List prospector contacts
Retrieve a paginated list of prospector-discovered contacts.
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
Comma-separated list of additional columns to include in the response. Valid column values: avatarUrl, companyName, companyWebsite, fullName, linkedInFollowerCount, linkedInHandle, location, role, seniority, skills, title. The meta column recordCount can be requested to return the total number of matching contacts in meta.recordCount.
Structured filter as URL-encoded JSON — see the LightFilterExpression schema for the grammar. Conditions are combined (AND) with the other query parameters.
Filterable fields:
| Field | Filter type | Operators | Description |
|---|---|---|---|
| fullName | stringFilter | eq, like, empty, notEmpty | Filter prospector contacts by name. |
| title | stringFilter | eq, like | Filter prospector contacts by job title. |
| companyName | stringFilter | eq, like | Filter prospector contacts by their current company name. |
| companyDomain | stringFilter | eq, like | Filter prospector contacts by their current company domain/website (e.g., "acme.com"). |
| locationId | stringListFilter | any, none, empty, notEmpty | Filter prospector contacts by location. Discover location IDs via GET /locations. |
| previousCompanyName | stringFilter | eq, like | Filter prospector contacts by their previous company/organization name. |
| previousCompanyDomain | stringFilter | eq, like | Filter prospector contacts by their previous company/organization domain/website (e.g., "acme.com"). |
| linkedInFollowerCount | numberFilter | eq, ne, gt, gte, lt, lte | Filter prospector contacts by LinkedIn follower count. |
| lastOrgChange | dateRangeFilter | in, between, after, before | Filter prospector contacts by when they last changed organizations (job change date). |
| 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. |
| memberSeniority | stringListFilter | any, none | Filter prospector contacts by normalized job seniority. Valid values: Intern, Junior IC, Senior IC, Manager, Director, VP, C-Level. |
| memberHasEmail | booleanFilter | eq, ne | Filter prospector contacts by whether they have a professional email address. The address itself is not returned. |
| memberHasPhoneNumber | booleanFilter | eq, ne | Filter prospector contacts by whether they have a phone number. The number itself is not returned. |
Filtering by company: to filter on a contact's current company, add a group whose target is ProspectorCompany. Its clauses use the company fields below, and it matches contacts whose current company satisfies them. Combine it with contact fields at the top level. For example, salespeople at software companies with at least 200 employees:
{
"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"] } }
]
}
]
}
- Every group must send target, objectConfigId and targetAssocPaths, using null for any it doesn't use.
- A company group needs at least one clause, and can contain nested and/or groups of company fields.
- It always means the current company. Previous companies are reachable only through previousCompanyName and previousCompanyDomain.
- This endpoint accepts the targets ProspectorCompany and ProspectorContact (the same as no target). Any other target returns a 400.
Company fields:
| Company field | Name | Filter type |
|---|---|---|
| Name | groupName | stringFilter |
| Website | groupWebsite | stringFilter |
| LinkedIn handle | groupLinkedinHandle | stringListFilter |
| Employee count | groupCompanySize | numberFilter |
| Revenue | groupRevenue | numberFilter |
| Capital raised | groupCapitalRaised | numberFilter |
| Location | groupLocationId | stringListFilter (location IDs from GET /locations) |
| NAICS industry code | groupIndustryCode | stringListFilter (codes from GET /industries) |
| Sub-industry | groupSubIndustry | stringListFilter |
| Technology | groupTechStackId | stringListFilter (IDs from GET /tech-stack-products) |
The company fields, operators and values are the same as on GET /prospector-companies.
Response
OK
Changes
No recorded changes to this operation across all 1 revision of this API.