{
"openapi": "3.0.0",
"info": {
"title": "Common Room API (v2)",
"version": "2.0.0",
"description": "Common Room API v2 for accessing contact and organization data.\n
\nFor v1 and RTBF APIs see the V1 API documentation.\n
\nThe OpenAPI spec for this API is available as JSON at api-v2.json.\n
\nTo use the Common Room API, you will need to create an API token.\nTo create an API token:\n\n - Navigate to Setting | API tokens\n
- Create a \"New Token\"\n
\n",
"x-logo": {
"url": "/common-room-api-logo.svg"
}
},
"servers": [
{
"url": "https://api.commonroom.io/api/v2",
"description": "Common Room API v2 Production Server"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Token Status",
"description": "Operations related to API token status"
},
{
"name": "Filtering",
"description": "List endpoints such as `GET /contacts`, `GET /organizations`, `GET /activities`,\nand `GET /objects/{objectTypeId}` accept a `lightFilter` query parameter: the\nURL-encoded JSON of a `LightFilterExpression`. The filterable `field` names and\nthe operators each accepts are listed in the `lightFilter` parameter of each\nendpoint; the shared grammar is documented here.\n\nExample — contacts in a segment who were active in the last 30 days:\n\n```json\n{\n \"type\": \"and\",\n \"clauses\": [\n { \"type\": \"stringListFilter\", \"field\": \"memberSegmentId\", \"params\": { \"op\": \"any\", \"value\": [\"s_123456\"] } },\n { \"type\": \"dateRangeFilter\", \"field\": \"memberLastActivity\", \"params\": { \"op\": \"in\", \"value\": \"P30D\", \"min\": null, \"max\": null } }\n ]\n}\n```\n\n\n"
},
{
"name": "Contacts",
"description": "Operations related to contact management"
},
{
"name": "Organizations",
"description": "Operations related to organization management"
},
{
"name": "Activities",
"description": "Operations related to activity events"
},
{
"name": "Segments",
"description": "Operations related to segment management"
},
{
"name": "Custom Fields",
"description": "Operations related to custom field definitions"
},
{
"name": "Lead Scores",
"description": "Operations related to lead score definitions"
},
{
"name": "Tags",
"description": "Operations related to tags (labels)"
},
{
"name": "Me",
"description": "Information about the authenticated user"
},
{
"name": "Data Available",
"description": "Notify Common Room that data is available for import"
},
{
"name": "Locations",
"description": "Operations related to location data"
},
{
"name": "Topics",
"description": "Operations related to topics"
},
{
"name": "Providers",
"description": "Operations related to signal sources (integrations)"
},
{
"name": "Objects",
"description": "Operations related to custom objects"
},
{
"name": "Object Types",
"description": "Operations related to custom object type definitions"
},
{
"name": "Website Visits",
"description": "Operations related to website visit tracking"
},
{
"name": "Prospector Contacts",
"description": "Operations related to prospector contact discovery"
},
{
"name": "Prospector Companies",
"description": "Operations related to prospector company discovery"
},
{
"name": "Industries",
"description": "Operations related to NAICS industry codes"
},
{
"name": "Tech Stack Products",
"description": "Operations related to technographics and tech stack products"
},
{
"name": "Privacy",
"description": "Privacy requests, such as right-to-be-forgotten erasure"
},
{
"name": "Analytics",
"description": "Operations related to team-reporting metrics"
}
],
"paths": {
"/api-token-status": {
"get": {
"summary": "API Token status information",
"description": "Status information about the API token used in the request.\n",
"tags": [
"Token Status"
],
"responses": {
"200": {
"description": "Core API Token Information",
"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/ApiToken"
}
}
}
},
"403": {
"description": "Forbidden",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status",
"example": {
"status": "forbidden"
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/job-titles": {
"get": {
"summary": "List job title suggestions",
"tags": [
"Metadata"
],
"parameters": [
{
"name": "query",
"in": "query",
"schema": {
"type": "string"
},
"description": "Optional prefix used to filter job titles."
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of job titles to return per page, up to 1000."
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string"
},
"description": "Opaque best-effort cursor from a previous response. Reuse a cursor with the same sort and direction; concurrent writes may affect pagination consistency."
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"popularity",
"alphabetical"
],
"default": "alphabetical"
},
"description": "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."
},
{
"name": "direction",
"in": "query",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
},
"description": "Direction for the leading sort factor. Defaults to desc for popularity and asc for alphabetical."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobTitleList"
}
}
}
},
"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"
}
}
}
},
"/contacts/bulk": {
"post": {
"summary": "Update many contacts",
"description": "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.",
"tags": [
"Contacts"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"contactIds"
],
"properties": {
"contactIds": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Prefixed contact IDs (format `c_`). Duplicates are ignored.",
"items": {
"type": "string"
}
},
"segmentId": {
"type": "string",
"description": "Add every contact to this segment (format `s_`)."
},
"tagIdsToAdd": {
"type": "array",
"maxItems": 25,
"description": "Tag IDs (format `l_`) to add to every record.",
"items": {
"type": "string"
}
},
"tagIdsToRemove": {
"type": "array",
"maxItems": 25,
"description": "Tag IDs (format `l_`) to remove from every record.",
"items": {
"type": "string"
}
},
"customFields": {
"$ref": "#/components/schemas/BulkCustomFieldUpdates"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The contacts were updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkUpdateResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "A contact, the segment, or a tag was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/contacts/{id}": {
"get": {
"summary": "Get a contact by ID",
"description": "Retrieve a specific contact by their unique identifier.",
"tags": [
"Contacts"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed contact ID (format `c_`)"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid values: `activateMessage`, `avatarUrl`, `fullName`, `location`, `primaryEmail`,\n`phoneNumbers`, `title`, `companyName`, `companyWebsite`, `linkedInUrls`, `gitHubUrls`,\n`xUrls`, `connectedCustomObjects`, `profiles`, `jobHistory`, `fullJobHistory`, `jobChangeDate`,\n`currentCompany`, `previousCompany`, `leadScores`, `leadScoreKeyFactors`, `recentActivities`,\n`recentWebPages`,\n`recentWebVisitsNumber`, `segments`, `sparkSummary`, `recentSparkSummaries`, `tags`,\n`url`, `activityCount7d`, `activityCount28d`, `activityCount8w`, `activityCount12w`,\n`activityCount6m`, `activityCount1y`, `activityCountAll`. Use `cf_*` to include all\ncustom fields, or `cf_` for a specific one.\n"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid contact ID or invalid parameters)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Contact not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"summary": "Delete a contact",
"description": "Delete a contact from the workspace, the same way deleting a contact in the Common Room app does. If the contact was merged into another contact, the contact it was merged into is deleted. Deleting a contact that is already deleted succeeds. Contacts who can log in to the workspace cannot be deleted. This is not a privacy erasure; for right-to-be-forgotten requests use `POST /right-to-be-forgotten-requests`. Requires the `contacts:write` scope and a role that can delete contacts.",
"tags": [
"Contacts"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed contact ID (format `c_`)"
}
],
"responses": {
"204": {
"description": "The contact was deleted"
},
"400": {
"description": "Invalid contact ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden, or the role cannot delete contacts",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"404": {
"description": "Contact not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"409": {
"description": "The contact can log in to the workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/contacts": {
"get": {
"summary": "List contacts",
"description": "Retrieve a list of contacts with pagination support.",
"tags": [
"Contacts"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of contacts to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "id"
},
"description": "Field to sort results by. One of: `id`, `latest_activity`, `name`,\na lead-score ID (format `ls_`), a custom-field ID (format `cf_`),\nor an activity-count sort: `activity_count_7d`, `activity_count_28d`,\n`activity_count_8w`, `activity_count_12w`, `activity_count_6m`,\n`activity_count_1y`, `activity_count_all`. Activity-count sorts rank contacts\nby number of activities in that trailing window; use `direction=desc` and\nrequest the matching `activityCount*` column to see the counts.\n"
},
{
"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.\nValid column values: `activateMessage`, `avatarUrl`, `fullName`, `location`,\n`primaryEmail`, `phoneNumbers`, `title`, `companyName`, `companyWebsite`, `linkedInUrls`,\n`gitHubUrls`, `xUrls`, `connectedCustomObjects`, `profiles`, `jobHistory`, `fullJobHistory`, `jobChangeDate`,\n`currentCompany`, `previousCompany`, `leadScores`, `leadScoreKeyFactors`,\n`recentActivities`,\n`recentWebPages`, `recentWebVisitsNumber`, `segments`, `sparkSummary`,\n`recentSparkSummaries`, `tags`, `url`, `activityCount7d`, `activityCount28d`,\n`activityCount8w`, `activityCount12w`, `activityCount6m`, `activityCount1y`,\n`activityCountAll`. Use `cf_*` to include all custom fields, or `cf_` for\na specific one. The meta column `recordCount` can be requested to return the\ntotal number of matching contacts in `meta.recordCount`.\n"
},
{
"name": "organizationId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter contacts by prefixed organization ID (format `o_`)"
},
{
"name": "segmentId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter contacts by segment ID (e.g. s_123456)"
},
{
"name": "lightFilter",
"in": "query",
"required": false,
"description": "Structured filter as URL-encoded JSON — see the `LightFilterExpression`\nschema for the grammar. Conditions are combined (AND) with the other\nquery parameters.\n\nFilterable fields:\n\n| Field | Filter type | Operators | Description |\n|---|---|---|---|\n| `memberHasEmail` | `booleanFilter` | `eq`, `ne` | Filter contacts by whether they have an email address. |\n| `isTeamMember` | `booleanFilter` | `eq`, `ne` | Filter contacts by whether they are a teammate (workspace user). |\n| `memberHasPrimaryEmail` | `booleanFilter` | `eq`, `ne` | Filter contacts by whether they have a primary email. |\n| `memberHasPrimaryBusinessEmail` | `booleanFilter` | `eq`, `ne` | Filter contacts by whether they have a primary business email. |\n| `memberHasPhoneNumber` | `booleanFilter` | `eq`, `ne` | Filter contacts by whether they have a phone number. |\n| `memberHasPrimaryPhoneNumber` | `booleanFilter` | `eq`, `ne` | Filter contacts by whether they have a primary phone number. |\n| `memberHasPremiumPhoneNumber` | `booleanFilter` | `eq`, `ne` | Filter contacts by whether they have a premium phone number. |\n| `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. |\n| `memberSeniority` | `stringListFilter` | `any`, `none` | Filter contacts by normalized job seniority. Valid values: Intern, Junior IC, Senior IC, Manager, Director, VP, C-Level. |\n| `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. |\n| `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\"]). |\n| `companyName` | `stringFilter` | `eq`, `like` | Filter contacts by their company/organization name (e.g., \"Acme Corp\"). |\n| `companyWebsite` | `stringFilter` | `eq`, `like` | Filter contacts by their company/organization website domain (e.g., \"acme.com\"). |\n| `fullName` | `stringFilter` | `eq`, `like` | Filter contacts by name |\n| `title` | `stringFilter` | `eq`, `like`, `empty`, `notEmpty` | Filter contacts by job title; `empty`/`notEmpty` (with a null value) match contacts without or with any title. |\n| `memberSegmentId` | `stringListFilter` | `any`, `all`, `none` | Filter by segment (play) membership. Use segment IDs from `GET /segments`. |\n| `groupId` | `stringListFilter` | `any`, `none` | Filter by organization membership. Use organization IDs from `GET /organizations`. |\n| `memberLabelId` | `stringListFilter` | `any`, `all`, `none` | Filter contacts by tag/label ID(s). Use tag IDs from `GET /tags` (e.g., \"l_131504\"). |\n| `locationId` | `stringListFilter` | `any`, `none` | Filter contacts by location ID(s). Use location IDs from `GET /locations`. |\n| `memberLeadScorePercentile` | `leadScoreFilter` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte` | Filter contacts by lead score percentile (0-100). Requires a scoreId from `GET /lead-scores`. |\n| `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. |\n| `memberWebVisitLastSeen` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter contacts by when they last visited the website. |\n| `memberWebVisitFirstSeen` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter contacts by when they first visited the website. |\n| `memberWebVisitPageViews` | `numberFilter` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte` | Filter contacts by total tracked web page-view count (all-time). |\n| `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. |\n| `memberLastActivity` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter contacts by when they were last active. |\n| `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. |\n| `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. |\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightFilterExpression"
},
"examples": {
"contactsInSegment": {
"summary": "Contacts in a specific segment",
"value": {
"type": "and",
"clauses": [
{
"type": "stringListFilter",
"field": "memberSegmentId",
"params": {
"op": "any",
"value": [
"s_1"
]
}
}
]
}
},
"contactsInTopLeadScore": {
"summary": "Contacts with lead score in the top 25%",
"value": {
"type": "and",
"clauses": [
{
"type": "leadScoreFilter",
"field": "memberLeadScorePercentile",
"params": {
"op": "gte",
"value": 75,
"scoreId": "ls_123"
}
}
]
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactList"
}
}
}
},
"400": {
"description": "Bad Request — also returned for malformed filters, e.g.\n\"Invalid lightFilter: must be valid JSON\", \"Invalid lightFilter: does\nnot match LightFilterExpression schema\", or an unknown filter field.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"delete": {
"summary": "Delete many contacts",
"description": "Delete up to 100 contacts in one request, the same way deleting contacts in the Common Room app does. The `ids` parameter is required; this endpoint never deletes all contacts. Every ID is validated before anything is deleted, and an error names every offending ID. A merged contact ID deletes the contact it was merged into. Contacts that are already deleted are skipped, so a request can be retried as a whole. Contacts who can log in to the workspace cannot be deleted. This is not a privacy erasure; for right-to-be-forgotten requests use `POST /right-to-be-forgotten-requests`. Requires the `contacts:write` scope and a role that can delete contacts.",
"tags": [
"Contacts"
],
"parameters": [
{
"name": "ids",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Comma-separated list of 1 to 100 prefixed contact IDs (format `c_`). Duplicates are ignored."
}
],
"responses": {
"200": {
"description": "The contacts were deleted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteContactsResponse"
}
}
}
},
"400": {
"description": "Missing `ids`, more than 100 IDs, or an invalid ID (for example `c_1.5` or `c_abc`)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden, or the role cannot delete contacts",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"404": {
"description": "A contact was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"409": {
"description": "A contact can log in to the workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/right-to-be-forgotten-requests": {
"post": {
"summary": "Create a right-to-be-forgotten request",
"description": "Request erasure of a person's data under a privacy law such as the GDPR or CCPA.\nUse this endpoint only for privacy / right-to-be-forgotten requests. To remove\ncontacts as routine data cleanup, use `DELETE /contacts` instead.\n\nA right-to-be-forgotten request is **irreversible**:\n- every contact in the workspace with this email is anonymized;\n- customer data synced with this email as the contact identifier (for example from\n a data warehouse, Census, Hightouch or a batch import) is permanently blocked from\n being imported again.\n\nRequests are processed daily. Poll\n`GET /right-to-be-forgotten-requests/{id}` (the `Location` header) to see when\na request has been processed. The email is never returned by the API.\n\nRequires the `contacts:write` scope and a role that can create\nright-to-be-forgotten requests.\n",
"tags": [
"Privacy"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"description": "The email address to erase, at most 254 characters. Matching is case-insensitive."
}
}
}
}
}
},
"responses": {
"202": {
"description": "The request was accepted and will be processed",
"headers": {
"Location": {
"description": "The URL of the created request",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RightToBeForgottenRequestResponse"
}
}
}
},
"400": {
"description": "Missing or invalid email, or an email longer than 254 characters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden, or the role cannot create right-to-be-forgotten requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"409": {
"description": "The email belongs to a contact who can log in to the workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/right-to-be-forgotten-requests/{id}": {
"get": {
"summary": "Get a right-to-be-forgotten request",
"description": "Retrieve the status of a right-to-be-forgotten request. The email is never returned. Requires the `contacts:read` scope.",
"tags": [
"Privacy"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed request ID (format `rtbf_`)"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RightToBeForgottenRequestResponse"
}
}
}
},
"400": {
"description": "Invalid request ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Request not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/organizations/bulk": {
"post": {
"summary": "Update many organizations",
"description": "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.",
"tags": [
"Organizations"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"organizationIds"
],
"properties": {
"organizationIds": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Prefixed organization IDs (format `o_`). Duplicates are ignored.",
"items": {
"type": "string"
}
},
"segmentId": {
"type": "string",
"description": "Add every organization to this segment (format `s_`)."
},
"tagIdsToAdd": {
"type": "array",
"maxItems": 25,
"description": "Tag IDs (format `l_`) to add to every record.",
"items": {
"type": "string"
}
},
"tagIdsToRemove": {
"type": "array",
"maxItems": 25,
"description": "Tag IDs (format `l_`) to remove from every record.",
"items": {
"type": "string"
}
},
"customFields": {
"$ref": "#/components/schemas/BulkCustomFieldUpdates"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The organizations were updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkUpdateResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "A organization, the segment, or a tag was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/organizations/{id}": {
"get": {
"summary": "Get an organization by ID",
"description": "Retrieve a specific organization by its unique identifier.",
"tags": [
"Organizations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed organization ID (format `o_`)"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid values: `about`, `contactsCount`, `employees`, `linkedInUrl`, `profiles`,\n`revenueRangeMax`, `revenueRangeMin`, `subIndustry`, `technologies`, `location`,\n`leadScores`,\n`leadScoreKeyFactors`,\n`recentJobOpenings`, `recentNews`, `researchResults`, `surgingTopics`, `tags`, `topContacts`, `url`.\nUse `cf_*` to include all custom fields, or `cf_` for a specific one.\n"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid organization ID or invalid parameters)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Organization not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/organizations": {
"get": {
"summary": "List organizations",
"description": "Retrieve a list of organizations with pagination support.",
"tags": [
"Organizations"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of organizations to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "id"
},
"description": "Field to sort results by. One of: `id`, `member_count`,\na lead-score ID (format `ls_`), or a custom-field ID (format `cf_`).\n"
},
{
"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.\nValid column values: `about`, `contactsCount`, `employees`, `linkedInUrl`, `profiles`,\n`revenueRangeMax`, `revenueRangeMin`, `subIndustry`, `technologies`, `location`,\n`leadScores`,\n`leadScoreKeyFactors`,\n`recentJobOpenings`, `recentNews`, `researchResults`, `surgingTopics`, `tags`, `topContacts`, `url`.\nUse `cf_*` to include all custom fields, or `cf_` for a specific one. The meta\ncolumn `recordCount` can be requested to return the total number of matching\norganizations in `meta.recordCount`.\n"
},
{
"name": "name",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter organizations by exact name match"
},
{
"name": "primaryDomain",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter organizations by primary domain (exact match)"
},
{
"name": "lightFilter",
"in": "query",
"required": false,
"description": "Structured filter as URL-encoded JSON — see the `LightFilterExpression`\nschema for the grammar. Conditions are combined (AND) with the other\nquery parameters.\n\nFilterable fields:\n\n| Field | Filter type | Operators | Description |\n|---|---|---|---|\n| `companyName` | `stringFilter` | `eq`, `like` | Filter organizations by name. |\n| `companyWebsite` | `stringFilter` | `eq`, `like` | Filter organizations by website domain (e.g., \"acme.com\"). |\n| `groupSegmentId` | `stringListFilter` | `any`, `all`, `none` | Filter organizations by segment membership. Use segment IDs from `GET /segments`. |\n| `groupLabelId` | `stringListFilter` | `any`, `all`, `none` | Filter organizations by tag/label ID(s). Use tag IDs from `GET /tags` (e.g., \"l_131504\"). |\n| `groupLocationId` | `stringListFilter` | `any`, `none` | Filter organizations by location ID(s). Use location IDs from `GET /locations`. |\n| `groupSubIndustry` | `stringListFilter` | `any`, `all`, `none` | Filter organizations by industry label (e.g. \"Software\", \"Financial Services\"). |\n| `groupMemberCount` | `numberFilter` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte` | Filter organizations by number of members |\n| `groupRevenue` | `numberFilter` | `gt`, `gte`, `lt`, `lte` | Filter organizations by estimated annual revenue. Lower bounds match the estimate's floor, upper bounds its ceiling. |\n| `groupCompanySize` | `numberFilter` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte` | Filter organizations by company size (number of employees) |\n| `groupLeadScorePercentile` | `leadScoreFilter` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte` | Filter organizations by lead score percentile (0-100). Requires a scoreId from `GET /lead-scores`. |\n| `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. |\n| `groupWebVisitLastSeen` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter organizations by when anyone from the org last visited the website. |\n| `groupWebVisitFirstSeen` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter organizations by when anyone from the org first visited the website. |\n| `groupWebVisitPageViews` | `numberFilter` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte` | Filter organizations by total tracked web page-view count (all-time). |\n| `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. |\n| `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. |\n| `groupTechStackId` | `stringListFilter` | `any`, `all`, `none` | Filter organizations by tech stack product ID(s). Use product IDs from `GET /tech-stack-products`. |\n| `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. |\n| `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. |\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightFilterExpression"
},
"examples": {
"organizationsWith100Members": {
"summary": "Organizations with 100+ members",
"value": {
"type": "and",
"clauses": [
{
"type": "numberFilter",
"field": "groupMemberCount",
"params": {
"op": "gte",
"value": 100
}
}
]
}
},
"organizationsBySubIndustry": {
"summary": "Organizations in the Software or Financial Services industry",
"value": {
"type": "and",
"clauses": [
{
"type": "stringListFilter",
"field": "groupSubIndustry",
"params": {
"op": "any",
"value": [
"Software",
"Financial Services"
]
}
}
]
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationList"
}
}
}
},
"400": {
"description": "Bad Request — also returned for malformed filters, e.g.\n\"Invalid lightFilter: must be valid JSON\", \"Invalid lightFilter: does\nnot match LightFilterExpression schema\", or an unknown filter field.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"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_`)"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid values: `contactId`, `content`, `isUserInitiated`, `participantCount`,\n`providerId`, `providerName`, `replyCount`, `sentiment`, `subSourceNames`,\n`url`.\n"
}
],
"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": 1000,
"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.\nValid column values: `contactId`, `content`, `isUserInitiated`,\n`participantCount`, `providerId`, `providerName`, `replyCount`, `sentiment`,\n`subSourceNames`, `url`. The meta column `recordCount` can be\nrequested to return the total number of matching activities in\n`meta.recordCount`.\n"
},
{
"name": "contactId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter activities by prefixed contact ID (format `c_`)"
},
{
"name": "organizationId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter activities by prefixed organization ID (format `o_`)"
},
{
"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"
},
{
"name": "lightFilter",
"in": "query",
"required": false,
"description": "Structured filter as URL-encoded JSON — see the `LightFilterExpression`\nschema for the grammar. Conditions are combined (AND) with the other\nquery parameters. To filter by contact or organization, use the\ndedicated `contactId` / `organizationId` query parameters above.\n\nFilterable fields:\n\n| Field | Filter type | Operators | Description |\n|---|---|---|---|\n| `activityTime` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter activities by time range |\n| `activityType` | `stringListFilter` | `any`, `none` | Filter activities by activity type ID. Use PascalCase enum names returned in activity records (e.g., \"SlackPost\", \"GitHubIssueOpen\"). |\n| `activityProviderId` | `stringListFilter` | `any`, `none` | Filter activities by provider ID. Use provider IDs from `GET /providers` to discover available sources (e.g., Gong, Salesforce, Slack). |\n| `activityTopic` | `stringListFilter` | `any`, `all`, `none`, `empty`, `notEmpty` | Filter activities by topic IDs. Use `GET /topics` to list available topics. |\n| `activityKeyword` | `stringListFilter` | `any`, `all`, `none` | Keyword search across activity content |\n| `activityCategory` | `stringListFilter` | `any`, `all`, `none`, `empty`, `notEmpty` | Filter activities by auto-category label IDs. Use `GET /activity-categories` to find IDs. |\n| `activitySentiment` | `stringListFilter` | `any`, `all`, `none`, `empty`, `notEmpty` | Filter activities by sentiment label IDs. Use `GET /activity-sentiment` to find IDs. |\n| `activityIsParent` | `booleanFilter` | `eq`, `ne` | Filter activities by whether they are parent activities (conversations) |\n| `activityIsUserInitiated` | `booleanFilter` | `eq`, `ne` | Filter activities by whether they were initiated by the contact. |\n| `activityIsTeamMember` | `booleanFilter` | `eq`, `ne` | Filter activities by whether the contact who performed them is a teammate (workspace user). |\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightFilterExpression"
},
"examples": {
"activitiesLast7Days": {
"summary": "Activities from the last 7 days",
"value": {
"type": "and",
"clauses": [
{
"type": "dateRangeFilter",
"field": "activityTime",
"params": {
"op": "in",
"value": "P7D",
"min": null,
"max": null
}
}
]
}
},
"activitiesFromProvider": {
"summary": "Activities from a specific provider",
"value": {
"type": "and",
"clauses": [
{
"type": "stringListFilter",
"field": "activityProviderId",
"params": {
"op": "any",
"value": [
"sig_123"
]
}
}
]
}
}
}
}
}
}
],
"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 — also returned for malformed filters, e.g.\n\"Invalid lightFilter: must be valid JSON\", \"Invalid lightFilter: does\nnot match LightFilterExpression schema\", or an unknown filter field.\n",
"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\ntheir human-readable display names. Use the `id` as the `type` value\nreturned by `/activities`.\n",
"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"
}
}
}
},
"/segments/{id}": {
"patch": {
"summary": "Rename a segment",
"description": "Update the name of an existing segment without changing its ID, entity type, or memberships.",
"tags": [
"Segments"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed segment ID (format `s_`)"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 500
}
}
}
}
}
},
"responses": {
"200": {
"description": "Segment renamed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateObjectResponse"
}
}
}
},
"400": {
"description": "Invalid segment ID or name",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"404": {
"description": "Segment not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"409": {
"description": "A segment with the requested name already exists",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
},
"get": {
"summary": "Get a segment by ID",
"description": "Retrieve a specific segment by its unique identifier.",
"tags": [
"Segments"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed segment ID (format `s_`)"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid values: `entityCount`, `url`, `summary`, `automationStatus`.\n"
}
],
"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/SegmentResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid segment 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": "Segment not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/segments": {
"get": {
"summary": "List segments",
"description": "Retrieve a list of segments with pagination support.",
"tags": [
"Segments"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of segments to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid column values: `entityCount`, `url`, `summary`, `automationStatus`. The meta column `recordCount`\ncan be requested to return the total number of matching segments in\n`meta.recordCount`.\n"
},
{
"name": "query",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter segments by name (substring match)"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {
"X-RateLimit-Limit": {
"$ref": "#/components/headers/X-RateLimit-Limit"
},
"X-RateLimit-Remaining": {
"$ref": "#/components/headers/X-RateLimit-Remaining"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SegmentList"
}
}
}
},
"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"
}
}
},
"post": {
"summary": "Create a segment",
"description": "Create a new segment in the community.",
"tags": [
"Segments"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSegmentRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"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/CreateSegmentResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid parameters or missing required fields)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"409": {
"description": "Conflict (a segment with this name already exists)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/custom-fields/{id}": {
"get": {
"summary": "Get a custom field by ID",
"description": "Retrieve a specific custom field definition by its unique identifier.",
"tags": [
"Custom Fields"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed custom field ID (format `cf_`)"
}
],
"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/CustomFieldResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid custom field ID)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Custom field not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/custom-fields": {
"get": {
"summary": "List custom fields",
"description": "Retrieve all custom field definitions for the community, optionally\nfiltered by entity type.\n",
"tags": [
"Custom Fields"
],
"parameters": [
{
"name": "entityType",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter fields by entity type. Valid values: `contact`, `organization`,\nor a prefixed object type ID (format `cot_`).\n"
}
],
"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/CustomFieldList"
}
}
}
},
"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"
}
}
}
},
"/lead-scores/{id}": {
"get": {
"summary": "Get a lead score definition by ID",
"description": "Retrieve a specific lead score definition by its unique identifier.",
"tags": [
"Lead Scores"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed lead score ID (format `ls_`)"
}
],
"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/LeadScoreDefinitionResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid lead score ID)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Lead score not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/lead-scores": {
"get": {
"summary": "List lead score definitions",
"description": "Retrieve all lead score definitions for the community.",
"tags": [
"Lead Scores"
],
"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/LeadScoreDefinitionList"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/tags/{id}": {
"get": {
"summary": "Get a tag by ID",
"description": "Retrieve a specific tag by its unique identifier.",
"tags": [
"Tags"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed tag ID (format `l_`)"
}
],
"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/TagResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid tag ID)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Tag not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/tags": {
"get": {
"summary": "List tags",
"description": "Retrieve a list of tags (user-defined and auto-generated) for the community, with pagination support.",
"tags": [
"Tags"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of tags to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "query",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter tags by a case-insensitive substring of their name"
},
{
"name": "entityType",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"contact",
"organization",
"activity",
"object"
]
},
"description": "Filter tags by the type of entity they can be applied to"
}
],
"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/TagList"
}
}
}
},
"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"
}
}
}
},
"/me": {
"get": {
"summary": "Get current user info",
"description": "Retrieve information about the authenticated user, including their profile,\nbookmarked segments, personas, and company details.\n",
"tags": [
"Me"
],
"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/MeResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/data-available": {
"post": {
"summary": "Notify data available",
"description": "Notify Common Room that new data is available for import from a connected\ndata source. This triggers import and augmentation workflows for the\nspecified provider.\n",
"tags": [
"Data Available"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"sourceId"
],
"properties": {
"sourceId": {
"type": "integer",
"description": "The numeric provider ID of the data source"
}
}
}
}
}
},
"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": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
}
}
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid or missing sourceId)",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [
false
]
},
"message": {
"type": "string"
}
},
"required": [
"success",
"message"
]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Source does not belong to your community",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [
false
]
},
"message": {
"type": "string"
}
},
"required": [
"success",
"message"
]
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/locations/{id}": {
"get": {
"summary": "Get a location by ID",
"description": "Retrieve a specific location by its unique identifier.",
"tags": [
"Locations"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed location ID"
}
],
"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/LocationItemResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid location ID)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Location not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/locations": {
"get": {
"summary": "List locations",
"description": "Retrieve a paginated list of locations, sorted by member count (descending).",
"tags": [
"Locations"
],
"parameters": [
{
"name": "locationType",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"city",
"country",
"country_region",
"world_region"
]
},
"description": "The granularity of locations to return (required)"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of locations to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of meta columns. The meta column `recordCount`\ncan be requested to return the total number of matching locations in\n`meta.recordCount`.\n"
}
],
"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/LocationItemList"
}
}
}
},
"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"
}
}
}
},
"/topics/{id}": {
"get": {
"summary": "Get a topic by ID",
"description": "Retrieve a specific topic by its unique identifier.",
"tags": [
"Topics"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed topic ID (format `tp_`)"
}
],
"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/TopicResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid topic ID)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Topic not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/topics": {
"get": {
"summary": "List topics",
"description": "Retrieve a paginated list of topics, sorted alphabetically by name.",
"tags": [
"Topics"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of topics to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "query",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter topics by display name prefix"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of meta columns. The meta column `recordCount`\ncan be requested to return the total number of matching topics in\n`meta.recordCount`.\n"
}
],
"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/TopicList"
}
}
}
},
"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"
}
}
}
},
"/providers": {
"get": {
"summary": "List providers",
"description": "List the visible signal sources (integrations) for the community, with pagination support.",
"tags": [
"Providers"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of providers to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
}
],
"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/ProviderList"
}
}
}
},
"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"
}
}
}
},
"/objects/bulk": {
"post": {
"summary": "Update many custom objects",
"description": "Apply the same change to up to 100 custom objects 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. A tag must be scoped to the object type of every listed object. 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.",
"tags": [
"Objects"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"objectIds"
],
"properties": {
"objectIds": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "Prefixed custom object IDs (format `co_`). Duplicates are ignored.",
"items": {
"type": "string"
}
},
"segmentId": {
"type": "string",
"description": "Add every custom object to this segment (format `s_`)."
},
"tagIdsToAdd": {
"type": "array",
"maxItems": 25,
"description": "Tag IDs (format `l_`) to add to every record.",
"items": {
"type": "string"
}
},
"tagIdsToRemove": {
"type": "array",
"maxItems": 25,
"description": "Tag IDs (format `l_`) to remove from every record.",
"items": {
"type": "string"
}
},
"customFields": {
"$ref": "#/components/schemas/BulkCustomFieldUpdates"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The custom objects were updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkUpdateResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "A custom object, the segment, or a tag was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/objects/{id}": {
"get": {
"summary": "Get a custom object by ID",
"description": "Retrieve a specific custom object by its unique identifier.",
"tags": [
"Objects"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed custom object ID (format `co_`)"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid values: `recordKey`, `tags`, `url`. Use `cf_*` to include all custom fields,\nor `cf_` for a specific one.\n"
}
],
"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/CustomObjectResponse"
}
}
}
},
"400": {
"description": "Bad Request (e.g. invalid object 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": "Object not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/objects/{id}/customFields": {
"post": {
"summary": "Update custom fields on a custom object",
"description": "Set Common Room custom-field values on a custom object record.",
"tags": [
"Objects"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed custom object ID (format `co_`)"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"customFields"
],
"properties": {
"customFields": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"customFieldId",
"customFieldValue"
],
"properties": {
"customFieldId": {
"type": "string",
"description": "Custom field ID (format `cf_`)"
},
"customFieldValue": {
"$ref": "#/components/schemas/ApiFieldValue",
"description": "The value is coerced against the target custom-field definition: plain strings are accepted for URL and date fields, and plain numbers are accepted for integer fields. Integer values must be whole numbers."
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated custom object",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomObjectResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Object not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/objects/{id}/segments": {
"post": {
"summary": "Add a custom object to a segment",
"description": "Add a custom object record to an existing object segment.",
"tags": [
"Objects"
],
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The prefixed custom object ID (format `co_`)"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"segmentId"
],
"properties": {
"segmentId": {
"type": "string",
"description": "The prefixed segment ID (format `s_`)"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated custom object",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomObjectResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "Object or segment not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/objects": {
"get": {
"summary": "List custom objects",
"description": "Retrieve a paginated list of custom objects.",
"tags": [
"Objects"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of objects 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",
"name"
],
"default": "id"
},
"description": "Field to sort results by"
},
{
"name": "direction",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
},
"description": "Sort direction"
},
{
"name": "objectTypeId",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Filter objects by prefixed object type ID (format `cot_`)"
},
{
"name": "segmentId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter objects by prefixed segment ID (format `s_`)"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid column values: `recordKey`, `tags`, `url`. Use `cf_*` to include all custom fields,\nor `cf_` for a specific one. The meta column `recordCount` can be\nrequested to return the total number of matching objects in `meta.recordCount`.\n"
},
{
"name": "lightFilter",
"in": "query",
"required": false,
"description": "Structured filter as URL-encoded JSON — see the `LightFilterExpression`\nschema for the grammar. Conditions are combined (AND) with the other\nquery parameters.\n\nFilterable fields:\n\n| Field | Filter type | Operators | Description |\n|---|---|---|---|\n| `objectSegmentId` | `stringListFilter` | `any`, `all`, `none` | Filter objects by segment membership. Use segment IDs from `GET /segments`. |\n| `objectLabelId` | `stringListFilter` | `any`, `all`, `none` | Filter objects by tag. Use tag IDs from `GET /tags`. |\n| `objectRecordKey` | `stringListFilter` | `any`, `all`, `none` | Filter objects by record keys |\n| `objectName` | `stringFilter` | `eq`, `like` | Filter objects by name |\n| `objectLeadScorePercentile` | `leadScoreFilter` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte` | Filter objects by lead score percentile (0-100). Requires a scoreId from `GET /lead-scores`. |\n| `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. |\n| `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. |\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightFilterExpression"
},
"examples": {
"objectsInSegment": {
"summary": "Custom objects in a segment",
"value": {
"type": "and",
"clauses": [
{
"type": "stringListFilter",
"field": "objectSegmentId",
"params": {
"op": "any",
"value": [
"s_1"
]
}
}
]
}
}
}
}
}
}
],
"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/CustomObjectList"
}
}
}
},
"400": {
"description": "Bad Request — also returned for malformed filters, e.g.\n\"Invalid lightFilter: must be valid JSON\", \"Invalid lightFilter: does\nnot match LightFilterExpression schema\", or an unknown filter field.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/object-types": {
"get": {
"summary": "List object types",
"description": "Retrieve all custom object type definitions for the community, including\ntheir associations to other entity types.\n",
"tags": [
"Object Types"
],
"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/ObjectTypeList"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/website-visits": {
"get": {
"summary": "List website visits",
"description": "Retrieve a paginated list of website visits.",
"tags": [
"Website Visits"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of visits to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid column values: `url` (included by default), `contactId`, `organizationId`.\nThe meta column `recordCount` can be requested to return the total number\nof matching visits in `meta.recordCount`.\n"
},
{
"name": "contactId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter visits by prefixed contact ID (format `c_`)"
},
{
"name": "organizationId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter visits by prefixed organization ID (format `o_`)"
},
{
"name": "lightFilter",
"in": "query",
"required": false,
"description": "Structured filter as URL-encoded JSON — see the `LightFilterExpression`\nschema for the grammar. Conditions are combined (AND) with the other\nquery parameters. To filter by contact or organization, use the\ndedicated `contactId` / `organizationId` query parameters above.\n\nFilterable fields:\n\n| Field | Filter type | Operators | Description |\n|---|---|---|---|\n| `visitTime` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter website visits by time range. |\n| `url` | `stringFilter` | `eq`, `like` | Filter website visits by URL. Use `like` for partial match (contains). |\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightFilterExpression"
},
"examples": {
"visitsLast7Days": {
"summary": "Website visits in the last 7 days",
"value": {
"type": "and",
"clauses": [
{
"type": "dateRangeFilter",
"field": "visitTime",
"params": {
"op": "in",
"value": "P7D",
"min": null,
"max": null
}
}
]
}
},
"visitsToPricingPage": {
"summary": "Website visits to URLs containing \"/pricing\"",
"value": {
"type": "and",
"clauses": [
{
"type": "stringFilter",
"field": "url",
"params": {
"op": "like",
"value": "/pricing"
}
}
]
}
}
}
}
}
}
],
"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/WebsiteVisitList"
}
}
}
},
"400": {
"description": "Bad Request — also returned for malformed filters, e.g.\n\"Invalid lightFilter: must be valid JSON\", \"Invalid lightFilter: does\nnot match LightFilterExpression schema\", or an unknown filter field.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/buying-committee-cells": {
"get": {
"summary": "List buying committee cells",
"description": "Retrieve the materialized buying committee cells for one organization.\nThe full committee is returned in a single response — this endpoint is\nnot paginated. Cells are returned in the same seniority-row and\ndepartment-column order as the product. Every cell includes its full\nbounded list of available ranked contacts.\n\nA buying committee must already be configured in the workspace. The\ntoken must grant `organizations:read`, `contacts:read`, and\n`prospector:read` (or the encompassing `read` scope).\n\nCandidates are a ranked sample using up to five engagement-ranked and\nfive recently touched candidates per cell, not every eligible person. Prospector\nemails are intentionally withheld and returned as null, matching the\nbuying committee view in the product. Cells without available candidates have an\nempty `contacts` array.\n\n`meta.nextCursor` is always null. Pagination parameters, sorting,\nfilters other than `organizationId`, and retrieving a cell by ID\nare not supported.\n\nExample request:\n\n```sh\ncurl --get 'https://api.commonroom.io/api/v2/buying-committee-cells' \\\n --header \"Authorization: Bearer $COMMON_ROOM_API_TOKEN\" \\\n --data-urlencode 'organizationId=o_123' \\\n --data-urlencode 'cols=recordCount'\n```\n",
"tags": [
"Buying Committee"
],
"parameters": [
{
"name": "organizationId",
"in": "query",
"required": true,
"schema": {
"type": "string",
"pattern": "^o_[0-9]+$"
},
"description": "Organization ID in the authenticated workspace whose buying committee should be read",
"example": "o_123"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated columns. Use `recordCount` to include the materialized cell count in response metadata. Contacts and other cell fields are always returned."
}
],
"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/BuyingCommitteeCellList"
},
"example": {
"success": true,
"data": [
{
"id": "buying-committee-cell:o_123:200:106",
"department": {
"id": 200,
"key": "Sales",
"name": "Sales"
},
"seniority": {
"id": 106,
"key": "CLevel",
"name": "C-Level"
},
"contacts": []
}
],
"meta": {
"nextCursor": null,
"recordCount": 1
}
}
}
}
},
"400": {
"description": "Invalid organization ID, unsupported query parameter, or column selection",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Token is missing a required organization, contact, or Prospector read scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"404": {
"description": "Organization not found in this workspace, or buying committee is not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/job-openings": {
"get": {
"summary": "List job openings",
"description": "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.",
"tags": [
"Job Openings"
],
"parameters": [
{
"name": "organizationId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Prefixed organization ID (format `o_`) whose job openings to read. Required unless `objectId` is given."
},
{
"name": "objectId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Prefixed custom object ID (format `co_`) 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."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of job openings to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid column value: `jobDescription`.\nThe meta column `recordCount` can be requested to return the total number\nof matching job openings in `meta.recordCount`.\n"
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"firstSeenAt"
]
},
"description": "Sort field"
},
{
"name": "direction",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"description": "Sort direction"
},
{
"name": "lightFilter",
"in": "query",
"required": false,
"description": "Structured filter as URL-encoded JSON — see the `LightFilterExpression`\nschema for the grammar. Conditions are combined (AND) with the other\nquery parameters. An `organizationId` or `objectId` clause inside the\nfilter is hoisted to the corresponding query parameter, so the\nrequired scope can be supplied either way.\n\nFilterable fields:\n\n| Field | Filter type | Operators | Description |\n|---|---|---|---|\n| `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_`). |\n| `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_`). |\n| `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. |\n| `jobOpeningTitle` | `stringListFilter` | `any`, `all`, `none` | Filter job openings by title. |\n| `jobOpeningStatus` | `stringFilter` | `eq` | Filter job openings by status. Valid values: open, closed. |\n| `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. |\n| `jobOpeningFirstSeen` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter job openings by the date the posting was originally published or first discovered. |\n| `jobOpeningLastSeen` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter job openings by the most recent date the posting was still observed as active. |\n| `jobOpeningGeolocation` | `stringListFilter` | `any`, `none` | Filter job openings by location ID(s). Use location IDs from `GET /locations`. |\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightFilterExpression"
},
"examples": {
"openSalesRoles": {
"summary": "Open sales roles at an organization",
"value": {
"type": "and",
"clauses": [
{
"type": "stringFilter",
"field": "organizationId",
"params": {
"op": "eq",
"value": "o_123"
}
},
{
"type": "stringListFilter",
"field": "jobOpeningTitle",
"params": {
"op": "any",
"value": [
"Account Executive",
"Sales"
]
}
},
{
"type": "stringFilter",
"field": "jobOpeningStatus",
"params": {
"op": "eq",
"value": "open"
}
}
]
}
},
"recentOpeningsForObject": {
"summary": "Job openings first seen in the last 30 days for a custom object",
"value": {
"type": "and",
"clauses": [
{
"type": "stringFilter",
"field": "objectId",
"params": {
"op": "eq",
"value": "co_456"
}
},
{
"type": "dateRangeFilter",
"field": "jobOpeningFirstSeen",
"params": {
"op": "in",
"value": "P30D",
"min": null,
"max": null
}
}
]
}
}
}
}
}
}
],
"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/JobOpeningList"
}
}
}
},
"400": {
"description": "Bad Request — also returned for malformed filters, e.g.\n\"Invalid lightFilter: must be valid JSON\", \"Invalid lightFilter: does\nnot match LightFilterExpression schema\", or an unknown filter field.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "The organization or object does not exist in this workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/news-items": {
"get": {
"summary": "List news items",
"description": "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.",
"tags": [
"News Items"
],
"parameters": [
{
"name": "organizationId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Prefixed organization ID (format `o_`) whose news items to read. Required unless `objectId` is given."
},
{
"name": "objectId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Prefixed custom object ID (format `co_`) 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."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of news items to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "News items have no opt-in columns; every field is always returned.\nThe meta column `recordCount` can be requested to return the total number\nof matching news items in `meta.recordCount`.\n"
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"publishedAt"
]
},
"description": "Sort field"
},
{
"name": "direction",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"description": "Sort direction"
},
{
"name": "lightFilter",
"in": "query",
"required": false,
"description": "Structured filter as URL-encoded JSON — see the `LightFilterExpression`\nschema for the grammar. Conditions are combined (AND) with the other\nquery parameters. An `organizationId` or `objectId` clause inside the\nfilter is hoisted to the corresponding query parameter, so the\nrequired scope can be supplied either way.\n\nFilterable fields:\n\n| Field | Filter type | Operators | Description |\n|---|---|---|---|\n| `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_`). |\n| `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_`). |\n| `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. |\n| `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. |\n| `newsPublishedAt` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter news items by publication date. |\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightFilterExpression"
},
"examples": {
"fundingNews": {
"summary": "Funding news for an organization in the last 90 days",
"value": {
"type": "and",
"clauses": [
{
"type": "stringFilter",
"field": "organizationId",
"params": {
"op": "eq",
"value": "o_123"
}
},
{
"type": "stringListFilter",
"field": "newsCategory",
"params": {
"op": "any",
"value": [
"receives_financing"
]
}
},
{
"type": "dateRangeFilter",
"field": "newsPublishedAt",
"params": {
"op": "in",
"value": "P90D",
"min": null,
"max": null
}
}
]
}
},
"newsForObject": {
"summary": "News for the organization behind a custom object",
"value": {
"type": "and",
"clauses": [
{
"type": "stringFilter",
"field": "objectId",
"params": {
"op": "eq",
"value": "co_456"
}
}
]
}
}
}
}
}
}
],
"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/NewsItemList"
}
}
}
},
"400": {
"description": "Bad Request — also returned for malformed filters, e.g.\n\"Invalid lightFilter: must be valid JSON\", \"Invalid lightFilter: does\nnot match LightFilterExpression schema\", or an unknown filter field.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"404": {
"description": "The organization or object does not exist in this workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/prospector-contacts": {
"get": {
"summary": "List prospector contacts",
"description": "Retrieve a paginated list of prospector-discovered contacts.",
"tags": [
"Prospector Contacts"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of contacts to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid column values: `avatarUrl`, `companyName`, `companyWebsite`, `fullName`,\n`linkedInFollowerCount`, `linkedInHandle`, `location`, `role`, `seniority`,\n`skills`, `title`. The meta column `recordCount` can be requested to return\nthe total number of matching contacts in `meta.recordCount`.\n"
},
{
"name": "lightFilter",
"in": "query",
"required": false,
"description": "Structured filter as URL-encoded JSON — see the `LightFilterExpression`\nschema for the grammar. Conditions are combined (AND) with the other\nquery parameters.\n\nFilterable fields:\n\n| Field | Filter type | Operators | Description |\n|---|---|---|---|\n| `fullName` | `stringFilter` | `eq`, `like`, `empty`, `notEmpty` | Filter prospector contacts by name. |\n| `title` | `stringFilter` | `eq`, `like` | Filter prospector contacts by job title. |\n| `companyName` | `stringFilter` | `eq`, `like` | Filter prospector contacts by their current company name. |\n| `companyDomain` | `stringFilter` | `eq`, `like` | Filter prospector contacts by their current company domain/website (e.g., \"acme.com\"). |\n| `locationId` | `stringListFilter` | `any`, `none`, `empty`, `notEmpty` | Filter prospector contacts by location. Discover location IDs via `GET /locations`. |\n| `previousCompanyName` | `stringFilter` | `eq`, `like` | Filter prospector contacts by their previous company/organization name. |\n| `previousCompanyDomain` | `stringFilter` | `eq`, `like` | Filter prospector contacts by their previous company/organization domain/website (e.g., \"acme.com\"). |\n| `linkedInFollowerCount` | `numberFilter` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte` | Filter prospector contacts by LinkedIn follower count. |\n| `lastOrgChange` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter prospector contacts by when they last changed organizations (job change date). |\n| `jobRole` | `stringListFilter` | `any`, `none` | Filter prospector contacts by normalized job role. Valid values: Sales, Marketing, Engineering, Product, IT, Security, Finance, Operations, Customer Success, HR, Design, Legal, Research, Healthcare, Education, Consulting, Leadership, Other. |\n| `memberSeniority` | `stringListFilter` | `any`, `none` | Filter prospector contacts by normalized job seniority. Valid values: Intern, Junior IC, Senior IC, Manager, Director, VP, C-Level. |\n| `memberHasEmail` | `booleanFilter` | `eq`, `ne` | Filter prospector contacts by whether they have a professional email address. The address itself is not returned. |\n| `memberHasPhoneNumber` | `booleanFilter` | `eq`, `ne` | Filter prospector contacts by whether they have a phone number. The number itself is not returned. |\n\nFiltering by company: to filter on a contact's current company, add a group\nwhose `target` is `ProspectorCompany`. Its clauses use the company fields\nbelow, and it matches contacts whose current company satisfies them. Combine\nit with contact fields at the top level. For example, salespeople at software\ncompanies with at least 200 employees:\n\n```json\n{\n \"type\": \"and\",\n \"clauses\": [\n { \"type\": \"stringListFilter\", \"field\": \"jobRole\", \"params\": { \"op\": \"any\", \"value\": [\"Sales\"] } },\n {\n \"type\": \"and\",\n \"target\": \"ProspectorCompany\",\n \"objectConfigId\": null,\n \"targetAssocPaths\": null,\n \"clauses\": [\n { \"type\": \"numberFilter\", \"field\": \"groupCompanySize\", \"params\": { \"op\": \"gte\", \"value\": 200 } },\n { \"type\": \"stringListFilter\", \"field\": \"groupIndustryCode\", \"params\": { \"op\": \"any\", \"value\": [\"5112\"] } }\n ]\n }\n ]\n}\n```\n\n- Every group must send `target`, `objectConfigId` and `targetAssocPaths`, using\n `null` for any it doesn't use.\n- A company group needs at least one clause, and can contain nested `and`/`or`\n groups of company fields.\n- It always means the current company. Previous companies are reachable only\n through `previousCompanyName` and `previousCompanyDomain`.\n- This endpoint accepts the targets `ProspectorCompany` and `ProspectorContact`\n (the same as no target). Any other target returns a 400.\n\nCompany fields:\n\n| Company field | Name | Filter type |\n|---|---|---|\n| Name | `groupName` | `stringFilter` |\n| Website | `groupWebsite` | `stringFilter` |\n| LinkedIn handle | `groupLinkedinHandle` | `stringListFilter` |\n| Employee count | `groupCompanySize` | `numberFilter` |\n| Revenue | `groupRevenue` | `numberFilter` |\n| Capital raised | `groupCapitalRaised` | `numberFilter` |\n| Location | `groupLocationId` | `stringListFilter` (location IDs from `GET /locations`) |\n| NAICS industry code | `groupIndustryCode` | `stringListFilter` (codes from `GET /industries`) |\n| Sub-industry | `groupSubIndustry` | `stringListFilter` |\n| Technology | `groupTechStackId` | `stringListFilter` (IDs from `GET /tech-stack-products`) |\n\nThe company fields, operators and values are the same as on\n`GET /prospector-companies`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightFilterExpression"
},
"examples": {
"engineeringLeadersWithEmail": {
"summary": "Engineering directors and VPs with an email address",
"value": {
"type": "and",
"clauses": [
{
"type": "stringListFilter",
"field": "jobRole",
"params": {
"op": "any",
"value": [
"Engineering"
]
}
},
{
"type": "stringListFilter",
"field": "memberSeniority",
"params": {
"op": "any",
"value": [
"Director",
"VP"
]
}
},
{
"type": "booleanFilter",
"field": "memberHasEmail",
"params": {
"op": "eq",
"value": true
}
}
]
}
},
"salesAtMidSizeSoftwareCompanies": {
"summary": "Salespeople at software companies with at least 200 employees",
"value": {
"type": "and",
"clauses": [
{
"type": "stringListFilter",
"field": "jobRole",
"params": {
"op": "any",
"value": [
"Sales"
]
}
},
{
"type": "and",
"target": "ProspectorCompany",
"objectConfigId": null,
"targetAssocPaths": null,
"clauses": [
{
"type": "numberFilter",
"field": "groupCompanySize",
"params": {
"op": "gte",
"value": 200
}
},
{
"type": "stringListFilter",
"field": "groupIndustryCode",
"params": {
"op": "any",
"value": [
"5112"
]
}
}
]
}
]
}
},
"prospectsAtCompanyDomain": {
"summary": "Prospects at a specific company domain",
"value": {
"type": "and",
"clauses": [
{
"type": "stringFilter",
"field": "companyDomain",
"params": {
"op": "eq",
"value": "acme.com"
}
}
]
}
},
"recentJobChangers": {
"summary": "Prospects who changed jobs in the last 30 days",
"value": {
"type": "and",
"clauses": [
{
"type": "dateRangeFilter",
"field": "lastOrgChange",
"params": {
"op": "in",
"value": "P30D",
"min": null,
"max": null
}
}
]
}
}
}
}
}
}
],
"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/ProspectorContactList"
}
}
}
},
"400": {
"description": "Bad Request — also returned for malformed filters, e.g.\n\"Invalid lightFilter: must be valid JSON\", \"Invalid lightFilter: does\nnot match LightFilterExpression schema\", or an unknown filter field.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/prospector-companies": {
"get": {
"summary": "List prospector companies",
"description": "Retrieve a paginated list of prospector-discovered companies.",
"tags": [
"Prospector Companies"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of companies to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "cols",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Comma-separated list of additional columns to include in the response.\nValid column values: `description`, `employees`, `linkedInHandles`, `location`,\n`logoUrl`, `primaryWebsite`, `raised`, `revenueRange`, `subIndustry`,\n`technologies`. The meta column `recordCount` can be requested to return\nthe total number of matching companies in `meta.recordCount`.\n"
},
{
"name": "lightFilter",
"in": "query",
"required": false,
"description": "Structured filter as URL-encoded JSON — see the `LightFilterExpression`\nschema for the grammar. Conditions are combined (AND) with the other\nquery parameters.\n\nFilterable fields:\n\n| Field | Filter type | Operators | Description |\n|---|---|---|---|\n| `groupName` | `stringFilter` | `eq`, `like` | Filter prospector companies by name. |\n| `groupLinkedinHandle` | `stringListFilter` | `any`, `none` | Filter prospector companies by LinkedIn handle. |\n| `groupWebsite` | `stringFilter` | `eq`, `like` | Filter prospector companies by primary website/domain (e.g., \"acme.com\"). |\n| `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. |\n| `groupCompanySize` | `numberFilter` | `eq`, `ne`, `gte`, `lte` | Filter prospector companies by employee count. |\n| `groupRevenue` | `numberFilter` | `gt`, `gte`, `lt`, `lte` | Filter prospector companies by estimated annual revenue. Lower bounds match the estimate's floor, upper bounds its ceiling. |\n| `groupCapitalRaised` | `numberFilter` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte` | Filter prospector companies by total capital raised. |\n| `groupLocationId` | `stringListFilter` | `any`, `all`, `none`, `empty`, `notEmpty` | Filter prospector companies by location ID(s). Use location IDs from `GET /locations`. |\n| `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. |\n| `groupTechStackId` | `stringListFilter` | `any`, `all`, `none` | Filter prospector companies by tech stack product ID(s). Look up product IDs via `GET /tech-stack-products`. |\n| `technographicsIntensity` | `numberFilter` | `gte`, `lte` | Filter prospector companies by technology usage intensity score. |\n| `technographicsFirstSeen` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter prospector companies by when a technology was first detected. |\n| `technographicsLastSeen` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter prospector companies by when a technology was last detected. |\n| `jobOpeningKeyword` | `stringListFilter` | `any`, `all`, `none` | Filter companies by job listing keyword search. Finds companies with job openings matching the given keywords. |\n| `jobOpeningTitle` | `stringListFilter` | `any`, `all`, `none` | Filter companies by job listing title. |\n| `jobOpeningStatus` | `stringFilter` | `eq` | Filter companies by job opening status. Values: 'open', 'closed'. |\n| `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. |\n| `jobOpeningFirstSeen` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter companies by the date a job opening was originally published or first discovered. |\n| `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. |\n| `jobOpeningGeolocation` | `stringListFilter` | `any`, `none` | Filter prospector companies by job opening location ID(s). Use location IDs from `GET /locations`. |\n| `newsKeyword` | `stringListFilter` | `any`, `all`, `none` | Filter companies by news keyword search. Finds companies with news articles matching the given keywords. |\n| `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. |\n| `newsPublishedAt` | `dateRangeFilter` | `in`, `between`, `after`, `before` | Filter companies by news publication date. |\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LightFilterExpression"
},
"examples": {
"softwareCompaniesWith50Employees": {
"summary": "Companies with 50+ employees in Software industry",
"value": {
"type": "and",
"clauses": [
{
"type": "numberFilter",
"field": "groupCompanySize",
"params": {
"op": "gte",
"value": 50
}
},
{
"type": "stringListFilter",
"field": "groupSubIndustry",
"params": {
"op": "any",
"value": [
"Software"
]
}
}
]
}
},
"softwarePublishersByNaicsCode": {
"summary": "Companies in NAICS code 5112 (Software Publishers)",
"value": {
"type": "and",
"clauses": [
{
"type": "stringListFilter",
"field": "groupIndustryCode",
"params": {
"op": "any",
"value": [
"5112"
]
}
}
]
}
}
}
}
}
}
],
"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/ProspectorCompanyList"
}
}
}
},
"400": {
"description": "Bad Request — also returned for malformed filters, e.g.\n\"Invalid lightFilter: must be valid JSON\", \"Invalid lightFilter: does\nnot match LightFilterExpression schema\", or an unknown filter field.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Status"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/industries": {
"get": {
"summary": "List NAICS industry codes",
"description": "Retrieve a paginated list of NAICS industry codes, optionally filtered by search query.",
"tags": [
"Industries"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of codes to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "query",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Search text to filter industry codes by name"
}
],
"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/NaicsCodeList"
}
}
}
},
"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"
}
}
}
},
"/tech-stack-products": {
"get": {
"summary": "List tech stack products",
"description": "Retrieve a paginated list of technographic products, optionally filtered by search query.",
"tags": [
"Tech Stack Products"
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50
},
"description": "The maximum number of products to return per page"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Pagination cursor from a previous response"
},
{
"name": "query",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Search text to filter products by name"
}
],
"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/TechStackProductList"
}
}
}
},
"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"
}
}
}
},
"/analytics/catalog": {
"get": {
"summary": "Get the analytics catalog",
"description": "Lists the entities, dimensions, filters and metrics that `GET /analytics/query` accepts. Read it\nbefore building a query: metric keys, the groupings each metric supports and filter keys come from here.\nThe token must grant `analytics:read` (or the encompassing `read` scope).\n",
"tags": [
"Analytics"
],
"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/AnalyticsCatalogResponse"
}
}
}
},
"403": {
"description": "Token is missing the `analytics:read` scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/analytics/query": {
"get": {
"summary": "Query analytics metrics",
"description": "Computes catalog metrics for the reps on a set of teams, as one total or broken down by\n`groupBy`, over a window (`range`, or `start` and `end`) or on a date (`asOf`, snapshot\nmetrics only). Every request names who it covers with `personaIds` (teams, including their\nsub-teams), `memberIds` (reps), or both. Admins can query every team, and managers with Editor\npermission the teams they manage and their sub-teams. A team or rep outside the caller's scope\nfails the whole request.\n\n`groupBy=action` lists the actions behind `repAction` metrics, newest first, in pages: pass\n`meta.nextCursor` back as `cursor` for the next page. Other results come whole in one response.\nThe token must grant `analytics:read` (or the encompassing `read` scope); action rows carry\ncontact emails and Salesforce ids, so `groupBy=action` also needs `contacts:read`.\n\nExample request, completed tasks per rep on two teams over the last 7 days, as in the app:\n\n```sh\ncurl --get 'https://api.commonroom.io/api/v2/analytics/query' \\\n --header \"Authorization: Bearer $COMMON_ROOM_API_TOKEN\" \\\n --data-urlencode 'metrics=tasksMarkedDone' \\\n --data-urlencode 'groupBy=rep' \\\n --data-urlencode 'personaIds=p_31' \\\n --data-urlencode 'personaIds=p_32' \\\n --data-urlencode 'range=P7D' \\\n --data-urlencode 'timeZone=America/Los_Angeles'\n```\n",
"tags": [
"Analytics"
],
"parameters": [
{
"name": "metrics",
"in": "query",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true,
"description": "Metric keys from the catalog, repeated (`metrics=a&metrics=b`)."
},
{
"name": "groupBy",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true,
"description": "Dimension keys, repeated. Every metric must support the combination. Omit for one row covering everyone."
},
{
"name": "range",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"example": "P7D",
"description": "ISO 8601 duration of at most a year. Durations of a day or longer end at the start of tomorrow in\n`timeZone`, like the app's presets; durations in hours or minutes end now. Excludes `start`, `end` and `asOf`.\n"
},
{
"name": "start",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Inclusive window start, ISO 8601 with offset. URL-encode a `+` offset as `%2B`. Requires `end`."
},
{
"name": "end",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Exclusive window end, in the same format as `start`. At most a year after `start`."
},
{
"name": "asOf",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date"
},
"description": "A date for a point-in-time query. Only metrics with `snapshot` temporality accept it."
},
{
"name": "timeZone",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "UTC"
},
"description": "IANA time zone for `range`, and the zone `start` and `end` are reported in. Not accepted with `asOf`."
},
{
"name": "personaIds",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"pattern": "^p_[0-9]+$"
}
},
"style": "form",
"explode": true,
"description": "Teams to report on, repeated, including their sub-teams."
},
{
"name": "memberIds",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"pattern": "^c_[0-9]+$"
}
},
"style": "form",
"explode": true,
"description": "Reps to report on by contact id, repeated. With `personaIds`, narrows those teams to these reps."
},
{
"name": "segmentIds",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"pattern": "^s_[0-9]+$"
}
},
"style": "form",
"explode": true,
"description": "Only actions taken in these segments, repeated. `repAction` metrics only."
},
{
"name": "sepDestinations",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true,
"description": "Only sends to these destinations, repeated; the catalog lists the workspace's. `repAction` metrics only."
},
{
"name": "repMetrics",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"style": "form",
"explode": true,
"description": "Only actions that count toward one of these rep metrics, repeated. `repAction` metrics only."
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "A requested metric or a column of a grouped dimension. Nulls sort last. Action rows sort only by `startedAt`."
},
{
"name": "direction",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"description": "Sort order. Only with `sort`."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500
},
"description": "Keep the first N rows after sorting. Only with `sort`, except with `groupBy=action`, where it is\nthe page size (default 25). `meta.totalRows` gives the count before the limit.\n"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "The `meta.nextCursor` of an earlier `groupBy=action` response, for the next page."
}
],
"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/AnalyticsQueryResponse"
},
"example": {
"success": true,
"data": [
{
"repId": "c_907",
"repName": "Grace Hopper",
"teamId": "p_31",
"teamName": "West",
"lastActiveAt": "2026-10-19T16:02:11.000Z",
"lastActionedAt": "2026-10-19T15:40:03.000Z",
"tasksMarkedDone": 7
}
],
"meta": {
"entity": "rep",
"groupBy": [
"rep"
],
"time": {
"start": "2026-10-13T00:00:00.000-07:00",
"end": "2026-10-20T00:00:00.000-07:00",
"timeZone": "America/Los_Angeles"
},
"scope": {
"teams": [
{
"id": "p_31",
"name": "West"
}
],
"repCount": 1
},
"columns": [
{
"name": "repId",
"role": "dimension"
},
{
"name": "repName",
"role": "dimension"
},
{
"name": "teamId",
"role": "attribute",
"nullable": true
},
{
"name": "teamName",
"role": "attribute",
"nullable": true
},
{
"name": "lastActiveAt",
"role": "attribute",
"type": "timestamp",
"nullable": true
},
{
"name": "lastActionedAt",
"role": "attribute",
"type": "timestamp",
"nullable": true
},
{
"name": "tasksMarkedDone",
"role": "metric",
"unit": "task",
"temporality": "window"
}
],
"rowCount": 1,
"totalRows": 1,
"notes": []
}
}
}
}
},
"400": {
"description": "`invalid_parameters`: an unknown parameter or metric, a `groupBy` a metric doesn't support, a\nmissing or conflicting time form, neither `personaIds` nor `memberIds`, a malformed or unknown id,\na rep not on the requested teams, an invalid `sort`, `limit` or `cursor`, more reps than one request\ncan cover, or more than 5,000 rows. The message says what to change.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"403": {
"description": "`insufficient_scope` when the token lacks `analytics:read`, or `contacts:read` with\n`groupBy=action`. `insufficient_capability` when the\ncaller can't view team reporting, or a requested team or rep is outside their scope; the message\nlists only the ids the request sent.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiV2ErrorResponse"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
}
},
"components": {
"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"
}
},
"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": {
"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"
}
}
}
}
}
}
}
},
"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": {
"status": {
"type": "string",
"example": "failure"
},
"reason": {
"type": "string",
"description": "Reason for the request failure"
}
}
}
}
}
}
},
"schemas": {
"ApiV2Error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A machine-readable error code identifying the failure.",
"enum": [
"insufficient_scope",
"not_found",
"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",
"insufficient_scope",
"insufficient_capability"
]
},
"message": {
"type": "string",
"description": "A human-readable description of the error."
}
}
},
"ApiV2ErrorResponse": {
"type": "object",
"required": [
"success",
"error"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
false
]
},
"error": {
"$ref": "#/components/schemas/ApiV2Error"
}
}
},
"BulkCustomFieldUpdates": {
"type": "array",
"minItems": 1,
"description": "Custom-field values to set on every record in the request.",
"items": {
"type": "object",
"required": [
"customFieldId",
"customFieldValue"
],
"properties": {
"customFieldId": {
"type": "string",
"description": "Custom field ID (format `cf_`)"
},
"customFieldValue": {
"$ref": "#/components/schemas/ApiFieldValue"
}
}
}
},
"BulkUpdateResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "object",
"required": [
"ids"
],
"properties": {
"ids": {
"type": "array",
"description": "The prefixed IDs of the records that were updated, deduplicated.",
"items": {
"type": "string"
}
}
}
}
}
},
"DeleteContactsResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "One entry per requested ID, in request order, with duplicates removed.",
"items": {
"type": "object",
"required": [
"id",
"deletedId"
],
"properties": {
"id": {
"type": "string",
"description": "The requested contact ID (format `c_`)."
},
"deletedId": {
"type": "string",
"description": "The contact that was deleted (format `c_`). It differs from `id`\nwhen the requested contact had been merged into another contact.\n"
}
}
}
}
}
}
}
},
"RightToBeForgottenRequest": {
"type": "object",
"required": [
"id",
"status",
"createdAt",
"processedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Right-to-be-forgotten request ID (format `rtbf_`)"
},
"status": {
"type": "string",
"enum": [
"pending",
"processed"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"processedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When the request was processed, or null while it is pending."
}
}
},
"RightToBeForgottenRequestResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/RightToBeForgottenRequest"
}
}
},
"LightFilterExpression": {
"type": "object",
"description": "Structured filter for list endpoints, passed as the URL-encoded JSON value\nof the `lightFilter` query parameter. Combine clauses with `and`/`or` logic\nat the root; each clause is either a leaf condition (discriminated by its\n`type` field, which determines the valid `field` names and `params`) or a\nnested group for complex boolean logic. The filterable `field` names for\neach endpoint — and the operators each one accepts — are listed in that\nendpoint's `lightFilter` parameter description. Custom fields are\nreferenced as `cf_` (find IDs via `GET /custom-fields`). Using an\noperator outside a field's documented set returns a 400 with the valid\noptions.\n",
"required": [
"type",
"clauses"
],
"properties": {
"type": {
"type": "string",
"enum": [
"and",
"or"
],
"description": "How to combine top-level clauses: \"and\" = all must match, \"or\" = any can match"
},
"clauses": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/LightFilterClause"
},
"description": "Array of filter conditions — leaf clauses or nested groups."
}
}
},
"LightFilterClause": {
"description": "A single filter condition (leaf clause) or a nested group of conditions.",
"oneOf": [
{
"$ref": "#/components/schemas/LightBooleanFilterClause"
},
{
"$ref": "#/components/schemas/LightStringFilterClause"
},
{
"$ref": "#/components/schemas/LightStringListFilterClause"
},
{
"$ref": "#/components/schemas/LightNumberFilterClause"
},
{
"$ref": "#/components/schemas/LightNumberRangeFilterClause"
},
{
"$ref": "#/components/schemas/LightDateRangeFilterClause"
},
{
"$ref": "#/components/schemas/LightLeadScoreFilterClause"
},
{
"$ref": "#/components/schemas/LightLocationFilterClause"
},
{
"$ref": "#/components/schemas/LightWebVisitPagesFilterClause"
},
{
"$ref": "#/components/schemas/LightFilterGroupClause"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"booleanFilter": "#/components/schemas/LightBooleanFilterClause",
"stringFilter": "#/components/schemas/LightStringFilterClause",
"stringListFilter": "#/components/schemas/LightStringListFilterClause",
"numberFilter": "#/components/schemas/LightNumberFilterClause",
"numberRangeFilter": "#/components/schemas/LightNumberRangeFilterClause",
"dateRangeFilter": "#/components/schemas/LightDateRangeFilterClause",
"leadScoreFilter": "#/components/schemas/LightLeadScoreFilterClause",
"location": "#/components/schemas/LightLocationFilterClause",
"webVisitPages": "#/components/schemas/LightWebVisitPagesFilterClause",
"and": "#/components/schemas/LightFilterGroupClause",
"or": "#/components/schemas/LightFilterGroupClause"
}
}
},
"LightFilterGroupClause": {
"type": "object",
"description": "A nested group of clauses combined with `and`/`or` logic, for boolean logic\nmore complex than the top-level combinator. A group can also apply its\nclauses to a related entity by setting `target`; each endpoint's\n`lightFilter` description lists the targets it accepts. All five keys are\nrequired: send `null` for `target`, `objectConfigId` and `targetAssocPaths`\nwhen you don't use them, or the request returns a 400.\n",
"required": [
"type",
"clauses",
"target",
"objectConfigId",
"targetAssocPaths"
],
"properties": {
"type": {
"type": "string",
"enum": [
"and",
"or"
],
"description": "Logical combinator: \"and\" = all must match, \"or\" = any can match"
},
"clauses": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/LightFilterClause"
},
"description": "Child filter clauses — leaf clauses or further nested groups."
},
"target": {
"type": "string",
"nullable": true,
"description": "The entity the child clauses describe. `null` means the endpoint's own\nentity. For example, `ProspectorCompany` on `GET /prospector-contacts`\nfilters on each contact's current company.\n"
},
"objectConfigId": {
"type": "string",
"nullable": true,
"description": "The custom object type (`cot_`) when `target` is `Object`; otherwise `null`."
},
"targetAssocPaths": {
"type": "array",
"nullable": true,
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LightPathSegment"
}
},
"description": "Advanced association paths to the target, one array of hops per path; the last hop is the destination. Send `null` to resolve them automatically."
}
}
},
"LightPathSegment": {
"type": "object",
"description": "One hop of an association path. All three keys are required; send `null` for the ones you don't use.",
"required": [
"target",
"objectConfigId",
"assocType"
],
"properties": {
"target": {
"type": "string",
"description": "The entity this hop reaches."
},
"objectConfigId": {
"type": "string",
"nullable": true,
"description": "The custom object type (`cot_`) when `target` is `Object`; otherwise `null`."
},
"assocType": {
"type": "string",
"nullable": true,
"description": "Which association to traverse when the two entities have more than one link; `null` uses the default."
}
}
},
"LightBooleanFilterClause": {
"type": "object",
"required": [
"type",
"field",
"params"
],
"properties": {
"type": {
"type": "string",
"enum": [
"booleanFilter"
]
},
"field": {
"type": "string",
"description": "Filterable field name (see the endpoint's field table) or custom field ID (`cf_`)."
},
"params": {
"type": "object",
"required": [
"op",
"value"
],
"properties": {
"op": {
"type": "string",
"description": "Operator for this field — see the field's Operators column in the endpoint description. eq: exact match, ne: not equal."
},
"value": {
"type": "boolean"
}
}
}
}
},
"LightStringFilterClause": {
"type": "object",
"required": [
"type",
"field",
"params"
],
"properties": {
"type": {
"type": "string",
"enum": [
"stringFilter"
]
},
"field": {
"type": "string",
"description": "Filterable field name (see the endpoint's field table) or custom field ID (`cf_`)."
},
"params": {
"type": "object",
"required": [
"op",
"value"
],
"properties": {
"op": {
"type": "string",
"description": "Operator for this field — see the field's Operators column in the endpoint description. eq: case-insensitive exact match — preferred for entity names, domains, and emails. like: case-insensitive substring/partial match — use for keyword or contains searches. empty/notEmpty: check if the field has a value."
},
"value": {
"type": "string",
"nullable": true,
"description": "Set to null for `empty`/`notEmpty` operators."
}
}
}
}
},
"LightStringListFilterClause": {
"type": "object",
"required": [
"type",
"field",
"params"
],
"properties": {
"type": {
"type": "string",
"enum": [
"stringListFilter"
]
},
"field": {
"type": "string",
"description": "Filterable field name (see the endpoint's field table) or custom field ID (`cf_`) for enum fields."
},
"params": {
"type": "object",
"required": [
"op",
"value"
],
"properties": {
"op": {
"type": "string",
"description": "Operator for this field — see the field's Operators column in the endpoint description. any: match any value in the list, all: match all values, none: exclude all values, empty/notEmpty: check if the field has values."
},
"value": {
"type": "array",
"nullable": true,
"minItems": 1,
"items": {
"type": "string"
},
"description": "Set to null for `empty`/`notEmpty` operators."
}
}
}
}
},
"LightNumberFilterClause": {
"type": "object",
"required": [
"type",
"field",
"params"
],
"properties": {
"type": {
"type": "string",
"enum": [
"numberFilter"
]
},
"field": {
"type": "string",
"description": "Filterable field name (see the endpoint's field table) or custom field ID (`cf_`)."
},
"params": {
"type": "object",
"required": [
"op",
"value"
],
"properties": {
"op": {
"type": "string",
"description": "Operator for this field — see the field's Operators column in the endpoint description. eq: equal, ne: not equal, gt/gte: greater than (or equal), lt/lte: less than (or equal)."
},
"value": {
"type": "number"
}
}
}
}
},
"LightNumberRangeFilterClause": {
"type": "object",
"required": [
"type",
"field",
"params"
],
"properties": {
"type": {
"type": "string",
"enum": [
"numberRangeFilter"
]
},
"field": {
"type": "string",
"description": "Filterable field name (see the endpoint's field table)."
},
"params": {
"type": "object",
"required": [
"op",
"value"
],
"properties": {
"op": {
"type": "string",
"description": "Operator for this field — see the field's Operators column in the endpoint description. between: match values within the inclusive min/max range."
},
"value": {
"type": "object",
"required": [
"min",
"max"
],
"properties": {
"min": {
"type": "number",
"nullable": true
},
"max": {
"type": "number",
"nullable": true
}
}
}
}
}
}
},
"LightDateRangeFilterClause": {
"type": "object",
"required": [
"type",
"field",
"params"
],
"properties": {
"type": {
"type": "string",
"enum": [
"dateRangeFilter"
]
},
"field": {
"type": "string",
"description": "Filterable field name (see the endpoint's field table) or custom field ID (`cf_`)."
},
"params": {
"type": "object",
"description": "At least one of `value`, `min`, or `max` must be non-null.",
"required": [
"op",
"value",
"min",
"max"
],
"properties": {
"op": {
"type": "string",
"description": "Operator for this field — see the field's Operators column in the endpoint description. in: within an ISO 8601 duration of now (use `value`, e.g. \"P7D\"), between: date range (use `min` + `max`), after: after a date (use `min`), before: before a date (use `max`)."
},
"value": {
"type": "string",
"nullable": true,
"pattern": "^P",
"description": "ISO 8601 duration for the `in` operator (e.g. \"P7D\" for the last 7 days). Null for other operators."
},
"min": {
"type": "string",
"nullable": true,
"description": "Start date in ISO 8601 format. Required for `between` and `after`."
},
"max": {
"type": "string",
"nullable": true,
"description": "End date in ISO 8601 format. Required for `between` and `before`."
}
}
}
}
},
"LightLeadScoreFilterClause": {
"type": "object",
"required": [
"type",
"field",
"params"
],
"properties": {
"type": {
"type": "string",
"enum": [
"leadScoreFilter"
]
},
"field": {
"type": "string",
"description": "Filterable field name (see the endpoint's field table), e.g. `memberLeadScorePercentile`."
},
"params": {
"type": "object",
"required": [
"op",
"value",
"scoreId"
],
"properties": {
"op": {
"type": "string",
"description": "Operator for this field — see the field's Operators column in the endpoint description. eq: equal, ne: not equal, gt/gte: greater than (or equal), lt/lte: less than (or equal)."
},
"value": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Lead score percentile (0–100)."
},
"scoreId": {
"type": "string",
"description": "Lead score ID (format `ls_`). Find available scores via `GET /lead-scores`."
}
}
}
}
},
"LightLocationFilterClause": {
"type": "object",
"required": [
"type",
"field",
"params"
],
"properties": {
"type": {
"type": "string",
"enum": [
"location"
]
},
"field": {
"type": "string",
"enum": [
"city",
"country",
"country_region"
],
"description": "Location component to match. `country_region` is a state or province."
},
"params": {
"type": "object",
"required": [
"op",
"value"
],
"properties": {
"op": {
"type": "string",
"description": "Operator for this field — see the field's Operators column in the endpoint description. any: match any of the given locations."
},
"value": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
}
}
}
}
},
"LightWebVisitPagesFilterClause": {
"type": "object",
"required": [
"type",
"field",
"params"
],
"properties": {
"type": {
"type": "string",
"enum": [
"webVisitPages"
]
},
"field": {
"type": "string",
"enum": [
"memberWebVisitPagesViewed",
"groupWebVisitPagesViewed"
],
"description": "Use `memberWebVisitPagesViewed` for a contact-level rule, `groupWebVisitPagesViewed` for an organization-level rule."
},
"params": {
"type": "object",
"required": [
"op",
"pages",
"interval",
"minimumPageViews"
],
"properties": {
"op": {
"type": "string",
"description": "Operator for this field — see the field's Operators column in the endpoint description. any: visited at least one page matching one of the patterns; none: visited zero matching pages."
},
"pages": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"match",
"value"
],
"properties": {
"match": {
"type": "string",
"enum": [
"contains",
"exact",
"partial",
"prefix"
],
"description": "Match mode: contains/partial = substring match on the URL path (preferred for keyword intent like \"/pricing\"); exact = full URL equality; prefix = URL starts with value."
},
"value": {
"type": "string",
"description": "URL or URL-path keyword to match. Use a leading slash for paths (e.g. \"/pricing\", \"/demo\")."
}
}
}
},
"interval": {
"type": "string",
"pattern": "^P",
"description": "ISO 8601 duration window for the visit, e.g. \"P7D\" (last 7 days), \"P30D\", \"P90D\"."
},
"minimumPageViews": {
"type": "integer",
"nullable": true,
"minimum": 1,
"description": "Minimum total matching page-view count within the interval. Null means at least 1."
}
}
}
}
},
"ApiLocation": {
"type": "object",
"description": "A best-effort location, with each component populated when known.",
"properties": {
"city": {
"type": "string",
"description": "City name"
},
"region": {
"type": "string",
"description": "State, province, or region name"
},
"country": {
"type": "string",
"description": "Country name"
},
"countryCode": {
"type": "string",
"description": "Two-letter ISO 3166-1 country code"
}
}
},
"ApiFieldValue": {
"description": "A typed custom-field value. The `type` discriminator indicates the value's runtime type.",
"oneOf": [
{
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"string"
]
},
"value": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"url"
]
},
"value": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"int"
]
},
"value": {
"type": "integer"
}
}
},
{
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"number"
]
},
"value": {
"type": "number"
}
}
},
{
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"date"
]
},
"value": {
"type": "string",
"format": "date-time"
}
}
},
{
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"boolean"
]
},
"value": {
"type": "boolean"
}
}
}
]
},
"ApiLeadScore": {
"type": "object",
"required": [
"scoreId",
"score",
"percentile"
],
"properties": {
"scoreId": {
"type": "integer",
"description": "The numeric ID of the lead-score definition"
},
"score": {
"type": "number",
"description": "The raw score for this contact or organization"
},
"percentile": {
"type": "number",
"description": "The percentile rank of the score within the community"
}
}
},
"ApiLeadScoreKeyFactors": {
"type": "object",
"description": "The factors that produced one lead score, sorted strongest first. One entry is returned per configured score, aligned with leadScores; a score with no recorded factors returns an empty factors list rather than being omitted.",
"required": [
"scoreId",
"factors"
],
"properties": {
"scoreId": {
"type": "integer",
"description": "The numeric ID of the lead-score definition"
},
"factors": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"value",
"strength"
],
"properties": {
"label": {
"type": "string",
"description": "Human-readable name of the scored attribute, custom field, nested score, or research prompt"
},
"value": {
"type": "string",
"nullable": true,
"description": "The matched value, rendered for display. Null when the value has no readable rendering without per-workspace lookups (tags, segments, technologies, programming languages)."
},
"strength": {
"type": "number",
"description": "Points this factor contributed to the score; negative for detractors"
}
}
}
}
}
},
"ApiActivity": {
"type": "object",
"required": [
"id",
"type",
"activityTime"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed activity ID (format `a_`)"
},
"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_`)"
},
"content": {
"type": "string",
"nullable": true
},
"isUserInitiated": {
"type": "boolean"
},
"participantCount": {
"type": "integer"
},
"providerId": {
"type": "string",
"description": "Prefixed signal source ID (format `sig_`)"
},
"providerName": {
"type": "string",
"nullable": true
},
"replyCount": {
"type": "integer"
},
"sentiment": {
"type": "string",
"nullable": true
},
"subSourceNames": {
"type": "array",
"items": {
"type": "string"
}
},
"url": {
"type": "string",
"format": "uri"
}
}
},
"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"
}
}
},
"ActivityTypeList": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiActivityType"
}
}
}
},
"ActivityResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/ApiActivity"
}
}
},
"ActivityList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiActivity"
}
},
"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."
}
}
}
}
},
"Contact": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed contact ID (format `c_`)"
},
"name": {
"type": "string",
"description": "The contact's display name"
},
"avatarUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"fullName": {
"type": "string",
"nullable": true
},
"location": {
"allOf": [
{
"$ref": "#/components/schemas/ApiLocation"
}
],
"nullable": true
},
"primaryEmail": {
"type": "string",
"nullable": true
},
"phoneNumbers": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"value",
"isPremium"
],
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
},
"isPremium": {
"type": "boolean",
"description": "Whether the number is a premium (paid) phone number"
}
}
}
},
"title": {
"type": "string",
"nullable": true
},
"companyName": {
"type": "string",
"nullable": true
},
"companyWebsite": {
"type": "string",
"nullable": true
},
"linkedInUrls": {
"type": "array",
"description": "LinkedIn profile URLs",
"items": {
"type": "string",
"format": "uri"
}
},
"gitHubUrls": {
"type": "array",
"description": "GitHub profile URLs",
"items": {
"type": "string",
"format": "uri"
}
},
"xUrls": {
"type": "array",
"description": "X (formerly Twitter) profile URLs",
"items": {
"type": "string",
"format": "uri"
}
},
"connectedCustomObjects": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"objectType"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed custom object ID (format `co_`)"
},
"name": {
"type": "string"
},
"objectType": {
"type": "string"
}
}
}
},
"customFields": {
"type": "object",
"description": "Map of custom-field ID (format `cf_`) to its typed value.",
"additionalProperties": {
"$ref": "#/components/schemas/ApiFieldValue"
}
},
"profiles": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
},
"jobHistory": {
"type": "array",
"description": "The 3 most recent positions, current positions first. Use fullJobHistory for the complete list.",
"items": {
"type": "object",
"required": [
"company",
"title",
"startDate",
"endDate"
],
"properties": {
"company": {
"type": "string"
},
"title": {
"type": "string",
"nullable": true
},
"startDate": {
"type": "string"
},
"endDate": {
"type": "string",
"nullable": true
}
}
}
},
"fullJobHistory": {
"type": "array",
"description": "Complete employment history, current positions first then by startDate descending.",
"items": {
"type": "object",
"required": [
"company",
"domain",
"title",
"startDate",
"endDate",
"isCurrent"
],
"properties": {
"company": {
"type": "string"
},
"domain": {
"type": "string"
},
"title": {
"type": "string",
"nullable": true
},
"startDate": {
"type": "string"
},
"endDate": {
"type": "string",
"nullable": true
},
"isCurrent": {
"type": "boolean"
}
}
}
},
"jobChangeDate": {
"type": "string",
"nullable": true,
"description": "Date the contact started at their current company"
},
"currentCompany": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ApiContactCompany"
}
],
"nullable": true,
"description": "The contact's current employer"
},
"previousCompany": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ApiContactCompany"
}
],
"nullable": true,
"description": "The contact's most recent previous employer"
},
"leadScores": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiLeadScore"
}
},
"leadScoreKeyFactors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiLeadScoreKeyFactors"
}
},
"segments": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed segment ID (format `s_`)"
},
"name": {
"type": "string"
}
}
}
},
"recentWebPages": {
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"numVisits"
],
"properties": {
"url": {
"type": "string"
},
"numVisits": {
"type": "integer"
}
}
}
},
"recentWebVisitsNumber": {
"type": "integer"
},
"recentActivities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiActivity"
}
},
"activityCount7d": {
"type": "integer",
"description": "Number of activities in the last 7 days."
},
"activityCount28d": {
"type": "integer",
"description": "Number of activities in the last 28 days."
},
"activityCount8w": {
"type": "integer",
"description": "Number of activities in the last 8 weeks."
},
"activityCount12w": {
"type": "integer",
"description": "Number of activities in the last 12 weeks."
},
"activityCount6m": {
"type": "integer",
"description": "Number of activities in the last 6 months."
},
"activityCount1y": {
"type": "integer",
"description": "Number of activities in the last year."
},
"activityCountAll": {
"type": "integer",
"description": "Number of activities across all time."
},
"activateMessage": {
"type": "object",
"nullable": true,
"required": [
"title",
"message"
],
"properties": {
"title": {
"type": "string"
},
"message": {
"type": "string",
"nullable": true
}
}
},
"sparkSummary": {
"type": "string",
"nullable": true
},
"recentSparkSummaries": {
"type": "array",
"items": {
"type": "string"
}
},
"tags": {
"type": "array",
"description": "Prefixed label IDs (format `l_`)",
"items": {
"type": "string"
}
},
"url": {
"type": "string",
"format": "uri",
"description": "Common Room URL for this contact"
}
}
},
"ApiContactCompany": {
"type": "object",
"description": "A company the contact works or worked at, with the contact's role there and the company's firmographics.",
"required": [
"companyName",
"domain",
"isCurrent",
"jobTitle",
"startDate",
"endDate",
"seniority",
"employeeCount",
"revenueRange",
"industry",
"location"
],
"properties": {
"companyName": {
"type": "string",
"nullable": true
},
"domain": {
"type": "string",
"nullable": true
},
"isCurrent": {
"type": "boolean"
},
"jobTitle": {
"type": "string",
"nullable": true
},
"startDate": {
"type": "string",
"nullable": true
},
"endDate": {
"type": "string",
"nullable": true
},
"seniority": {
"type": "string",
"nullable": true
},
"employeeCount": {
"type": "number",
"nullable": true
},
"revenueRange": {
"type": "object",
"nullable": true,
"required": [
"min",
"max"
],
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number",
"nullable": true
}
}
},
"industry": {
"type": "object",
"nullable": true,
"required": [
"naicsCodes",
"subIndustry"
],
"properties": {
"naicsCodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiNaicsCode"
}
},
"subIndustry": {
"type": "string",
"nullable": true
}
}
},
"location": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ApiLocation"
}
],
"nullable": true
}
}
},
"ContactResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/Contact"
}
}
},
"ContactList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Contact"
}
},
"meta": {
"type": "object",
"required": [
"nextCursor"
],
"properties": {
"nextCursor": {
"type": "string",
"nullable": true,
"description": "Cursor for pagination; pass as the `cursor` query parameter to fetch the next page."
},
"recordCount": {
"type": "integer",
"description": "Total number of records matching the query. Only returned when `cols=recordCount` is requested."
}
}
}
}
},
"Organization": {
"type": "object",
"required": [
"id",
"name",
"primaryDomain"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed organization ID (format `o_`)"
},
"name": {
"type": "string",
"description": "The organization's name"
},
"primaryDomain": {
"type": "string",
"description": "The organization's primary domain name"
},
"about": {
"type": "string",
"nullable": true
},
"contactsCount": {
"type": "integer",
"nullable": true
},
"employees": {
"type": "integer",
"nullable": true
},
"linkedInUrl": {
"type": "string",
"nullable": true
},
"profiles": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type",
"url"
],
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
}
}
},
"revenueRangeMax": {
"type": "integer",
"nullable": true
},
"revenueRangeMin": {
"type": "integer",
"nullable": true
},
"subIndustry": {
"type": "string",
"nullable": true
},
"technologies": {
"type": "array",
"nullable": true,
"description": "Products in the organization's tech stack",
"items": {
"type": "string"
}
},
"location": {
"allOf": [
{
"$ref": "#/components/schemas/ApiLocation"
}
],
"nullable": true
},
"customFields": {
"type": "object",
"description": "Map of custom-field ID (format `cf_`) to its typed value.",
"additionalProperties": {
"$ref": "#/components/schemas/ApiFieldValue"
}
},
"leadScores": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiLeadScore"
}
},
"leadScoreKeyFactors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiLeadScoreKeyFactors"
}
},
"researchResults": {
"type": "array",
"items": {
"type": "object",
"required": [
"promptId",
"answer",
"isPrimaryPrompt",
"promptName"
],
"properties": {
"promptId": {
"type": "string"
},
"answer": {
"type": "string"
},
"isPrimaryPrompt": {
"type": "boolean"
},
"promptName": {
"type": "string"
}
}
}
},
"recentJobOpenings": {
"type": "array",
"items": {
"type": "object",
"required": [
"jobTitle",
"url",
"firstSeenAt",
"isClosed",
"location"
],
"properties": {
"jobTitle": {
"type": "string"
},
"jobDescription": {
"type": "string",
"nullable": true
},
"url": {
"type": "string",
"format": "uri"
},
"firstSeenAt": {
"type": "string"
},
"isClosed": {
"type": "boolean"
},
"location": {
"type": "string",
"nullable": true
}
}
}
},
"recentNews": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"url",
"publishedAt",
"category",
"articleSentence"
],
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"publishedAt": {
"type": "string"
},
"category": {
"type": "string"
},
"articleSentence": {
"type": "string",
"nullable": true
}
}
}
},
"surgingTopics": {
"type": "array",
"description": "Bombora surging topic names this organization is showing buyer intent for. Empty unless the Bombora integration is enabled.",
"items": {
"type": "string"
}
},
"tags": {
"type": "array",
"description": "Prefixed label IDs (format `l_`)",
"items": {
"type": "string"
}
},
"topContacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Contact"
}
},
"url": {
"type": "string",
"format": "uri",
"description": "Common Room URL for this organization"
}
}
},
"OrganizationResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/Organization"
}
}
},
"UpdateObjectResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
},
"OrganizationList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Organization"
}
},
"meta": {
"type": "object",
"required": [
"nextCursor"
],
"properties": {
"nextCursor": {
"type": "string",
"nullable": true,
"description": "Cursor for pagination; pass as the `cursor` query parameter to fetch the next page."
},
"recordCount": {
"type": "integer",
"description": "Total number of records matching the query. Only returned when `cols=recordCount` is requested."
}
}
}
}
},
"ApiSegment": {
"type": "object",
"required": [
"id",
"name",
"entityType"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed segment ID (format `s_`)"
},
"name": {
"type": "string",
"description": "The segment's display name"
},
"entityType": {
"type": "string",
"enum": [
"contact",
"object",
"organization"
],
"description": "The type of entity this segment contains"
},
"entityCount": {
"type": "integer",
"description": "Number of entities in this segment"
},
"url": {
"type": "string",
"format": "uri",
"description": "Common Room URL for this segment"
},
"summary": {
"type": "string",
"nullable": true,
"description": "AI-generated summary of the segment. Null if no summary has been generated yet."
},
"automationStatus": {
"type": "string",
"nullable": true,
"enum": [
"paused",
"running"
],
"description": "Whether the segment's rule-based membership updates are paused or running. Null for manually curated segments."
}
}
},
"SegmentResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/ApiSegment"
}
}
},
"SegmentList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiSegment"
}
},
"meta": {
"type": "object",
"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."
}
}
}
}
},
"CreateSegmentRequest": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "The name for the new segment (max 500 characters)"
},
"description": {
"type": "string",
"description": "Optional description for the segment (markdown supported)"
},
"entityType": {
"type": "string",
"enum": [
"contact",
"object",
"organization"
],
"default": "contact",
"description": "The type of entity this segment will contain"
},
"objectTypeId": {
"type": "string",
"description": "Required when entityType is `object`. Prefixed object type ID (format `cot_`)"
}
}
},
"CreateSegmentResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed segment ID (format `s_`)"
},
"name": {
"type": "string"
}
}
}
}
},
"ApiCustomField": {
"type": "object",
"required": [
"id",
"name",
"entityTypes",
"keyField",
"valueType"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed custom field ID (format `cf_`)"
},
"name": {
"type": "string",
"description": "The custom field's display name"
},
"entityTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"contact",
"object",
"organization"
]
},
"description": "Entity types this field applies to"
},
"keyField": {
"type": "boolean",
"description": "Whether this is a key field used for deduplication"
},
"valueType": {
"type": "string",
"enum": [
"string",
"url",
"int",
"number",
"date",
"boolean"
],
"description": "The data type of field values"
},
"sampleValues": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiFieldValue"
},
"description": "Example values for this field"
},
"description": {
"type": "string",
"nullable": true,
"description": "Human-readable description of the field"
},
"targetSubTypes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sub-types this field targets"
},
"providedBy": {
"type": "string",
"nullable": true,
"description": "Name of the provider that owns this field, if any"
},
"objectTypeId": {
"type": "string",
"description": "Prefixed object type ID (format `cot_`), if this field belongs to a specific object type"
}
}
},
"CustomFieldResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/ApiCustomField"
}
}
},
"CustomFieldList": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiCustomField"
}
}
}
},
"ApiLeadScoreDefinition": {
"type": "object",
"required": [
"id",
"name",
"enabled",
"entityType",
"isPrimaryScore",
"outputType"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed lead score ID (format `ls_`)"
},
"name": {
"type": "string",
"description": "The lead score's display name"
},
"enabled": {
"type": "boolean",
"description": "Whether this lead score is currently enabled"
},
"entityType": {
"type": "string",
"enum": [
"contact",
"organization",
"object"
],
"description": "The type of entity this lead score applies to"
},
"isPrimaryScore": {
"type": "boolean",
"description": "Whether this is the primary score for its entity type"
},
"outputType": {
"type": "string",
"enum": [
"percentile",
"point_value"
],
"description": "The scale this score's value is on. `percentile` scores are filterable with `*LeadScorePercentile`; `point_value` scores hold a raw summed point total and are filterable with `*LeadScorePointValue`. Filtering a score with the wrong key matches nothing."
}
}
},
"LeadScoreDefinitionResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/ApiLeadScoreDefinition"
}
}
},
"LeadScoreDefinitionList": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiLeadScoreDefinition"
}
}
}
},
"ApiTag": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed tag ID (format `l_`)"
},
"name": {
"type": "string",
"description": "The tag's display name"
},
"description": {
"type": "string",
"nullable": true,
"description": "Human-readable description of the tag"
},
"entityTypes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"contact",
"organization",
"activity",
"object"
]
},
"description": "Entity types this tag can be applied to"
},
"objectTypeId": {
"type": "string",
"description": "For object tags, the object type (format `cot_`) whose records the tag applies to"
}
}
},
"TagResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/ApiTag"
}
}
},
"TagList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiTag"
}
},
"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."
}
}
}
}
},
"MeResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "object",
"required": [
"id",
"communityId",
"name",
"role"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed contact ID (format `c_`)"
},
"communityId": {
"type": "string",
"description": "Prefixed community ID (format `com_`)"
},
"name": {
"type": "string",
"description": "The authenticated user's display name"
},
"title": {
"type": "string",
"nullable": true,
"description": "The user's job title"
},
"role": {
"type": "string",
"description": "The user's role in the community"
},
"loginEmail": {
"type": "string",
"nullable": true,
"description": "The user's login email address"
},
"profiles": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"handle"
],
"properties": {
"type": {
"type": "string"
},
"handle": {
"type": "string"
}
}
}
},
"segments": {
"type": "array",
"description": "Segments bookmarked by this user",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"personas": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"company": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"domains": {
"type": "array",
"items": {
"type": "string"
}
},
"summary": {
"type": "string",
"nullable": true
}
}
}
}
}
}
},
"ApiLocationItem": {
"type": "object",
"required": [
"id",
"name",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed location ID"
},
"name": {
"type": "string",
"description": "Display name for the location"
},
"type": {
"type": "string",
"enum": [
"city",
"country",
"country_region",
"world_region"
],
"description": "The granularity of this location"
},
"city": {
"type": "string"
},
"region": {
"type": "string"
},
"country": {
"type": "string"
}
}
},
"LocationItemResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/ApiLocationItem"
}
}
},
"LocationItemList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiLocationItem"
}
},
"meta": {
"type": "object",
"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."
}
}
}
}
},
"ApiTopic": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed topic ID (format `tp_`)"
},
"name": {
"type": "string",
"description": "The topic's display name"
}
}
},
"TopicResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/ApiTopic"
}
}
},
"TopicList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiTopic"
}
},
"meta": {
"type": "object",
"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."
}
}
}
}
},
"ApiActivityCategory": {
"type": "object",
"required": [
"id",
"name",
"value"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed label ID (format `l_`)"
},
"name": {
"type": "string",
"description": "Display name for the category"
},
"value": {
"type": "string",
"description": "Machine-readable category value"
}
}
},
"ActivityCategoryList": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiActivityCategory"
}
}
}
},
"ApiActivitySentiment": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed label ID (format `l_`)"
},
"name": {
"type": "string",
"description": "Display name for the sentiment (e.g. positive, negative, neutral)"
}
}
},
"ActivitySentimentList": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiActivitySentiment"
}
}
}
},
"ApiProvider": {
"type": "object",
"required": [
"id",
"name",
"serviceName"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed signal source ID (format `sig_`)"
},
"name": {
"type": "string",
"nullable": true,
"description": "User-defined display name for this source"
},
"serviceName": {
"type": "string",
"description": "The provider service type (e.g. `slack`, `github`, `salesforce`)"
}
}
},
"ProviderList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiProvider"
}
},
"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."
}
}
}
}
},
"ApiCustomObject": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed custom object ID (format `co_`)"
},
"name": {
"type": "string",
"description": "The object's display name"
},
"url": {
"type": "string",
"format": "uri",
"description": "Common Room URL for this custom object"
},
"recordKey": {
"type": "string",
"description": "External record key for this object"
},
"tags": {
"type": "array",
"description": "Prefixed label IDs (format `l_`)",
"items": {
"type": "string"
}
},
"customFields": {
"type": "object",
"description": "Map of custom-field ID (format `cf_`) to its typed value.",
"additionalProperties": {
"$ref": "#/components/schemas/ApiFieldValue"
}
}
}
},
"CustomObjectResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"$ref": "#/components/schemas/ApiCustomObject"
}
}
},
"CustomObjectList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiCustomObject"
}
},
"meta": {
"type": "object",
"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."
}
}
}
}
},
"ApiObjectTypeAssoc": {
"type": "object",
"required": [
"objectAssocType",
"targetEntity",
"targetObjectTypeId"
],
"properties": {
"objectAssocType": {
"type": "string",
"description": "The relationship type"
},
"targetEntity": {
"type": "string",
"description": "The target entity name (e.g. `Contact`, `Organization`, or a custom object type name)"
},
"targetObjectTypeId": {
"type": "string",
"nullable": true,
"description": "Prefixed target object type ID (format `cot_`), or null for standard entities"
}
}
},
"ApiObjectType": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed object type ID (format `cot_`)"
},
"name": {
"type": "string",
"description": "The object type's display name"
},
"assocs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiObjectTypeAssoc"
},
"description": "Associations to other entity types"
}
}
},
"ObjectTypeList": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiObjectType"
}
}
}
},
"ApiWebsiteVisit": {
"type": "object",
"required": [
"id",
"visitTime"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed website visit cursor (format `w_`)"
},
"visitTime": {
"type": "string",
"format": "date-time",
"description": "When the visit occurred"
},
"url": {
"type": "string",
"format": "uri",
"description": "The visited page URL"
},
"contactId": {
"type": "string",
"description": "Prefixed contact ID (format `c_`)"
},
"organizationId": {
"type": "string",
"description": "Prefixed organization ID (format `o_`)"
}
}
},
"WebsiteVisitList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiWebsiteVisit"
}
},
"meta": {
"type": "object",
"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."
}
}
}
}
},
"ApiBuyingCommitteePerson": {
"type": "object",
"required": [
"id",
"source",
"name",
"title",
"email",
"url",
"linkedInUrl",
"temperature",
"lastEngagedAt",
"lastTouchedAt"
],
"properties": {
"id": {
"type": "string",
"description": "Contact or Prospector contact ID"
},
"source": {
"type": "string",
"enum": [
"contact",
"prospector"
]
},
"name": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"email": {
"type": "string",
"nullable": true,
"description": "Always null when `source` is `prospector`; Prospector professional emails are intentionally withheld by this API, matching the buying committee view in the product."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Common Room profile for this contact. Null when `source` is `prospector`, which has no Common Room profile."
},
"linkedInUrl": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "LinkedIn profile for this person. Null when `source` is `contact`."
},
"temperature": {
"type": "string",
"enum": [
"engaged",
"warm",
"cold"
],
"description": "Engagement classification based on the workspace's buying committee signal settings and time windows. `engaged` means the person has a qualifying engaged signal within the configured engaged window. `warm` means there is no current engaged signal, but a qualifying warm signal or an older engaged signal within its configured warm extension. `cold` means neither condition is met. Signal groups and time windows are configurable, so these labels do not imply fixed activity types or durations across workspaces."
},
"lastEngagedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Activity timestamp used for the candidate's engaged or warm classification: the most recent engaged activity for engaged candidates, or warm activity for warm candidates. Null for cold candidates."
},
"lastTouchedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
},
"ApiBuyingCommitteeCell": {
"type": "object",
"required": [
"id",
"department",
"seniority",
"contacts"
],
"properties": {
"id": {
"type": "string"
},
"department": {
"type": "object",
"required": [
"id",
"key",
"name"
],
"properties": {
"id": {
"type": "integer",
"description": "Internal numeric identifier. Prefer `key` for a stable machine-readable value."
},
"key": {
"type": "string",
"description": "Stable machine-readable department key, e.g. `Sales`"
},
"name": {
"type": "string",
"description": "Display name, e.g. `Sales`"
}
}
},
"seniority": {
"type": "object",
"required": [
"id",
"key",
"name"
],
"properties": {
"id": {
"type": "integer",
"description": "Internal numeric identifier. Prefer `key` for a stable machine-readable value."
},
"key": {
"type": "string",
"description": "Stable machine-readable seniority key, e.g. `CLevel`"
},
"name": {
"type": "string",
"description": "Display name, e.g. `C-Level`"
}
}
},
"contacts": {
"type": "array",
"description": "All available ranked contacts from the bounded cell sample; always returned",
"items": {
"$ref": "#/components/schemas/ApiBuyingCommitteePerson"
}
}
}
},
"BuyingCommitteeCellList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiBuyingCommitteeCell"
}
},
"meta": {
"type": "object",
"required": [
"nextCursor"
],
"properties": {
"nextCursor": {
"type": "string",
"nullable": true,
"description": "Always `null` for this endpoint — the full committee is returned in one response"
},
"recordCount": {
"type": "integer",
"description": "Returned only when `cols=recordCount` is requested"
}
}
}
}
},
"ApiJobOpening": {
"type": "object",
"required": [
"id",
"jobTitle",
"url",
"firstSeenAt",
"isClosed",
"location"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed job opening ID (format `j_`)"
},
"jobTitle": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri",
"description": "Link to the posting"
},
"firstSeenAt": {
"type": "string",
"format": "date-time",
"description": "When the posting was first published or first discovered"
},
"isClosed": {
"type": "boolean",
"description": "Whether the posting is closed. Also true when the posting has not been observed for 30 days, even if the source has not marked it closed."
},
"location": {
"type": "string",
"nullable": true
},
"jobDescription": {
"type": "string",
"nullable": true,
"description": "Full posting text. Only returned when `cols=jobDescription` is requested."
}
}
},
"JobOpeningList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiJobOpening"
}
},
"meta": {
"type": "object",
"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."
}
}
}
}
},
"ApiNewsItem": {
"type": "object",
"required": [
"id",
"title",
"url",
"publishedAt",
"category",
"articleSentence"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed news item ID (format `n_`)"
},
"title": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"publishedAt": {
"type": "string",
"format": "date-time"
},
"category": {
"type": "string",
"description": "Category name, e.g. `receives_financing`. Note that the `recentNews` column on an organization reports this as a numeric string instead."
},
"articleSentence": {
"type": "string",
"nullable": true,
"description": "The sentence from the article that mentions the organization"
}
}
},
"NewsItemList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiNewsItem"
}
},
"meta": {
"type": "object",
"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."
}
}
}
}
},
"ApiProspectorContact": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prospector contact ID"
},
"name": {
"type": "string",
"description": "The contact's display name"
},
"avatarUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"companyName": {
"type": "string",
"nullable": true
},
"companyWebsite": {
"type": "string",
"format": "uri",
"nullable": true
},
"fullName": {
"type": "string",
"nullable": true
},
"linkedInFollowerCount": {
"type": "number",
"nullable": true
},
"linkedInHandle": {
"type": "string",
"nullable": true
},
"location": {
"allOf": [
{
"$ref": "#/components/schemas/ApiLocation"
}
],
"nullable": true
},
"role": {
"type": "string",
"nullable": true
},
"seniority": {
"type": "string",
"nullable": true
},
"skills": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"title": {
"type": "string",
"nullable": true
}
}
},
"ProspectorContactList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiProspectorContact"
}
},
"meta": {
"type": "object",
"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."
}
}
}
}
},
"ApiProspectorCompanyLocation": {
"type": "object",
"properties": {
"address": {
"type": "string",
"nullable": true
},
"city": {
"type": "string",
"nullable": true
},
"state": {
"type": "string",
"nullable": true
},
"country": {
"type": "string",
"nullable": true
},
"countryCode": {
"type": "string",
"nullable": true
}
}
},
"ApiProspectorCompany": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prospector company ID"
},
"name": {
"type": "string",
"description": "The company's display name"
},
"description": {
"type": "string",
"nullable": true
},
"employees": {
"type": "number",
"nullable": true
},
"linkedInHandles": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"location": {
"allOf": [
{
"$ref": "#/components/schemas/ApiProspectorCompanyLocation"
}
],
"nullable": true
},
"logoUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"primaryWebsite": {
"type": "string",
"nullable": true
},
"raised": {
"type": "number",
"nullable": true,
"description": "Total capital raised"
},
"revenueRange": {
"type": "object",
"nullable": true,
"properties": {
"min": {
"type": "number"
},
"max": {
"type": "number",
"nullable": true
}
}
},
"subIndustry": {
"type": "string",
"nullable": true
},
"technologies": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
}
}
},
"ProspectorCompanyList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiProspectorCompany"
}
},
"meta": {
"type": "object",
"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."
}
}
}
}
},
"ApiNaicsCode": {
"type": "object",
"required": [
"id",
"code",
"name"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed NAICS code ID (format `naics_`)"
},
"code": {
"type": "integer",
"description": "The numeric NAICS code"
},
"name": {
"type": "string",
"description": "Industry name"
}
}
},
"NaicsCodeList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiNaicsCode"
}
},
"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."
}
}
}
}
},
"ApiTechStackProduct": {
"type": "object",
"required": [
"id",
"product",
"vendor"
],
"properties": {
"id": {
"type": "string",
"description": "Prefixed product ID (format `p_`)"
},
"product": {
"type": "string",
"description": "Product name"
},
"vendor": {
"type": "string",
"description": "Vendor name"
}
}
},
"TechStackProductList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiTechStackProduct"
}
},
"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."
}
}
}
}
},
"JobTitleListItem": {
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "string"
}
}
},
"JobTitleList": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobTitleListItem"
}
},
"meta": {
"type": "object",
"required": [
"nextCursor"
],
"properties": {
"nextCursor": {
"type": "string",
"nullable": true,
"description": "Opaque best-effort cursor; concurrent writes may affect pagination consistency."
}
}
}
}
},
"AnalyticsColumn": {
"type": "object",
"required": [
"name",
"role"
],
"properties": {
"name": {
"type": "string",
"description": "The column's key in each row."
},
"role": {
"type": "string",
"description": "`dimension` for the columns that identify a row, `attribute` for columns that describe its dimension, and `metric` for computed values."
},
"type": {
"type": "string",
"description": "Set on `timestamp`, `date` and `list` columns. New values may be added."
},
"unit": {
"type": "string",
"description": "Metrics only. What one unit counts, such as `task`, `record`, `contact` or `rep`."
},
"temporality": {
"type": "string",
"description": "Metrics only. `window` counts within the window. `snapshot` is the state at the latest daily\nsnapshot up to the window's end, or on `asOf`; the snapshot's date is in the row's `snapshotDate`.\n"
},
"nullable": {
"type": "boolean"
}
}
},
"AnalyticsQueryResponse": {
"type": "object",
"required": [
"success",
"data",
"meta"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "array",
"description": "One object per row: the grouped dimensions' columns, then the requested metrics, then\n`snapshotDate` when a snapshot metric is requested. Each value is computed for the requested\ngrouping, so adding rows doesn't reproduce a coarser total; request the coarser `groupBy` instead.\n",
"items": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string",
"nullable": true
},
{
"type": "number",
"nullable": true
},
{
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
}
]
}
}
},
"meta": {
"type": "object",
"required": [
"entity",
"groupBy",
"time",
"scope",
"columns",
"rowCount",
"totalRows",
"notes"
],
"properties": {
"entity": {
"type": "string",
"description": "The population the metrics describe, `rep` or `repAction`."
},
"groupBy": {
"type": "array",
"items": {
"type": "string"
}
},
"time": {
"type": "object",
"description": "The resolved window (`start`, `end` and `timeZone`), or `asOf`.",
"properties": {
"start": {
"type": "string",
"format": "date-time"
},
"end": {
"type": "string",
"format": "date-time"
},
"timeZone": {
"type": "string"
},
"asOf": {
"type": "string",
"format": "date"
}
}
},
"scope": {
"type": "object",
"required": [
"teams",
"repCount"
],
"properties": {
"teams": {
"type": "array",
"description": "The teams the request covers.",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"example": "p_31"
},
"name": {
"type": "string"
}
}
}
},
"repCount": {
"type": "integer",
"description": "The number of reps counted."
}
}
},
"columns": {
"type": "array",
"description": "One entry per row column, in row order.",
"items": {
"$ref": "#/components/schemas/AnalyticsColumn"
}
},
"rowCount": {
"type": "integer"
},
"totalRows": {
"type": "integer",
"description": "Rows before `limit` was applied; for action rows, every row across the pages."
},
"nextCursor": {
"type": "string",
"description": "Action rows only, when more pages follow. Pass it back as `cursor` with the same parameters."
},
"notes": {
"type": "array",
"description": "Caveats about the result, such as a missing snapshot that leaves snapshot metrics null.",
"items": {
"type": "string"
}
}
}
}
}
},
"AnalyticsCatalogResponse": {
"type": "object",
"required": [
"success",
"data"
],
"properties": {
"success": {
"type": "boolean",
"enum": [
true
]
},
"data": {
"type": "object",
"required": [
"entities",
"dimensions",
"filters",
"metrics"
],
"description": "What `GET /analytics/query` accepts. Each metric names its entity, unit and temporality and lists\nthe `groupBy` combinations it supports. Each dimension lists the columns it adds to a row. Each\nfilter is a query parameter that chooses who is counted. New entries and fields may be added.\n",
"properties": {
"entities": {
"type": "array",
"items": {
"type": "object"
}
},
"dimensions": {
"type": "array",
"items": {
"type": "object"
}
},
"filters": {
"type": "array",
"items": {
"type": "object"
}
},
"metrics": {
"type": "array",
"items": {
"type": "object"
}
}
}
}
}
},
"ApiToken": {
"type": "object",
"properties": {
"jti": {
"type": "string",
"example": "tcpgph92"
},
"communityName": {
"type": "string",
"example": "Uncommon"
},
"communityId": {
"type": "string",
"example": "8p980hdo0"
}
}
},
"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"
]
}
}
}
}
}