Common Room Contacts API

openapi: 3.0.0
info:
  title: Common Room Core Activities Contacts 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: Contacts
paths:
  /source/{destinationSourceId}/user:
    post:
      description: 'Adds a new user into the destination source, or updates existing user previously added via API with the same ID

        '
      summary: Add or Edit User
      tags:
      - Contacts
      operationId: addUpdateUserToSource
      parameters:
      - in: path
        name: destinationSourceId
        schema:
          type: integer
        required: true
        description: The Destination Source ID of the created API signal. See https://www.commonroom.io/docs/signals/custom-integrations/zapier-api/#create-an-api-signal for details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUser'
      responses:
        '202':
          description: OK - User info accepted and will be processed
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '404':
          description: Destination Source Not Found
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
        '429':
          $ref: '#/components/responses/RateLimited'
  /members/customFields:
    get:
      description: 'Gets all contact custom fields for a room

        '
      summary: Gets all contact custom fields for a room
      tags:
      - Contacts
      parameters:
      - in: query
        name: destinationSourceId
        schema:
          type: string
          description: If a value is provided provided, the API will only return custom fields that can be written to by the specified destination source
        required: false
      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:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - name
                  - type
                  - multivalue
                  properties:
                    id:
                      type: number
                      description: Custom field ID
                      example: 12345
                    name:
                      type: string
                      description: Custom field name
                      example: Preferred programming language
                    type:
                      type: string
                      description: Custom field type
                      example: enum
                    multivalue:
                      type: boolean
                      description: Whether the custom field accepts multiple assigned values
                      example: false
                    values:
                      type: array
                      description: Array of acceptable values if the custom field type is an `enum`.
                      items:
                        type: string
                        example: Python
  /user/{email}:
    summary: Represents a Contact
    description: 'Represents a Contact associated with an email address within the room

      identified by the authentication scheme.

      '
    parameters:
    - name: email
      schema:
        type: string
        format: email
        example: contact@example.commonroom.io
      in: path
      required: true
    get:
      summary: Get Contact by E-Mail
      deprecated: true
      description: A Contact's profile based on an email address.
      tags:
      - Contacts
      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:
                type: array
                items:
                  $ref: '#/components/schemas/CommunityMember'
        '404':
          description: Not Found
          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/Status'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      summary: Anonymize Contact
      description: 'Request removal of all personally identifiable information (PII) for the

        Contact associated by this email address.


        This does not immediately anonymize the contact. The anonymization

        is queued and will happen at a future time within 15 days.

        '
      tags:
      - Contacts
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#../'
              example:
                status: success
        '404':
          description: Not Found
          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/Status'
        '429':
          $ref: '#/components/responses/RateLimited'
  /members:
    parameters:
    - in: query
      name: twitter
      schema:
        type: string
        example: twitterHandle
    - in: query
      name: email
      schema:
        type: string
        example: email@domain.com
    - in: query
      name: github
      schema:
        type: string
        example: githubHandle
    - in: query
      name: linkedin
      schema:
        type: string
        example: in/username
    get:
      summary: Get Contact By E-Mail or Socials
      deprecated: true
      tags:
      - Contacts
      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:
                type: array
                items:
                  type: object
                  properties:
                    fullName:
                      type: string
                      example: Greg
                    activities_count:
                      type: number
                    avatar:
                      type: string
                      description: Avatar URL string
                    bio:
                      type: string
                    organization:
                      type: string
                    title:
                      type: string
                    first_seen:
                      type: string
                      description: Date when contact appeared in your room in ISO 8601 format
                    last_active:
                      type: string
                      description: Date of the contact's last activity in ISO 8601 format
                    location:
                      type: object
                    member_tags:
                      type: array
                    segments:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: number
                          name:
                            type: string
                    url:
                      type: string
                    twitter:
                      type: string
                    github:
                      type: string
                    linkedin:
                      type: string
                    discord:
                      type: string
                    youtube:
                      type: string
                    common_room_member_url:
                      type: string
                    custom_fields:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                          type:
                            type: string
                            description: enum, string, date, int, url, boolean
                            example: boolean
                          value:
                            description: Value of custom field
                            example: true
        '400':
          description: Parameter Error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
        '404':
          description: Not Found
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contacts/{id}:
    get:
      summary: Get a contact by ID
      description: Retrieve a specific contact by their unique identifier.
      tags:
      - Contacts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The prefixed contact ID (format `c_<number>`)
      - name: cols
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated list of additional columns to include in the response.

          Valid values: `activateMessage`, `avatarUrl`, `fullName`, `location`, `primaryEmail`,

          `phoneNumbers`, `title`, `companyName`, `companyWebsite`, `connectedCustomObjects`,

          `profiles`, `jobHistory`, `leadScores`, `recentActivities`, `recentWebPages`,

          `recentWebVisitsNumber`, `segments`, `sparkSummary`, `recentSparkSummaries`, `tags`,

          `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/ContactResponse'
        '400':
          description: Bad Request (e.g. invalid contact 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: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
  /contacts:
    get:
      summary: List contacts
      description: Retrieve a list of contacts with pagination support.
      tags:
      - Contacts
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: The maximum number of contacts 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`, `latest_activity`, `name`,

          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: `activateMessage`, `avatarUrl`, `fullName`, `location`,

          `primaryEmail`, `phoneNumbers`, `title`, `companyName`, `companyWebsite`,

          `connectedCustomObjects`, `profiles`, `jobHistory`, `leadScores`, `recentActivities`,

          `recentWebPages`, `recentWebVisitsNumber`, `segments`, `sparkSummary`,

          `recentSparkSummaries`, `tags`, `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 contacts in `meta.recordCount`.

          '
      - name: organizationId
        in: query
        required: false
        schema:
          type: string
        description: Filter contacts by prefixed organization ID (format `o_<number>`)
      - name: segmentId
        in: query
        required: false
        schema:
          type: string
        description: Filter contacts by segment ID (e.g. s_123456)
      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/ContactList'
        '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:
    ApiUser:
      type: object
      description: Information about a user. Provide as many fields as possible to enable better matching and merging into a single Common Room profile.
      properties:
        id:
          description: Unique identifier for the user within this source (identifier unrelated to Common Room). This ID must be unique for each individual user, and should be generated by the third party system you are pulling data from (this ID does _not_ come from Common Room). Used as the primary key for this user within this source, to group all the user's activity together.
          type: string
        fullName:
          description: The full name of the user.
          type: string
          nullable: true
        firstName:
          description: The first name of the user. Used if no full name given.
          type: string
          nullable: true
        lastName:
          description: The last name of the user. Used if no full name given.
          type: string
          nullable: true
        username:
          description: The username the user.
          type: string
          nullable: true
        avatarUrl:
          description: The url for the users avatar.
          type: string
          nullable: true
        bio:
          description: The biography for the user, to be used in the contact's "About" section.
          type: string
          nullable: true
        email:
          description: The email for the user, used to help enrich details about the person.
          type: string
          format: email
          nullable: true
        linkedin:
          description: Information about the users LinkedIn account
          type: object
          properties:
            type:
              type: string
              enum:
              - handle
            value:
              type: string
              description: Parsable value which includes the LinkedIn handle.
              example: in/person
          required:
          - type
          - value
          nullable: true
        github:
          description: Information about the users Github account
          type: object
          properties:
            type:
              type: string
              enum:
              - handle
            value:
              type: string
              description: Parsable value which includes their github handle, eg "Person" from https://github.com/Person
              example: Person
          required:
          - type
          - value
          nullable: true
        twitter:
          description: Information about the users Twitter account
          type: object
          properties:
            type:
              type: string
              enum:
              - handle
            value:
              type: string
              description: Parsable value which includes their twitter handle, eg @Person or Person
              example: '@Person'
          required:
          - type
          - value
          nullable: true
        discord:
          description: Information about the users Discord account, taken from the form username#discriminator
          type: object
          properties:
            type:
              type: string
              enum:
              - username
            username:
              type: string
              example: person
            discriminator:
              schema:
                anyOf:
                - type: string
                - type: number
              example: 1234
          required:
          - username
          - discriminator
          nullable: true
        externalProfiles:
          description: An optional list of known external profiles.
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                description: The url of the external profile referenced
              name:
                type: string
                description: The name to use when rendering the external profile url
            required:
            - url
          nullable: true
        roleAtCompany:
          description: The users role at their company, such as Engineering, Marketing, Sales
          type: string
          example: Engineering
          nullable: true
        titleAtCompany:
          description: The users title at their company
          type: string
          nullable: true
        companyName:
          description: The name of the users company
          type: string
          example: Common Room
          nullable: true
        companyDomain:
          description: The web domain of the users company
          type: string
          example: commonroom.io
          nullable: true
        country:
          description: The country the user resides in
          type: string
          nullable: true
        city:
          description: The city the user resides in
          type: string
          nullable: true
        region:
          description: The state, prefecture or region the user resides in, such as Washington, New York, Ontario, New South Whales
          type: string
          example: Washington
          nullable: true
        rawLocation:
          description: Loose description of a location to be interpreted, such as 'Seattle, WA', USA, Kyiv, Ukraine, Hong Kong
          type: string
          example: Seattle, WA
          nullable: true
        tags:
          description: Optional list of contact tags to assign to this user
          type: array
          items:
            $ref: '#/components/schemas/ApiTagAssignment'
        customFields:
          description: Optional list of custom fields to update for this user
          type: array
          items:
            $ref: '#/components/schemas/ApiCustomFields'
      required:
      - id
    ApiTagAssignment:
      type: object
      description: Optional List of tags to assign
      oneOf:
      - $ref: '#/components/schemas/ApiTagAssignmentById'
      - $ref: '#/components/schemas/ApiTagAssignmentByName'
      discriminator:
        propertyName: type
        mapping:
          id: '#/components/schemas/ApiTagAssignmentById'
          name: '#/components/schemas/ApiTagAssignmentByName'
    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.
    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
    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
    ApiTagAssignmentByName:
      type: object
      properties:
        type:
          type: string
          enum:
          - name
        name:
          description: 'Name of the tag to assign.


            This will assign an existing label if a matching one is found by name, otherwise a new label will be created and assigned.

            '
          type: string
      required:
      - type
      - name
    CommunityMember:
      CommunityMember:
        type: object
        properties:
          id:
            type: integer
            example: 147920
    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
    ApiV2ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ApiV2Error'
    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
    ContactList:
      type: object
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
        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.
    ApiTagAssignmentById:
      type: object
      properties:
        type:
          type: string
          enum:
          - id
        id:
          description: ID of the tag to assign, taken from the tag API
          type: string
      required:
      - type
      - id
    ApiCustomFields:
      type: object
      description: Optional list of custom fields to update
      properties:
        id:
          description: ID of the custom field to update which you can retrieve using the /members/customFields endpoint.
          type: number
        value:
          type: object
          description: 'The value of the custom field. Important: Omitting this field will clear the custom field value and cannot be undone.'
          properties:
            type:
              type: string
              description: The defined type of the custom field
              enum:
              - enum
              - string
              - date
              - int
              - number
              - url
              - boolean
              example: boolean
            value:
              description: The updated value of the custom field.
              example: true
              oneOf:
              - type: string
              - type: number
              - type: url
              - type: date
                description: Only supports ISO 8601 date format (YYYY-MM-DD).
              - type: boolean
              - type: array
                items:
                  oneOf:
                  - type: string
                    description: Only applicable for multivalue string custom fields.
                 

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/common-room/refs/heads/main/openapi/common-room-contacts-api-openapi.yml