logo
Documentation Powered by ReDoc

Common Room API (v2) (2.0.0)

Download OpenAPI specification:Download

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:

  1. Navigate to Setting | API tokens
  2. Create a "New Token"

Authentication

BearerAuth

Use a Core API JWT as a Bearer token in the Authentication header.

Tokens can be created by room Admins through https://app.commonroom.io/

Example:

curl -H "Authorization: Bearer abcd123.xzy" \
  https://api.commonroom.io/community/v1/api-token-status
Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Token Status

Operations related to API token status

API Token status information

Status information about the API token used in the request.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "jti": "tcpgph92",
  • "communityName": "Uncommon",
  • "communityId": "8p980hdo0"
}

Contacts

Operations related to contact management

Get a contact by ID

Retrieve a specific contact by their unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed contact ID (format c_<number>)

query Parameters
cols
string

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

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List contacts

Retrieve a list of contacts with pagination support.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of contacts to return per page

cursor
string

Pagination cursor from a previous response

sort
string
Default: "id"

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>).

direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction

cols
string

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.

organizationId
string

Filter contacts by prefixed organization ID (format o_<number>)

segmentId
string

Filter contacts by segment ID (e.g. s_123456)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Organizations

Operations related to organization management

Get an organization by ID

Retrieve a specific organization by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed organization ID (format o_<number>)

query Parameters
cols
string

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

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List organizations

Retrieve a list of organizations with pagination support.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of organizations to return per page

cursor
string

Pagination cursor from a previous response

sort
string
Default: "id"

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>).

direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction

cols
string

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
string

Filter organizations by exact name match

primaryDomain
string

Filter organizations by primary domain (exact match)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Activities

Operations related to activity events

Get an activity by ID

Retrieve a specific activity by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed activity ID (format a_<number>)

query Parameters
cols
string

Comma-separated list of additional columns to include in the response. Valid values: contactId, content, isUserInitiated, participantCount, providerId, providerName, replyCount, sentiment, subSourceNames, url.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List activities

Retrieve a list of activities with pagination support.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of activities to return per page

cursor
string

Pagination cursor from a previous response

sort
string
Default: "activityTime"
Enum: "id" "activityTime"

Field to sort results by.

direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction

cols
string

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.

contactId
string

Filter activities by prefixed contact ID (format c_<number>)

organizationId
string

Filter activities by prefixed organization ID (format o_<number>)

startDate
string <date-time>

Only return activities occurring at or after this ISO-8601 datetime

endDate
string <date-time>

Only return activities occurring at or before this ISO-8601 datetime

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

List activity types

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.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

List activity categories

List all activity category labels for the community.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

List activity sentiment labels

List all activity sentiment classifications for the community.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Segments

Operations related to segment management

Get a segment by ID

Retrieve a specific segment by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed segment ID (format s_<number>)

query Parameters
cols
string

Comma-separated list of additional columns to include in the response. Valid values: entityCount, url.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List segments

Retrieve a list of segments with pagination support.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of segments to return per page

cursor
string

Pagination cursor from a previous response

cols
string

Comma-separated list of additional columns to include in the response. Valid column values: entityCount, url. The meta column recordCount can be requested to return the total number of matching segments in meta.recordCount.

query
string

Filter segments by name (substring match)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Create a segment

Create a new segment in the community.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string

The name for the new segment (max 500 characters)

description
string

Optional description for the segment (markdown supported)

entityType
string
Default: "contact"
Enum: "contact" "object" "organization"

The type of entity this segment will contain

objectTypeId
string

Required when entityType is object. Prefixed object type ID (format cot_<number>)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "entityType": "contact",
  • "objectTypeId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Custom Fields

Operations related to custom field definitions

Get a custom field by ID

Retrieve a specific custom field definition by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed custom field ID (format cf_<number>)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List custom fields

Retrieve all custom field definitions for the community, optionally filtered by entity type.

Authorizations:
BearerAuth
query Parameters
entityType
string

Filter fields by entity type. Valid values: contact, organization, or a prefixed object type ID (format cot_<number>).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Lead Scores

Operations related to lead score definitions

Get a lead score definition by ID

Retrieve a specific lead score definition by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed lead score ID (format ls_<number>)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List lead score definitions

Retrieve all lead score definitions for the community.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Tags

Operations related to tags (labels)

Get a tag by ID

Retrieve a specific tag by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed tag ID (format l_<number>)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List tags

Retrieve a list of tags (user-defined and auto-generated) for the community, with pagination support.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of tags to return per page

cursor
string

Pagination cursor from a previous response

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Me

Information about the authenticated user

Get current user info

Retrieve information about the authenticated user, including their profile, bookmarked segments, personas, and company details.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Data Available

Notify Common Room that data is available for import

Notify data available

Notify Common Room that new data is available for import from a connected data source. This triggers import and augmentation workflows for the specified provider.

Authorizations:
BearerAuth
Request Body schema: application/json
sourceId
required
integer

The numeric provider ID of the data source

Responses

Request samples

Content type
application/json
{
  • "sourceId": 0
}

Response samples

Content type
application/json
{
  • "success": true
}

Locations

Operations related to location data

Get a location by ID

Retrieve a specific location by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed location ID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List locations

Retrieve a paginated list of locations, sorted by member count (descending).

Authorizations:
BearerAuth
query Parameters
locationType
required
string
Enum: "city" "country" "country_region" "world_region"

The granularity of locations to return (required)

limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of locations to return per page

cursor
string

Pagination cursor from a previous response

cols
string

Comma-separated list of meta columns. The meta column recordCount can be requested to return the total number of matching locations in meta.recordCount.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Topics

Operations related to topics

Get a topic by ID

Retrieve a specific topic by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed topic ID (format tp_<number>)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List topics

Retrieve a paginated list of topics, sorted alphabetically by name.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of topics to return per page

cursor
string

Pagination cursor from a previous response

query
string

Filter topics by display name prefix

cols
string

Comma-separated list of meta columns. The meta column recordCount can be requested to return the total number of matching topics in meta.recordCount.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Providers

Operations related to signal sources (integrations)

List providers

List the visible signal sources (integrations) for the community, with pagination support.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of providers to return per page

cursor
string

Pagination cursor from a previous response

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Objects

Operations related to custom objects

Get a custom object by ID

Retrieve a specific custom object by its unique identifier.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed custom object ID (format co_<number>)

query Parameters
cols
string

Comma-separated list of additional columns to include in the response. Valid values: recordKey. Use cf_* to include all custom fields, or cf_<id> for a specific one.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

List custom objects

Retrieve a paginated list of custom objects.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of objects to return per page

cursor
string

Pagination cursor from a previous response

sort
string
Default: "id"
Enum: "id" "name"

Field to sort results by

direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction

objectTypeId
required
string

Filter objects by prefixed object type ID (format cot_<number>)

segmentId
string

Filter objects by prefixed segment ID (format s_<number>)

cols
string

Comma-separated list of additional columns to include in the response. Valid column values: recordKey. Use cf_* to include all custom fields, or cf_<id> for a specific one. The meta column recordCount can be requested to return the total number of matching objects in meta.recordCount.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Object Types

Operations related to custom object type definitions

List object types

Retrieve all custom object type definitions for the community, including their associations to other entity types.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Website Visits

Operations related to website visit tracking

List website visits

Retrieve a paginated list of website visits.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of visits to return per page

cursor
string

Pagination cursor from a previous response

cols
string

Comma-separated list of additional columns to include in the response. Valid column values: url (included by default), contactId, organizationId. The meta column recordCount can be requested to return the total number of matching visits in meta.recordCount.

contactId
string

Filter visits by prefixed contact ID (format c_<number>)

organizationId
string

Filter visits by prefixed organization ID (format o_<number>)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Prospector Contacts

Operations related to prospector contact discovery

List prospector contacts

Retrieve a paginated list of prospector-discovered contacts.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of contacts to return per page

cursor
string

Pagination cursor from a previous response

sort
string
Default: "id"
Enum: "id" "name" "title" "linkedInFollowers" "lastOrgChange" "seniority" "role"

Field to sort results by

direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction

cols
string

Comma-separated list of additional columns to include in the response. Valid column values: avatarUrl, companyName, companyWebsite, fullName, linkedInFollowerCount, linkedInHandle, location, role, seniority, skills, title. The meta column recordCount can be requested to return the total number of matching contacts in meta.recordCount.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Prospector Companies

Operations related to prospector company discovery

List prospector companies

Retrieve a paginated list of prospector-discovered companies.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of companies to return per page

cursor
string

Pagination cursor from a previous response

sort
string
Default: "id"
Enum: "id" "name" "employeeCount" "capitalRaised" "score"

Field to sort results by

direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction

cols
string

Comma-separated list of additional columns to include in the response. Valid column values: description, employees, linkedInHandles, location, logoUrl, primaryWebsite, raised, revenueRange, subIndustry, technologies. The meta column recordCount can be requested to return the total number of matching companies in meta.recordCount.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Industries

Operations related to NAICS industry codes

List NAICS industry codes

Retrieve a paginated list of NAICS industry codes, optionally filtered by search query.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of codes to return per page

cursor
string

Pagination cursor from a previous response

query
string

Search text to filter industry codes by name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Tech Stack Products

Operations related to technographics and tech stack products

List tech stack products

Retrieve a paginated list of technographic products, optionally filtered by search query.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50

The maximum number of products to return per page

cursor
string

Pagination cursor from a previous response

query
string

Search text to filter products by name

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}