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"
}

Filtering

List endpoints such as GET /contacts, GET /organizations, GET /activities, and GET /objects/{objectTypeId} accept a lightFilter query parameter: the URL-encoded JSON of a LightFilterExpression. The filterable field names and the operators each accepts are listed in the lightFilter parameter of each endpoint; the shared grammar is documented here.

Example — contacts in a segment who were active in the last 30 days:

{
  "type": "and",
  "clauses": [
    { "type": "stringListFilter", "field": "memberSegmentId", "params": { "op": "any", "value": ["s_123456"] } },
    { "type": "dateRangeFilter", "field": "memberLastActivity", "params": { "op": "in", "value": "P30D", "min": null, "max": null } }
  ]
}
type
required
string
Enum: "and" "or"

How to combine top-level clauses: "and" = all must match, "or" = any can match

required
Array of any (LightFilterClause) non-empty

Array of filter conditions — leaf clauses or nested groups.

{
  • "type": "and",
  • "clauses": [
    ]
}

Contacts

Operations related to contact management

Update many contacts

Apply the same change to up to 100 contacts in one request. The request must include at least one of segmentId, tagIdsToAdd, tagIdsToRemove, or customFields. Every ID, the segment, the tags, and the custom fields are validated before anything is written, and an error names every offending ID. Each change is idempotent: contacts already in the segment are skipped, so a request that fails part-way can be retried as a whole. Requires the contacts:write scope.

Authorizations:
BearerAuth
Request Body schema: application/json
contactIds
required
Array of strings [ 1 .. 100 ] items

Prefixed contact IDs (format c_<number>). Duplicates are ignored.

segmentId
string

Add every contact to this segment (format s_<number>).

tagIdsToAdd
Array of strings <= 25 items

Tag IDs (format l_<number>) to add to every record.

tagIdsToRemove
Array of strings <= 25 items

Tag IDs (format l_<number>) to remove from every record.

Array of objects (BulkCustomFieldUpdates) non-empty

Custom-field values to set on every record in the request.

Responses

Request samples

Content type
application/json
{
  • "contactIds": [
    ],
  • "segmentId": "string",
  • "tagIdsToAdd": [
    ],
  • "tagIdsToRemove": [
    ],
  • "customFields": [
    ]
}

Response samples

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

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, leadScoreKeyFactors, recentActivities, recentWebPages, recentWebVisitsNumber, segments, sparkSummary, recentSparkSummaries, tags, url, activityCount7d, activityCount28d, activityCount8w, activityCount12w, activityCount6m, activityCount1y, activityCountAll. 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 .. 1000 ]
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>), a custom-field ID (format cf_<number>), or an activity-count sort: activity_count_7d, activity_count_28d, activity_count_8w, activity_count_12w, activity_count_6m, activity_count_1y, activity_count_all. Activity-count sorts rank contacts by number of activities in that trailing window; use direction=desc and request the matching activityCount* column to see the counts.

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, leadScoreKeyFactors, recentActivities, recentWebPages, recentWebVisitsNumber, segments, sparkSummary, recentSparkSummaries, tags, url, activityCount7d, activityCount28d, activityCount8w, activityCount12w, activityCount6m, activityCount1y, activityCountAll. 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)

object (LightFilterExpression)

Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters.

Filterable fields:

Field Filter type Operators Description
memberHasEmail booleanFilter eq, ne Filter contacts by whether they have an email address.
isTeamMember booleanFilter eq, ne Filter contacts by whether they are a teammate (workspace user).
memberHasPrimaryEmail booleanFilter eq, ne Filter contacts by whether they have a primary email.
memberHasPrimaryBusinessEmail booleanFilter eq, ne Filter contacts by whether they have a primary business email.
memberHasPhoneNumber booleanFilter eq, ne Filter contacts by whether they have a phone number.
memberHasPrimaryPhoneNumber booleanFilter eq, ne Filter contacts by whether they have a primary phone number.
memberHasPremiumPhoneNumber booleanFilter eq, ne Filter contacts by whether they have a premium phone number.
memberRole stringListFilter any, none Filter contacts by job role — case-insensitive free text matched against the contact's stored role (e.g. "Software Engineer", "VP of Sales"), not a fixed category list. Discover the role values present in this workspace via GET /member-roles (most common roles, ranked by contact count). For normalized seniority buckets use memberSeniority.
memberSeniority stringListFilter any, none Filter contacts by normalized job seniority. Valid values: Intern, Junior IC, Senior IC, Manager, Director, VP, C-Level.
memberEmail stringFilter eq, like Filter contacts by email. Pass a full address ("needshelp@acme.com") for exact case-insensitive lookup, or a domain ("acme.com" / "@acme.com") to match anyone on that domain.
memberEmailDomain stringListFilter any, none Filter contacts by email domain. Performs exact domain matching — "mail.com" will not match "gmail.com". Pass one or more domains without the "@" prefix (e.g., ["acme.com", "example.org"]).
companyName stringFilter eq, like Filter contacts by their company/organization name (e.g., "Acme Corp").
companyWebsite stringFilter eq, like Filter contacts by their company/organization website domain (e.g., "acme.com").
fullName stringFilter eq, like Filter contacts by name
title stringFilter eq, like, empty, notEmpty Filter contacts by job title; empty/notEmpty (with a null value) match contacts without or with any title.
memberSegmentId stringListFilter any, all, none Filter by segment (play) membership. Use segment IDs from GET /segments.
groupId stringListFilter any, none Filter by organization membership. Use organization IDs from GET /organizations.
memberLabelId stringListFilter any, all, none Filter contacts by tag/label ID(s). Use tag IDs from GET /tags (e.g., "l_131504").
locationId stringListFilter any, none Filter contacts by location ID(s). Use location IDs from GET /locations.
memberLeadScorePercentile leadScoreFilter eq, ne, gt, gte, lt, lte Filter contacts by lead score percentile (0-100). Requires a scoreId from GET /lead-scores.
ls_* numberFilter eq, ne, gt, gte, lt, lte Filter contacts by a Point Value lead score's raw point total, using the score ID as the field name. May be negative or fractional. Only scores whose outputType is point_value match; use memberLeadScorePercentile for percentile scores.
memberWebVisitLastSeen dateRangeFilter in, between, after, before Filter contacts by when they last visited the website.
memberWebVisitFirstSeen dateRangeFilter in, between, after, before Filter contacts by when they first visited the website.
memberWebVisitPageViews numberFilter eq, ne, gt, gte, lt, lte Filter contacts by total tracked web page-view count (all-time).
memberWebVisitPagesViewed webVisitPages any, none Filter contacts by which web pages they visited within a window. Provide page URL patterns, an interval (ISO 8601 duration, e.g. "P30D"), and optional minimum page views.
memberLastActivity dateRangeFilter in, between, after, before Filter contacts by when they were last active.
memberJobChangedAt dateRangeFilter in, between, after, before Filter contacts by when they changed jobs (started at a new company). Prefer a window with op in and an ISO 8601 duration (e.g. "P90D" for the last 90 days). Job changes are typically detected within a few months of the change taking place.
cf_* stringFilter varies by field type Filter by custom field value. Use the custom field ID (e.g., "cf_123456") as the field name. Find field IDs and their types via GET /custom-fields. Supports stringFilter for text fields, stringListFilter for enum/dropdown fields, numberFilter for numeric fields, booleanFilter for checkbox fields, and dateRangeFilter for date fields.

Responses

Response samples

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

Organizations

Operations related to organization management

Update many organizations

Apply the same change to up to 100 organizations in one request. The request must include at least one of segmentId, tagIdsToAdd, tagIdsToRemove, or customFields. Every ID, the segment, the tags, and the custom fields are validated before anything is written, and an error names every offending ID. Each change is idempotent: organizations already in the segment are skipped, so a request that fails part-way can be retried as a whole. Requires the organizations:write scope.

Authorizations:
BearerAuth
Request Body schema: application/json
organizationIds
required
Array of strings [ 1 .. 100 ] items

Prefixed organization IDs (format o_<number>). Duplicates are ignored.

segmentId
string

Add every organization to this segment (format s_<number>).

tagIdsToAdd
Array of strings <= 25 items

Tag IDs (format l_<number>) to add to every record.

tagIdsToRemove
Array of strings <= 25 items

Tag IDs (format l_<number>) to remove from every record.

Array of objects (BulkCustomFieldUpdates) non-empty

Custom-field values to set on every record in the request.

Responses

Request samples

Content type
application/json
{
  • "organizationIds": [
    ],
  • "segmentId": "string",
  • "tagIdsToAdd": [
    ],
  • "tagIdsToRemove": [
    ],
  • "customFields": [
    ]
}

Response samples

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

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, leadScoreKeyFactors, 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 .. 1000 ]
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, leadScoreKeyFactors, 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)

object (LightFilterExpression)

Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters.

Filterable fields:

Field Filter type Operators Description
companyName stringFilter eq, like Filter organizations by name.
companyWebsite stringFilter eq, like Filter organizations by website domain (e.g., "acme.com").
groupSegmentId stringListFilter any, all, none Filter organizations by segment membership. Use segment IDs from GET /segments.
groupLabelId stringListFilter any, all, none Filter organizations by tag/label ID(s). Use tag IDs from GET /tags (e.g., "l_131504").
groupLocationId stringListFilter any, none Filter organizations by location ID(s). Use location IDs from GET /locations.
groupSubIndustry stringListFilter any, all, none Filter organizations by industry label (e.g. "Software", "Financial Services").
groupMemberCount numberFilter eq, ne, gt, gte, lt, lte Filter organizations by number of members
groupRevenue numberFilter gt, gte, lt, lte Filter organizations by estimated annual revenue. Lower bounds match the estimate's floor, upper bounds its ceiling.
groupCompanySize numberFilter eq, ne, gt, gte, lt, lte Filter organizations by company size (number of employees)
groupLeadScorePercentile leadScoreFilter eq, ne, gt, gte, lt, lte Filter organizations by lead score percentile (0-100). Requires a scoreId from GET /lead-scores.
ls_* numberFilter eq, ne, gt, gte, lt, lte Filter organizations by a Point Value lead score's raw point total, using the score ID as the field name. May be negative or fractional. Only scores whose outputType is point_value match; use groupLeadScorePercentile for percentile scores.
groupWebVisitLastSeen dateRangeFilter in, between, after, before Filter organizations by when anyone from the org last visited the website.
groupWebVisitFirstSeen dateRangeFilter in, between, after, before Filter organizations by when anyone from the org first visited the website.
groupWebVisitPageViews numberFilter eq, ne, gt, gte, lt, lte Filter organizations by total tracked web page-view count (all-time).
groupWebVisitPagesViewed webVisitPages any, none Filter organizations by which web pages were visited within a window. Provide page URL patterns, an interval (ISO 8601 duration, e.g. "P30D"), and optional minimum page views.
groupNaicsCode stringListFilter any, none Filter organizations by NAICS industry code(s). Values are numeric string codes (e.g. "517", "5112"). Discover codes via GET /industries. For industry labels instead, use groupSubIndustry.
groupTechStackId stringListFilter any, all, none Filter organizations by tech stack product ID(s). Use product IDs from GET /tech-stack-products.
surgingTopics stringListFilter any, none, notEmpty Filter organizations by Bombora surging topic name(s) — research topics the org is showing buying intent on (e.g. "Customer Data Platform", "Marketing Automation"). Pass topic names, not IDs; notEmpty (with a null value) matches organizations surging on any topic.
cf_* stringFilter varies by field type Filter by custom field value. Use the custom field ID (e.g., "cf_3166091") as the field name. Find field IDs and their types via GET /custom-fields. Supports stringFilter for text fields, stringListFilter for enum/dropdown fields, numberFilter for numeric fields, booleanFilter for checkbox fields, and dateRangeFilter for date fields.

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 .. 1000 ]
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

object (LightFilterExpression)

Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters. To filter by contact or organization, use the dedicated contactId / organizationId query parameters above.

Filterable fields:

Field Filter type Operators Description
activityTime dateRangeFilter in, between, after, before Filter activities by time range
activityType stringListFilter any, none Filter activities by activity type ID. Use PascalCase enum names returned in activity records (e.g., "SlackPost", "GitHubIssueOpen").
activityProviderId stringListFilter any, none Filter activities by provider ID. Use provider IDs from GET /providers to discover available sources (e.g., Gong, Salesforce, Slack).
activityTopic stringListFilter any, all, none, empty, notEmpty Filter activities by topic IDs. Use GET /topics to list available topics.
activityKeyword stringListFilter any, all, none Keyword search across activity content
activityCategory stringListFilter any, all, none, empty, notEmpty Filter activities by auto-category label IDs. Use GET /activity-categories to find IDs.
activitySentiment stringListFilter any, all, none, empty, notEmpty Filter activities by sentiment label IDs. Use GET /activity-sentiment to find IDs.
activityIsParent booleanFilter eq, ne Filter activities by whether they are parent activities (conversations)
activityIsUserInitiated booleanFilter eq, ne Filter activities by whether they were initiated by the contact.
activityIsTeamMember booleanFilter eq, ne Filter activities by whether the contact who performed them is a teammate (workspace user).

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

Rename a segment

Update the name of an existing segment without changing its ID, entity type, or memberships.

Authorizations:
BearerAuth
path Parameters
id
required
string

The prefixed segment ID (format s_<number>)

Request Body schema: application/json
name
required
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

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

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 .. 1000 ]
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 .. 1000 ]
Default: 50

The maximum number of tags to return per page

cursor
string

Pagination cursor from a previous response

query
string

Filter tags by a case-insensitive substring of their name

entityType
string
Enum: "contact" "organization" "activity"

Filter tags by the type of entity they can be applied to

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 .. 1000 ]
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 .. 1000 ]
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 .. 1000 ]
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

Update many custom objects

Apply the same change to up to 100 custom objects in one request. The request must include at least one of segmentId or customFields. Every ID, the segment, the tags, and the custom fields are validated before anything is written, and an error names every offending ID. Each change is idempotent: custom objects already in the segment are skipped, so a request that fails part-way can be retried as a whole. Requires the objects:write scope.

Authorizations:
BearerAuth
Request Body schema: application/json
objectIds
required
Array of strings [ 1 .. 100 ] items

Prefixed custom object IDs (format co_<number>). Duplicates are ignored.

segmentId
string

Add every custom object to this segment (format s_<number>).

Array of objects (BulkCustomFieldUpdates) non-empty

Custom-field values to set on every record in the request.

Responses

Request samples

Content type
application/json
{
  • "objectIds": [
    ],
  • "segmentId": "string",
  • "customFields": [
    ]
}

Response samples

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

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, 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": {
    }
}

Update custom fields on a custom object

Set Common Room custom-field values on a custom object record.

Authorizations:
BearerAuth
path Parameters
id
required
string

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

Request Body schema: application/json
required
Array of objects non-empty

Responses

Request samples

Content type
application/json
{
  • "customFields": [
    ]
}

Response samples

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

Add a custom object to a segment

Add a custom object record to an existing object segment.

Authorizations:
BearerAuth
path Parameters
id
required
string

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

Request Body schema: application/json
segmentId
required
string

The prefixed segment ID (format s_<number>)

Responses

Request samples

Content type
application/json
{
  • "segmentId": "string"
}

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 .. 1000 ]
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, 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 objects in meta.recordCount.

object (LightFilterExpression)

Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters.

Filterable fields:

Field Filter type Operators Description
objectSegmentId stringListFilter any, all, none Filter objects by segment membership. Use segment IDs from GET /segments.
objectRecordKey stringListFilter any, all, none Filter objects by record keys
objectName stringFilter eq, like Filter objects by name
objectLeadScorePercentile leadScoreFilter eq, ne, gt, gte, lt, lte Filter objects by lead score percentile (0-100). Requires a scoreId from GET /lead-scores.
ls_* numberFilter eq, ne, gt, gte, lt, lte Filter objects by a Point Value lead score's raw point total, using the score ID as the field name. May be negative or fractional. Only scores whose outputType is point_value match; use objectLeadScorePercentile for percentile scores.
cf_* stringFilter varies by field type Filter by custom field value. Use the custom field ID (e.g., "cf_123456") as the field name. Find field IDs and their types via GET /custom-fields. Supports stringFilter for text fields, stringListFilter for enum/dropdown fields, numberFilter for numeric fields, booleanFilter for checkbox fields, and dateRangeFilter for date fields.

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

object (LightFilterExpression)

Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters. To filter by contact or organization, use the dedicated contactId / organizationId query parameters above.

Filterable fields:

Field Filter type Operators Description
visitTime dateRangeFilter in, between, after, before Filter website visits by time range.
url stringFilter eq, like Filter website visits by URL. Use like for partial match (contains).

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 .. 1000 ]
Default: 50

The maximum number of contacts 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: 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.

object (LightFilterExpression)

Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters.

Filterable fields:

Field Filter type Operators Description
fullName stringFilter eq, like, empty, notEmpty Filter prospector contacts by name.
title stringFilter eq, like Filter prospector contacts by job title.
companyName stringFilter eq, like Filter prospector contacts by their current company name.
companyDomain stringFilter eq, like Filter prospector contacts by their current company domain/website (e.g., "acme.com").
locationId stringListFilter any, none, empty, notEmpty Filter prospector contacts by location. Discover location IDs via GET /locations.
previousCompanyName stringFilter eq, like Filter prospector contacts by their previous company/organization name.
previousCompanyDomain stringFilter eq, like Filter prospector contacts by their previous company/organization domain/website (e.g., "acme.com").
linkedInFollowerCount numberFilter eq, ne, gt, gte, lt, lte Filter prospector contacts by LinkedIn follower count.
lastOrgChange dateRangeFilter in, between, after, before Filter prospector contacts by when they last changed organizations (job change date).

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 .. 1000 ]
Default: 50

The maximum number of companies 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: 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.

object (LightFilterExpression)

Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters.

Filterable fields:

Field Filter type Operators Description
groupName stringFilter eq, like Filter prospector companies by name.
groupLinkedinHandle stringListFilter any, none Filter prospector companies by LinkedIn handle.
groupWebsite stringFilter eq, like Filter prospector companies by primary website/domain (e.g., "acme.com").
groupSubIndustry stringListFilter any, none, empty, notEmpty Filter prospector companies by industry label (e.g. "Software", "Healthcare"). Not to be confused with groupIndustryCode which filters by NAICS code.
groupCompanySize numberFilter eq, ne, gte, lte Filter prospector companies by employee count.
groupRevenue numberFilter gt, gte, lt, lte Filter prospector companies by estimated annual revenue. Lower bounds match the estimate's floor, upper bounds its ceiling.
groupCapitalRaised numberFilter eq, ne, gt, gte, lt, lte Filter prospector companies by total capital raised.
groupLocationId stringListFilter any, all, none, empty, notEmpty Filter prospector companies by location ID(s). Use location IDs from GET /locations.
groupIndustryCode stringListFilter any, all, none, empty, notEmpty Filter prospector companies by NAICS industry code. Discover codes via GET /industries. Values are numeric strings (e.g. "517", "5112"). Not to be confused with groupSubIndustry which filters by industry label.
groupTechStackId stringListFilter any, all, none Filter prospector companies by tech stack product ID(s). Look up product IDs via GET /tech-stack-products.
technographicsIntensity numberFilter gte, lte Filter prospector companies by technology usage intensity score.
technographicsFirstSeen dateRangeFilter in, between, after, before Filter prospector companies by when a technology was first detected.
technographicsLastSeen dateRangeFilter in, between, after, before Filter prospector companies by when a technology was last detected.
jobOpeningKeyword stringListFilter any, all, none Filter companies by job listing keyword search. Finds companies with job openings matching the given keywords.
jobOpeningTitle stringListFilter any, all, none Filter companies by job listing title.
jobOpeningStatus stringFilter eq Filter companies by job opening status. Values: 'open', 'closed'.
jobOpeningSeniority stringListFilter any, none Filter companies by job seniority level. Values: owner, founder, c_level, partner, president, vice_president, head, director, manager, non_manager, mid_senior, junior.
jobOpeningFirstSeen dateRangeFilter in, between, after, before Filter companies by the date a job opening was originally published or first discovered.
jobOpeningLastSeen dateRangeFilter in, between, after, before Filter companies by the most recent date a job opening was still observed as active. Use this to find companies whose listings are currently live or were recently open.
jobOpeningGeolocation stringListFilter any, none Filter prospector companies by job opening location ID(s). Use location IDs from GET /locations.
newsKeyword stringListFilter any, all, none Filter companies by news keyword search. Finds companies with news articles matching the given keywords.
newsCategory stringListFilter any, none Filter companies by news category. Values: hires, promotes, leaves, acquires, merges_with, launches, receives_financing, partners_with, expands_offices_to, and more.
newsPublishedAt dateRangeFilter in, between, after, before Filter companies by news publication date.

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 .. 1000 ]
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 .. 1000 ]
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": {
    }
}

Metadata

List job title suggestions

Authorizations:
BearerAuth
query Parameters
query
string

Optional prefix used to filter job titles.

limit
integer [ 1 .. 1000 ]
Default: 50

The maximum number of job titles to return per page, up to 1000.

cursor
string

Opaque best-effort cursor from a previous response. Reuse a cursor with the same sort and direction; concurrent writes may affect pagination consistency.

sort
string
Default: "alphabetical"
Enum: "popularity" "alphabetical"

Leading sort factor. Popularity orders by count with raw job title ascending as the tie-breaker; alphabetical orders by raw job title with count descending as the tie-breaker.

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

Direction for the leading sort factor. Defaults to desc for popularity and asc for alphabetical.

Responses

Response samples

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

Buying Committee

List buying committee cells

Retrieve the materialized buying committee cells for one organization. The full committee is returned in a single response — this endpoint is not paginated. Cells are returned in the same seniority-row and department-column order as the product. Every cell includes its full bounded list of available ranked contacts.

A buying committee must already be configured in the workspace. The token must grant organizations:read, contacts:read, and prospector:read (or the encompassing read scope).

Candidates are a ranked sample using up to five engagement-ranked and five recently touched candidates per cell, not every eligible person. Prospector emails are intentionally withheld and returned as null, matching the buying committee view in the product. Cells without available candidates have an empty contacts array.

meta.nextCursor is always null. Pagination parameters, sorting, filters other than organizationId, and retrieving a cell by ID are not supported.

Example request:

curl --get 'https://api.commonroom.io/api/v2/buying-committee-cells' \
  --header "Authorization: Bearer $COMMON_ROOM_API_TOKEN" \
  --data-urlencode 'organizationId=o_123' \
  --data-urlencode 'cols=recordCount'
Authorizations:
BearerAuth
query Parameters
organizationId
required
string^o_[0-9]+$
Example: organizationId=o_123

Organization ID in the authenticated workspace whose buying committee should be read

cols
string

Comma-separated columns. Use recordCount to include the materialized cell count in response metadata. Contacts and other cell fields are always returned.

Responses

Response samples

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

Job Openings

List job openings

Retrieve a paginated list of job postings for one organization or custom object. Exactly one of organizationId or objectId is required: postings live in a corpus keyed by company domain, so they are only readable within the scope of a record you already have.

Authorizations:
BearerAuth
query Parameters
organizationId
string

Prefixed organization ID (format o_<number>) whose job openings to read. Required unless objectId is given.

objectId
string

Prefixed custom object ID (format co_<number>) whose job openings to read. Resolves through the object's associated organization, falling back to the object's own domain. Required unless organizationId is given. Using this parameter also requires the objects:read scope.

limit
integer [ 1 .. 1000 ]
Default: 50

The maximum number of job openings 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 value: jobDescription. The meta column recordCount can be requested to return the total number of matching job openings in meta.recordCount.

sort
string
Value: "firstSeenAt"

Sort field

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

Sort direction

object (LightFilterExpression)

Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters. An organizationId or objectId clause inside the filter is hoisted to the corresponding query parameter, so the required scope can be supplied either way.

Filterable fields:

Field Filter type Operators Description
organizationId stringFilter eq Scope the results to one organization (this or objectId, exactly one — as a filter clause or the query parameter). Use organization IDs from GET /organizations (format o_<number>).
objectId stringFilter eq Scope the results to the organization associated with one custom object, falling back to the object's own domain (this or organizationId, exactly one). Use object IDs from GET /objects (format co_<number>).
jobOpeningKeyword stringListFilter any, all, none Free-text search over job title and description. Applies a workspace-configured recency and status window (open postings first seen in roughly the last 28 days by default); use jobOpeningTitle, jobOpeningFirstSeen, or jobOpeningStatus when the window must be explicit and predictable.
jobOpeningTitle stringListFilter any, all, none Filter job openings by title.
jobOpeningStatus stringFilter eq Filter job openings by status. Valid values: open, closed.
jobOpeningSeniority stringListFilter any, none Filter job openings by seniority level. Valid values: owner, founder, c_level, partner, president, vice_president, head, director, manager, non_manager, mid_senior, junior. The seniority itself is not returned as a column.
jobOpeningFirstSeen dateRangeFilter in, between, after, before Filter job openings by the date the posting was originally published or first discovered.
jobOpeningLastSeen dateRangeFilter in, between, after, before Filter job openings by the most recent date the posting was still observed as active.
jobOpeningGeolocation stringListFilter any, none Filter job openings by location ID(s). Use location IDs from GET /locations.

Responses

Response samples

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

News Items

List news items

Retrieve a paginated list of news articles for one organization or custom object. Exactly one of organizationId or objectId is required: articles live in a corpus keyed by company domain, so they are only readable within the scope of a record you already have.

Authorizations:
BearerAuth
query Parameters
organizationId
string

Prefixed organization ID (format o_<number>) whose news items to read. Required unless objectId is given.

objectId
string

Prefixed custom object ID (format co_<number>) whose news items to read. Resolves through the object's associated organization, falling back to the object's own domain. Required unless organizationId is given. Using this parameter also requires the objects:read scope.

limit
integer [ 1 .. 1000 ]
Default: 50

The maximum number of news items to return per page

cursor
string

Pagination cursor from a previous response

cols
string

News items have no opt-in columns; every field is always returned. The meta column recordCount can be requested to return the total number of matching news items in meta.recordCount.

sort
string
Value: "publishedAt"

Sort field

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

Sort direction

object (LightFilterExpression)

Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters. An organizationId or objectId clause inside the filter is hoisted to the corresponding query parameter, so the required scope can be supplied either way.

Filterable fields:

Field Filter type Operators Description
organizationId stringFilter eq Scope the results to one organization (this or objectId, exactly one — as a filter clause or the query parameter). Use organization IDs from GET /organizations (format o_<number>).
objectId stringFilter eq Scope the results to the organization associated with one custom object, falling back to the object's own domain (this or organizationId, exactly one). Use object IDs from GET /objects (format co_<number>).
newsKeyword stringListFilter any, all, none Free-text search over the article title and body. Operator none excludes the matching articles. Applies a workspace-configured recency window (roughly the last 28 days by default) that a newsPublishedAt clause cannot widen — use newsCategory with newsPublishedAt to search further back.
newsCategory stringListFilter any, none Filter news items by category. Values include: hires, promotes, leaves, acquires, merges_with, launches, receives_financing, partners_with, expands_offices_to, and more.
newsPublishedAt dateRangeFilter in, between, after, before Filter news items by publication date.

Responses

Response samples

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