List contacts
Retrieve a list of contacts with pagination support.
Request
- Base URLhttps://api.commonroom.io/api/v2
- AuthHTTP bearer
- TypeScriptA function with typed inputs. Its response is checked against the schema.
Query parameters
The maximum number of contacts to return per page
Pagination cursor from a previous response
Field to sort results by. One of: id, latest_activity, name, a lead-score ID (format ls_<number>), a custom-field ID (format cf_<number>), or an activity-count sort: activity_count_7d, activity_count_28d, activity_count_8w, activity_count_12w, activity_count_6m, activity_count_1y, activity_count_all. Activity-count sorts rank contacts by number of activities in that trailing window; use direction=desc and request the matching activityCount* column to see the counts.
Sort direction
Comma-separated list of additional columns to include in the response. Valid column values: activateMessage, avatarUrl, fullName, location, primaryEmail, phoneNumbers, title, companyName, companyWebsite, linkedInUrls, gitHubUrls, xUrls, connectedCustomObjects, profiles, jobHistory, fullJobHistory, jobChangeDate, currentCompany, previousCompany, leadScores, leadScoreKeyFactors, recentActivities, recentWebPages, recentWebVisitsNumber, segments, sparkSummary, recentSparkSummaries, tags, url, activityCount7d, activityCount28d, activityCount8w, activityCount12w, activityCount6m, activityCount1y, activityCountAll. Use cf_* to include all custom fields, or cf_<id> for a specific one. The meta column recordCount can be requested to return the total number of matching contacts in meta.recordCount.
Filter contacts by prefixed organization ID (format o_<number>)
Filter contacts by segment ID (e.g. s_123456)
Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters.
Filterable fields:
| Field | Filter type | Operators | Description |
|---|---|---|---|
| memberHasEmail | booleanFilter | eq, ne | Filter contacts by whether they have an email address. |
| isTeamMember | booleanFilter | eq, ne | Filter contacts by whether they are a teammate (workspace user). |
| memberHasPrimaryEmail | booleanFilter | eq, ne | Filter contacts by whether they have a primary email. |
| memberHasPrimaryBusinessEmail | booleanFilter | eq, ne | Filter contacts by whether they have a primary business email. |
| memberHasPhoneNumber | booleanFilter | eq, ne | Filter contacts by whether they have a phone number. |
| memberHasPrimaryPhoneNumber | booleanFilter | eq, ne | Filter contacts by whether they have a primary phone number. |
| memberHasPremiumPhoneNumber | booleanFilter | eq, ne | Filter contacts by whether they have a premium phone number. |
| memberRole | stringListFilter | any, none | Filter contacts by job role — case-insensitive free text matched against the contact's stored role (e.g. "Software Engineer", "VP of Sales"), not a fixed category list. Discover the role values present in this workspace via GET /member-roles (most common roles, ranked by contact count). For normalized seniority buckets use memberSeniority. |
| memberSeniority | stringListFilter | any, none | Filter contacts by normalized job seniority. Valid values: Intern, Junior IC, Senior IC, Manager, Director, VP, C-Level. |
| memberEmail | stringFilter | eq, like | Filter contacts by email. Pass a full address ("needshelp@acme.com") for exact case-insensitive lookup, or a domain ("acme.com" / "@acme.com") to match anyone on that domain. |
| memberEmailDomain | stringListFilter | any, none | Filter contacts by email domain. Performs exact domain matching — "mail.com" will not match "gmail.com". Pass one or more domains without the "@" prefix (e.g., ["acme.com", "example.org"]). |
| companyName | stringFilter | eq, like | Filter contacts by their company/organization name (e.g., "Acme Corp"). |
| companyWebsite | stringFilter | eq, like | Filter contacts by their company/organization website domain (e.g., "acme.com"). |
| fullName | stringFilter | eq, like | Filter contacts by name |
| title | stringFilter | eq, like, empty, notEmpty | Filter contacts by job title; empty/notEmpty (with a null value) match contacts without or with any title. |
| memberSegmentId | stringListFilter | any, all, none | Filter by segment (play) membership. Use segment IDs from GET /segments. |
| groupId | stringListFilter | any, none | Filter by organization membership. Use organization IDs from GET /organizations. |
| memberLabelId | stringListFilter | any, all, none | Filter contacts by tag/label ID(s). Use tag IDs from GET /tags (e.g., "l_131504"). |
| locationId | stringListFilter | any, none | Filter contacts by location ID(s). Use location IDs from GET /locations. |
| memberLeadScorePercentile | leadScoreFilter | eq, ne, gt, gte, lt, lte | Filter contacts by lead score percentile (0-100). Requires a scoreId from GET /lead-scores. |
| ls_* | numberFilter | eq, ne, gt, gte, lt, lte | Filter contacts by a Point Value lead score's raw point total, using the score ID as the field name. May be negative or fractional. Only scores whose outputType is point_value match; use memberLeadScorePercentile for percentile scores. |
| memberWebVisitLastSeen | dateRangeFilter | in, between, after, before | Filter contacts by when they last visited the website. |
| memberWebVisitFirstSeen | dateRangeFilter | in, between, after, before | Filter contacts by when they first visited the website. |
| memberWebVisitPageViews | numberFilter | eq, ne, gt, gte, lt, lte | Filter contacts by total tracked web page-view count (all-time). |
| memberWebVisitPagesViewed | webVisitPages | any, none | Filter contacts by which web pages they visited within a window. Provide page URL patterns, an interval (ISO 8601 duration, e.g. "P30D"), and optional minimum page views. |
| memberLastActivity | dateRangeFilter | in, between, after, before | Filter contacts by when they were last active. |
| memberJobChangedAt | dateRangeFilter | in, between, after, before | Filter contacts by when they changed jobs (started at a new company). Prefer a window with op in and an ISO 8601 duration (e.g. "P90D" for the last 90 days). Job changes are typically detected within a few months of the change taking place. |
| cf_* | stringFilter | varies by field type | Filter by custom field value. Use the custom field ID (e.g., "cf_123456") as the field name. Find field IDs and their types via GET /custom-fields. Supports stringFilter for text fields, stringListFilter for enum/dropdown fields, numberFilter for numeric fields, booleanFilter for checkbox fields, and dateRangeFilter for date fields. |
Filtering by a related entity: a group whose target names another entity applies its clauses to that entity, using the fields of that entity's list endpoint. Every group must send target, objectConfigId and targetAssocPaths, using null for any it doesn't use. Targets this endpoint accepts:
| Target | Matches contacts | Clauses use |
|---|---|---|
| Contact (alias Member) | that match the clauses, the same as no target | the fields above |
| Organization (alias Company) | whose organization matches | GET /organizations fields |
| Object | associated with a matching custom object; set objectConfigId to its type (cot_<id>) | GET /objects fields |
| Activity | with at least one matching activity | GET /activities fields |
Any other target returns a 400.
Response
OK
Changes
No recorded changes to this operation across all 1 revision of this API.