Common Room Objects API

openapi: 3.2.0
info:
  title: Common Room API (v2) Objects API
  version: 2.0.0
  description: 'Common Room API v2 for accessing contact and organization data.


    For v1 and RTBF APIs see the V1 API documentation.


    To use the Common Room API, you will need to create an API token.

    To create an API token:


    Navigate to Setting | API tokens


    Create a "New Token"


    # Authentication


    -->'
  x-logo:
    url: /common-room-api-logo.svg
servers:
- url: https://api.commonroom.io/community/v2
  description: Common Room API v2
security:
- BearerAuth: []
tags:
- name: Objects
  description: Operations related to custom objects
paths:
  /objects/{id}:
    get:
      summary: Get a custom object by ID
      description: Retrieve a specific custom object by its unique identifier.
      tags:
      - Objects
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The prefixed custom object ID (format `co_<number>`)
      - name: cols
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated list of additional columns to include in the response.

          Valid values: `recordKey`. Use `cf_*` to include all custom fields,

          or `cf_<id>` for a specific one.

          '
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomObjectResponse'
        '400':
          description: Bad Request (e.g. invalid object ID or invalid parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '404':
          description: Object not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getObjectsById
      x-operation-id-source: derived
  /objects:
    get:
      summary: List custom objects
      description: Retrieve a paginated list of custom objects.
      tags:
      - Objects
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: The maximum number of objects to return per page
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor from a previous response
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - id
          - name
          default: id
        description: Field to sort results by
      - name: direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: Sort direction
      - name: objectTypeId
        in: query
        required: true
        schema:
          type: string
        description: Filter objects by prefixed object type ID (format `cot_<number>`)
      - name: segmentId
        in: query
        required: false
        schema:
          type: string
        description: Filter objects by prefixed segment ID (format `s_<number>`)
      - name: cols
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated list of additional columns to include in the response.

          Valid column values: `recordKey`. Use `cf_*` to include all custom fields,

          or `cf_<id>` for a specific one. The meta column `recordCount` can be

          requested to return the total number of matching objects in `meta.recordCount`.

          '
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomObjectList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getObjects
      x-operation-id-source: derived
components:
  schemas:
    CustomObjectList:
      type: object
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApiCustomObject'
        meta:
          type: object
          properties:
            nextCursor:
              type:
              - string
              - 'null'
              description: Cursor for pagination; pass as the `cursor` query parameter to fetch the next page.
            recordCount:
              type: integer
              description: Total number of records matching the query. Only returned when `cols=recordCount` is requested.
    ApiFieldValue:
      description: A typed custom-field value. The `type` discriminator indicates the value's runtime type.
      oneOf:
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - string
          value:
            type: string
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - url
          value:
            type: string
            format: uri
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - int
          value:
            type: integer
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - number
          value:
            type: number
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - date
          value:
            type: string
            format: date-time
      - type: object
        required:
        - type
        - value
        properties:
          type:
            type: string
            enum:
            - boolean
          value:
            type: boolean
    CustomObjectResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          $ref: '#/components/schemas/ApiCustomObject'
    ApiCustomObject:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Prefixed custom object ID (format `co_<number>`)
        name:
          type: string
          description: The object's display name
        recordKey:
          type: string
          description: External record key for this object
        customFields:
          type: object
          description: Map of custom-field ID (format `cf_<number>`) to its typed value.
          additionalProperties:
            $ref: '#/components/schemas/ApiFieldValue'
    ApiV2Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: A machine-readable error code identifying the failure.
          enum:
          - invalid_parameters
          - invalid_organization_id
          - org_not_found
          - invalid_contact_id
          - contact_not_found
          - invalid_object_id
          - object_not_found
          - invalid_object_type_id
          - object_type_not_found
          - invalid_segment_id
          - segment_not_found
          - invalid_activity_id
          - activity_not_found
          - conflict
          - internal_server_error
          - invalid_custom_field_id
          - custom_field_not_found
          - invalid_prospector_contact_id
          - prospector_contact_not_found
          - invalid_prospector_company_id
          - prospector_company_not_found
        message:
          type: string
          description: A human-readable description of the error.
    ApiV2ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ApiV2Error'
    Status:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
          - failure
          - not-found
          example: success
        reason:
          type: string
        errors:
          type: array
          items:
            type: string
          required:
          - status
      example:
        status: not created
        errors:
        - name is missing
  headers:
    X-RateLimit-Remaining:
      description: The total amount of requests remaining within the interval
      schema:
        type: integer
    X-RateLimit-Limit:
      description: The total amount of requests permitted within the interval
      schema:
        type: integer
  responses:
    RateLimited:
      description: Rate Limited
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          description: The datetime in epoch seconds when the interval resets
          schema:
            type: integer
        Retry-After:
          description: The UTC datetime when the interval resets
          schema:
            type: string
            format: date-time
      content:
        application/json:
          schema:
            type: object
            properties:
              reason:
                type: string
              rateLimit:
                type: object
                description: A summary of the rate limit encountered, additional information is available in the headers.
                properties:
                  intervalLimit:
                    type: number
                    description: The total amount of requests permitted within the interval
                  intervalRemaining:
                    type: number
                    description: The amount of requests remaining within the interval
                  intervalResetSeconds:
                    type: number
                    description: The amount of time in seconds representing a single interval
                  waitMs:
                    type: number
                    description: The amount of time to wait until the next interval
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Use a Core API JWT as a Bearer token in the Authentication header.\n\nTokens can be created by room Admins through https://app.commonroom.io/\n\nExample:\n\n```\ncurl -H \"Authorization: Bearer abcd123.xzy\" \\\n  https://api.commonroom.io/community/v1/api-token-status\n````\n"