Common Room Organizations API

openapi: 3.2.0
info:
  title: Common Room API (v2) Organizations 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: Organizations
  description: Operations related to organization management
paths:
  /organizations/{id}:
    get:
      summary: Get an organization by ID
      description: Retrieve a specific organization by its unique identifier.
      tags:
      - Organizations
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The prefixed organization ID (format `o_<number>`)
      - name: cols
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated list of additional columns to include in the response.

          Valid values: `about`, `contactsCount`, `employees`, `linkedInUrl`, `profiles`,

          `revenueRangeMax`, `revenueRangeMin`, `subIndustry`, `location`, `leadScores`,

          `recentJobOpenings`, `recentNews`, `researchResults`, `surgingTopics`, `tags`, `topContacts`, `url`.

          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/OrganizationResponse'
        '400':
          description: Bad Request (e.g. invalid organization 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: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getOrganizationsById
      x-operation-id-source: derived
  /organizations:
    get:
      summary: List organizations
      description: Retrieve a list of organizations with pagination support.
      tags:
      - Organizations
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: The maximum number of organizations 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
          default: id
        description: 'Field to sort results by. One of: `id`, `member_count`,

          a lead-score ID (format `ls_<number>`), or a custom-field ID (format `cf_<number>`).

          '
      - name: direction
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: Sort direction
      - name: cols
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated list of additional columns to include in the response.

          Valid column values: `about`, `contactsCount`, `employees`, `linkedInUrl`, `profiles`,

          `revenueRangeMax`, `revenueRangeMin`, `subIndustry`, `location`, `leadScores`,

          `recentJobOpenings`, `recentNews`, `researchResults`, `surgingTopics`, `tags`, `topContacts`, `url`.

          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

          organizations in `meta.recordCount`.

          '
      - name: name
        in: query
        required: false
        schema:
          type: string
        description: Filter organizations by exact name match
      - name: primaryDomain
        in: query
        required: false
        schema:
          type: string
        description: Filter organizations by primary domain (exact match)
      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/OrganizationList'
        '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: getOrganizations
      x-operation-id-source: derived
components:
  schemas:
    ApiLeadScore:
      type: object
      required:
      - scoreId
      - score
      - percentile
      properties:
        scoreId:
          type: integer
          description: The numeric ID of the lead-score definition
        score:
          type: number
          description: The raw score for this contact or organization
        percentile:
          type: number
          description: The percentile rank of the score within the community
    ApiLocation:
      type: object
      description: A best-effort location, with each component populated when known.
      properties:
        city:
          type: string
          description: City name
        region:
          type: string
          description: State, province, or region name
        country:
          type: string
          description: Country name
    ApiActivity:
      type: object
      required:
      - id
      - type
      - activityTime
      properties:
        id:
          type: string
          description: Prefixed activity ID (format `a_<number>`)
        type:
          type: string
          description: Activity type identifier (e.g. `tweet`, `pr_comment`)
        activityTime:
          type: string
          format: date-time
          description: When the activity occurred
        contactId:
          type: string
          description: Prefixed contact ID (format `c_<number>`)
        content:
          type:
          - string
          - 'null'
        isUserInitiated:
          type: boolean
        participantCount:
          type: integer
        providerId:
          type: string
          description: Prefixed signal source ID (format `sig_<number>`)
        providerName:
          type:
          - string
          - 'null'
        replyCount:
          type: integer
        sentiment:
          type:
          - string
          - 'null'
        subSourceNames:
          type: array
          items:
            type: string
        url:
          type: string
          format: uri
    OrganizationList:
      type: object
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Organization'
        meta:
          type: object
          required:
          - nextCursor
          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
    OrganizationResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          $ref: '#/components/schemas/Organization'
    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.
    Organization:
      type: object
      required:
      - id
      - name
      - primaryDomain
      properties:
        id:
          type: string
          description: Prefixed organization ID (format `o_<number>`)
        name:
          type: string
          description: The organization's name
        primaryDomain:
          type: string
          description: The organization's primary domain name
        about:
          type:
          - string
          - 'null'
        contactsCount:
          type:
          - integer
          - 'null'
        employees:
          type:
          - integer
          - 'null'
        linkedInUrl:
          type:
          - string
          - 'null'
        profiles:
          type: array
          items:
            type: object
            required:
            - name
            - type
            - url
            properties:
              name:
                type: string
              type:
                type: string
              url:
                type:
                - string
                - 'null'
                format: uri
        revenueRangeMax:
          type:
          - integer
          - 'null'
        revenueRangeMin:
          type:
          - integer
          - 'null'
        subIndustry:
          type:
          - string
          - 'null'
        location:
          allOf:
          - $ref: '#/components/schemas/ApiLocation'
        customFields:
          type: object
          description: Map of custom-field ID (format `cf_<number>`) to its typed value.
          additionalProperties:
            $ref: '#/components/schemas/ApiFieldValue'
        leadScores:
          type: array
          items:
            $ref: '#/components/schemas/ApiLeadScore'
        researchResults:
          type: array
          items:
            type: object
            required:
            - promptId
            - answer
            - isPrimaryPrompt
            properties:
              promptId:
                type: string
              answer:
                type: string
              isPrimaryPrompt:
                type: boolean
        recentJobOpenings:
          type: array
          items:
            type: object
            required:
            - jobTitle
            - url
            - firstSeenAt
            - isClosed
            - location
            properties:
              jobTitle:
                type: string
              jobDescription:
                type:
                - string
                - 'null'
              url:
                type: string
                format: uri
              firstSeenAt:
                type: string
              isClosed:
                type: boolean
              location:
                type:
                - string
                - 'null'
        recentNews:
          type: array
          items:
            type: object
            required:
            - title
            - url
            - publishedAt
            - category
            - articleSentence
            properties:
              title:
                type: string
              url:
                type: string
                format: uri
              publishedAt:
                type: string
              category:
                type: string
              articleSentence:
                type:
                - string
                - 'null'
        surgingTopics:
          type: array
          description: Bombora surging topic names this organization is showing buyer intent for. Empty unless the Bombora integration is enabled.
          items:
            type: string
        tags:
          type: array
          description: Prefixed label IDs (format `l_<number>`)
          items:
            type: string
        topContacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        url:
          type: string
          format: uri
          description: Common Room URL for this organization
    ApiV2ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ApiV2Error'
    Contact:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Prefixed contact ID (format `c_<number>`)
        name:
          type: string
          description: The contact's display name
        avatarUrl:
          type:
          - string
          - 'null'
          format: uri
        fullName:
          type:
          - string
          - 'null'
        location:
          allOf:
          - $ref: '#/components/schemas/ApiLocation'
        primaryEmail:
          type:
          - string
          - 'null'
        phoneNumbers:
          type: array
          items:
            type: object
            required:
            - type
            - value
            properties:
              type:
                type: string
              value:
                type: string
        title:
          type:
          - string
          - 'null'
        companyName:
          type:
          - string
          - 'null'
        companyWebsite:
          type:
          - string
          - 'null'
        connectedCustomObjects:
          type: array
          items:
            type: object
            required:
            - id
            - name
            - objectType
            properties:
              id:
                type: string
                description: Prefixed custom object ID (format `co_<number>`)
              name:
                type: string
              objectType:
                type: string
        customFields:
          type: object
          description: Map of custom-field ID (format `cf_<number>`) to its typed value.
          additionalProperties:
            $ref: '#/components/schemas/ApiFieldValue'
        profiles:
          type: array
          items:
            type: object
            required:
            - type
            - value
            properties:
              type:
                type: string
              value:
                type: string
        jobHistory:
          type: array
          items:
            type: object
            required:
            - company
            - title
            - startDate
            - endDate
            properties:
              company:
                type: string
              title:
                type:
                - string
                - 'null'
              startDate:
                type: string
              endDate:
                type:
                - string
                - 'null'
        leadScores:
          type: array
          items:
            $ref: '#/components/schemas/ApiLeadScore'
        segments:
          type: array
          items:
            type: object
            required:
            - id
            - name
            properties:
              id:
                type: string
                description: Prefixed segment ID (format `s_<number>`)
              name:
                type: string
        recentWebPages:
          type: array
          items:
            type: object
            required:
            - url
            - numVisits
            properties:
              url:
                type: string
              numVisits:
                type: integer
        recentWebVisitsNumber:
          type: integer
        recentActivities:
          type: array
          items:
            $ref: '#/components/schemas/ApiActivity'
        activateMessage:
          type:
          - object
          - 'null'
          required:
          - title
          - message
          properties:
            title:
              type: string
            message:
              type:
              - string
              - 'null'
        sparkSummary:
          type:
          - string
          - 'null'
        recentSparkSummaries:
          type: array
          items:
            type: string
        tags:
          type: array
          description: Prefixed label IDs (format `l_<number>`)
          items:
            type: string
        url:
          type: string
          format: uri
          description: Common Room URL for this contact
    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"