--- title: "List contacts" method: GET path: "/contacts" tags: ["Contacts"] --- # List contacts `GET /contacts` ## Request - Base URL: `https://api.commonroom.io/api/v2` - URL: `https://api.commonroom.io/api/v2/contacts` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieve a list of contacts with pagination support. ## Query parameters - `limit` integer - `cursor` string - `sort` string - `direction` 'asc' | 'desc' - `cols` string - `organizationId` string - `segmentId` string ## Response `200` OK - ContactList - `success` true, required - `data` Contact[], required - `id` string, required: Prefixed contact ID (format `c_`) - `name` string, required: The contact's display name - `avatarUrl` string, uri, nullable - `fullName` string, nullable - `location` ApiLocation: A best-effort location, with each component populated when known. - `city` string: City name - `region` string: State, province, or region name - `country` string: Country name - `countryCode` string: Two-letter ISO 3166-1 country code - `primaryEmail` string, nullable - `phoneNumbers` object[] - `type` string, required - `value` string, required - `isPremium` boolean, required: Whether the number is a premium (paid) phone number - `title` string, nullable - `companyName` string, nullable - `companyWebsite` string, nullable - `linkedInUrls` string[]: LinkedIn profile URLs - `gitHubUrls` string[]: GitHub profile URLs - `xUrls` string[]: X (formerly Twitter) profile URLs - `connectedCustomObjects` object[] - `id` string, required: Prefixed custom object ID (format `co_`) - `name` string, required - `objectType` string, required - `customFields` object: Map of custom-field ID (format `cf_`) to its typed value. - `profiles` object[] - `type` string, required - `value` string, required - `jobHistory` object[]: The 3 most recent positions, current positions first. Use fullJobHistory for the complete list. - `company` string, required - `title` string, nullable, required - `startDate` string, required - `endDate` string, nullable, required - `fullJobHistory` object[]: Complete employment history, current positions first then by startDate descending. - `company` string, required - `domain` string, required - `title` string, nullable, required - `startDate` string, required - `endDate` string, nullable, required - `isCurrent` boolean, required - `jobChangeDate` string, nullable: Date the contact started at their current company - `currentCompany` ApiContactCompany: A company the contact works or worked at, with the contact's role there and the company's firmographics. - `companyName` string, nullable, required - `domain` string, nullable, required - `isCurrent` boolean, required - `jobTitle` string, nullable, required - `startDate` string, nullable, required - `endDate` string, nullable, required - `seniority` string, nullable, required - `employeeCount` number, nullable, required - `revenueRange` object, nullable, required - `min` number, required - `max` number, nullable, required - `industry` object, nullable, required - `naicsCodes` ApiNaicsCode[], required - `id` string, required: Prefixed NAICS code ID (format `naics_`) - `code` integer, required: The numeric NAICS code - `name` string, required: Industry name - `subIndustry` string, nullable, required - `location` ApiLocation, required: A best-effort location, with each component populated when known. - `city` string: City name - `region` string: State, province, or region name - `country` string: Country name - `countryCode` string: Two-letter ISO 3166-1 country code - `previousCompany` ApiContactCompany: A company the contact works or worked at, with the contact's role there and the company's firmographics. - `companyName` string, nullable, required - `domain` string, nullable, required - `isCurrent` boolean, required - `jobTitle` string, nullable, required - `startDate` string, nullable, required - `endDate` string, nullable, required - `seniority` string, nullable, required - `employeeCount` number, nullable, required - `revenueRange` object, nullable, required - `min` number, required - `max` number, nullable, required - `industry` object, nullable, required - `naicsCodes` ApiNaicsCode[], required - `id` string, required: Prefixed NAICS code ID (format `naics_`) - `code` integer, required: The numeric NAICS code - `name` string, required: Industry name - `subIndustry` string, nullable, required - `location` ApiLocation, required: A best-effort location, with each component populated when known. - `city` string: City name - `region` string: State, province, or region name - `country` string: Country name - `countryCode` string: Two-letter ISO 3166-1 country code - `leadScores` ApiLeadScore[] - `scoreId` integer, required: The numeric ID of the lead-score definition - `score` number, required: The raw score for this contact or organization - `percentile` number, required: The percentile rank of the score within the community - `leadScoreKeyFactors` ApiLeadScoreKeyFactors[] - `scoreId` integer, required: The numeric ID of the lead-score definition - `factors` object[], required - `label` string, required: Human-readable name of the scored attribute, custom field, nested score, or research prompt - `value` string, nullable, required: The matched value, rendered for display. Null when the value has no readable rendering without per-workspace lookups (tags, segments, technologies, programming languages). - `strength` number, required: Points this factor contributed to the score; negative for detractors - `segments` object[] - `id` string, required: Prefixed segment ID (format `s_`) - `name` string, required - `recentWebPages` object[] - `url` string, required - `numVisits` integer, required - `recentWebVisitsNumber` integer - `recentActivities` ApiActivity[] - `id` string, required: Prefixed activity ID (format `a_`) - `type` string, required: Activity type identifier (e.g. `tweet`, `pr_comment`) - `activityTime` string, date-time, required: When the activity occurred - `contactId` string: Prefixed contact ID (format `c_`) - `content` string, nullable - `isUserInitiated` boolean - `participantCount` integer - `providerId` string: Prefixed signal source ID (format `sig_`) - `providerName` string, nullable - `replyCount` integer - `sentiment` string, nullable - `subSourceNames` string[] - `url` string, uri - `activityCount7d` integer: Number of activities in the last 7 days. - `activityCount28d` integer: Number of activities in the last 28 days. - `activityCount8w` integer: Number of activities in the last 8 weeks. - `activityCount12w` integer: Number of activities in the last 12 weeks. - `activityCount6m` integer: Number of activities in the last 6 months. - `activityCount1y` integer: Number of activities in the last year. - `activityCountAll` integer: Number of activities across all time. - `activateMessage` object, nullable - `title` string, required - `message` string, nullable, required - `sparkSummary` string, nullable - `recentSparkSummaries` string[] - `tags` string[]: Prefixed label IDs (format `l_`) - `url` string, uri: Common Room URL for this contact - `meta` object, required - `nextCursor` string, nullable, required: Cursor for pagination; pass as the `cursor` query parameter to fetch the next page. - `recordCount` integer: Total number of records matching the query. Only returned when `cols=recordCount` is requested. ## Other responses - `400`: Bad Request — also returned for malformed filters, e.g. "Invalid lightFilter: must be valid JSON", "Invalid lightFilter: does not match LightFilterExpression schema", or an unknown filter field. - `403`: Forbidden - `429`: Rate Limited --- [API](https://skmtc.dev/commonroom/apis/common-room-api-v2.md) - [All operations](https://skmtc.dev/commonroom/apis/common-room-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/commonroom/apis/common-room-api-v2/revisions/865d4d43dadf?raw)