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

        '
      summary: Add or Edit Activity
      tags:
      - Activities
      operationId: addUpdateActivityToSource
      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/ApiActivity'
      responses:
        '202':
          description: OK - Activity 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'
  /activityTypes:
    get:
      description: 'Gets all activity types

        '
      summary: Get Activity Types
      tags:
      - Activities
      operationId: getActivityTypes
      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:
                    id:
                      type: string
                      example: started_training
                    displayName:
                      type: string
                      example: Started training
        '429':
          $ref: '#/components/responses/RateLimited'
  /activities/{id}:
    get:
      summary: Get an activity by ID
      description: Retrieve a specific activity by its unique identifier.
      tags:
      - Activities
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The prefixed activity ID (format `a_<number>`)
      - name: cols
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated list of additional columns to include in the response.

          Valid values: `contactId`, `content`, `isUserInitiated`, `participantCount`,

          `providerId`, `providerName`, `replyCount`, `sentiment`, `subSourceNames`,

          `url`.

          '
      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/ActivityResponse'
        '400':
          description: Bad Request (e.g. invalid activity 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: Activity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
  /activities:
    get:
      summary: List activities
      description: Retrieve a list of activities with pagination support.
      tags:
      - Activities
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: The maximum number of activities 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
          - activityTime
          default: activityTime
        description: Field to sort results by.
      - 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: `contactId`, `content`, `isUserInitiated`,

          `participantCount`, `providerId`, `providerName`, `replyCount`, `sentiment`,

          `subSourceNames`, `url`. The meta column `recordCount` can be

          requested to return the total number of matching activities in

          `meta.recordCount`.

          '
      - name: contactId
        in: query
        required: false
        schema:
          type: string
        description: Filter activities by prefixed contact ID (format `c_<number>`)
      - name: organizationId
        in: query
        required: false
        schema:
          type: string
        description: Filter activities by prefixed organization ID (format `o_<number>`)
      - name: startDate
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Only return activities occurring at or after this ISO-8601 datetime
      - name: endDate
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Only return activities occurring at or before this ISO-8601 datetime
      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/ActivityList'
        '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'
  /activity-types:
    get:
      summary: List activity types
      description: 'List all activity type identifiers supported by Common Room, along with

        their human-readable display names. Use the `id` as the `type` value

        returned by `/activities`.

        '
      tags:
      - Activities
      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/ActivityTypeList'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '429':
          $ref: '#/components/responses/RateLimited'
  /activity-categories:
    get:
      summary: List activity categories
      description: List all activity category labels for the community.
      tags:
      - Activities
      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/ActivityCategoryList'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '429':
          $ref: '#/components/responses/RateLimited'
  /activity-sentiment:
    get:
      summary: List activity sentiment labels
      description: List all activity sentiment classifications for the community.
      tags:
      - Activities
      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/ActivitySentimentList'
        '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.
    ApiActivityCategory:
      type: object
      required:
      - id
      - name
      - value
      properties:
        id:
          type: string
          description: Prefixed label ID (format `l_<number>`)
        name:
          type: string
          description: Display name for the category
        value:
          type: string
          description: Machine-readable category value
    ApiActivity:
      type: object
      description: Information about an activity that occurred
      properties:
        id:
          description: Unique identifier for the activity within this source. This ID must be unique for each individual activity, and should be generated by the third party system you are pulling data from (this ID does _not_ come from Common Room). Used to deduplicate and keep the latest values for a given activity when combined with the activityType.
          type: string
        activityType:
          description: Type of activity being added or edited. Check /activityTypes route for accepted values. Used to deduplicate and keep the latest values for a given activity when combined with the id.
          type: string
        user:
          $ref: '#/components/schemas/ApiUser'
        activityTitle:
          description: An optional title to use when rendering the activity. Useful for things like a post title, merge request title, etc.
          type: object
          oneOf:
          - $ref: '#/components/schemas/TextContent'
          discriminator:
            propertyName: type
            mapping:
              text: '#/components/schemas/TextContent'
          nullable: true
        content:
          description: Optional content to display when rendering the activity, used to hold a message which was posted or information about what occurred.
          type: object
          oneOf:
          - $ref: '#/components/schemas/TextContent'
          - $ref: '#/components/schemas/MarkdownContent'
          discriminator:
            propertyName: type
            mapping:
              text: '#/components/schemas/TextContent'
              markdown: '#/components/schemas/MarkdownContent'
          nullable: true
        timestamp:
          description: Time the activity occurred, in standard ISO 8601 format (YYYY-MM-DDThh:mm:ss.sssZ). Current UTC time is used if not supplied
          type: string
          format: date-time
        url:
          description: URL pointing to the activity on a third party source, allows linking from Common Room to the source activity
          type: string
          nullable: true
        tags:
          description: Optional list of activity tags to assign to this activity
          type: array
          items:
            $ref: '#/components/schemas/ApiTagAssignment'
        parentActivity:
          description: Optional field which allows for "conversational threading", structuring activities as nested, associated with or in reply to another activity.
          type: object
          properties:
            id:
              type: string
              description: Unique identifier of another activity which should be treated as a conversational "parent" of this activity.
            activityType:
              type: string
              description: Activity type of the parent activity
          required:
          - id
          - activityType
          nullable: true
        subSource:
          description: Optional "sub source" the activity took place in. This allows further sub-dividing the sources data into third-party concepts like a slack channel, github repository or meetup group. Common examples include a slack channel name, meetup group hosting an event, a github repo an issue was created in.
          type: object
          properties:
            type:
              type: string
              enum:
              - name
            name:
              type: string
              description: Name of the sub source
              example: slack-channel-1
          required:
          - type
          - name
          nullable: true
      required:
      - id
      - activityType
      - user
    ActivitySentimentList:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApiActivitySentiment'
    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
    TextContent:
      type: object
      properties:
        type:
          type: string
          enum:
          - text
        value:
          type: string
          description: Plain text content of the activity
      required:
      - type
      - value
    ApiV2ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ApiV2Error'
    MarkdownContent:
      type: object
      properties:
        type:
          type: string
          enum:
          - markdown
        value:
          type: string
          description: Markdown content of the activity
      required:
      - type
      - value
    ActivityResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          $ref: '#/components/schemas/ApiActivity_2'
    ActivityTypeList:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApiActivityType'
    ApiActivitySentiment:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Prefixed label ID (format `l_<number>`)
        name:
          type: string
          description: Display name for the sentiment (e.g. positive, negative, neutral)
    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.
                  - type: number
                    description: Only applicable for multi-value number custom fields.
                  - type: date
                    description: Only applicable for multivalue date custom fields.
                  - type: url
                    description: Only applicable for multivalue URL custom fields.
                  - type: boolean
                    description: Only applicable for multivalue boolean custom fields.
          required:
          - type
          - value
      required:
      - id
    ActivityList:
      type: object
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApiActivity_2'
        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.
    ApiActivity_2:
      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
    ActivityCategoryList:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          enum:
          - true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ApiActivityCategory'
    ApiActivityType:
      type: object
      required:
      - id
      - displayName
      properties:
        id:
          type: string
          description: Activity type identifier (e.g. `tweet`, `pr_comment`)
        displayName:
          type: string
          description: Human-readable display name for the activity type
    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-Limit:
      description: The total amount of requests permitted within the interval
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: The total amount of requests remaining within the interval
      schema:
        type: integer
  responses:
    InvalidRequest:
      description: Invalid Request
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
      content:
        application/json:
          schema:
            type: object
            properties:
              reason:
                type: string
                description: A reason of `invalid-request-body` indicates that the request body did not match the schema required by our API docs. Please double-check that your request body matches the schema above, and contact us for help if you continue to experience issues.
              docs:
                type: string
                description: A link to this API documentation
    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"