Common Room Organizations API

openapi: 3.0.0
info:
  title: Common Room Core Activities Organizations API
  version: 1.0.0
  description: "Common Room Core REST APIs for getting data in to Common Room.\n<br/><br/>\nFor SCIM APIs <a href=\"./scim.html\">see the SCIM documentation</a>.\n<br/><br/>\nFor New, V2 APIs <a href=\"./api-v2.html\">see the V2 API documentation</a>.\n<br/><br/>\nTo use the Common Room API, or get started with the Common Room Zapier integration, you will need to create an API token.\nTo create an API token:\n<ol>\n  <li>Navigate to Setting | API tokens\n  <li>Create a “New Token\"\n</ol>\n\n# Authentication\n\n<!-- ReDoc-Inject: <security-definitions> -->"
  x-logo:
    url: /common-room-api-logo.svg
servers:
- url: https://api.commonroom.io/community/v1
  description: Common Room Core API v1
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'
  /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'
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
    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
    ApiV2ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ApiV2Error'
    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.
    OrganizationResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          $ref: '#/components/schemas/Organization'
    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
          nullable: true
        isUserInitiated:
          type: boolean
        participantCount:
          type: integer
        providerId:
          type: string
          description: Prefixed signal source ID (format `sig_<number>`)
        providerName:
          type: string
          nullable: true
        replyCount:
          type: integer
        sentiment:
          type: string
          nullable: true
        subSourceNames:
          type: array
          items:
            type: string
        url:
          type: string
          format: uri
    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
          nullable: true
        contactsCount:
          type: integer
          nullable: true
        employees:
          type: integer
          nullable: true
        linkedInUrl:
          type: string
          nullable: true
        profiles:
          type: array
          items:
            type: object
            required:
            - name
            - type
            - url
            properties:
              name:
                type: string
              type:
                type: string
              url:
                type: string
                format: uri
                nullable: true
        revenueRangeMax:
          type: integer
          nullable: true
        revenueRangeMin:
          type: integer
          nullable: true
        subIndustry:
          type: string
          nullable: true
        location:
          allOf:
          - $ref: '#/components/schemas/ApiLocation'
          nullable: true
        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
                nullable: true
              url:
                type: string
                format: uri
              firstSeenAt:
                type: string
              isClosed:
                type: boolean
              location:
                type: string
                nullable: true
        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
                nullable: true
        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
    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
    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
          format: uri
          nullable: true
        fullName:
          type: string
          nullable: true
        location:
          allOf:
          - $ref: '#/components/schemas/ApiLocation'
          nullable: true
        primaryEmail:
          type: string
          nullable: true
        phoneNumbers:
          type: array
          items:
            type: object
            required:
            - type
            - value
            properties:
              type:
                type: string
              value:
                type: string
        title:
          type: string
          nullable: true
        companyName:
          type: string
          nullable: true
        companyWebsite:
          type: string
          nullable: true
        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
                nullable: true
              startDate:
                type: string
              endDate:
                type: string
                nullable: true
        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
          nullable: true
          required:
          - title
          - message
          properties:
            title:
              type: string
            message:
              type: string
              nullable: true
        sparkSummary:
          type: string
          nullable: true
        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
    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
              nullable: true
              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.
    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"