Use this endpoint to search for individuals at specific companies.
You can filter contacts by details such as first name, last name, email, location, job title, job level, and job function. Company-level filters include company name, website, location, industry, size, and more. Additional parameters allow you to filter by quality score, email validation status, and phone requirements.
Sorting and pagination are supported. You can sort results by fields such as companyName, and control the number of results returned using page and perPage.
You must include at least one parameter (excluding sorting and pagination) to perform a search.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Search contacts
Find professionals at target accounts using person, employment, and company attributes. Search by name, email, title, seniority, job function, company, location, email availability, phone availability, and more.
What you can search for
Contact Search is best when you know the company, role, seniority, function, or data quality requirements for the people you want to find.
Find contacts at an account
Search by company name, website, Demandbase company ID, location, industry, or employee count.
Find people by title
Search for specific job titles such as Director, VP, CISO, Marketing Operations, or Revenue Operations.
Find executives or managers
Use job level filters to target executives, directors, managers, individual contributors, and other seniority groups.
Find teams by department
Filter by job function such as IT, Marketing, Sales, Finance, Operations, Engineering, or Human Resources.
Require email availability
Return contacts with emails and optionally require validated email status.
Require phone availability
Return contacts with phone data and choose direct, corporate, mobile, or any phone type.
Common searches
Find contacts at a company
Find contacts by company website
Find IT leaders
Find contacts with validated email
Find contacts with mobile phones
Find active contacts only
Quickstart
Send a POST request to /contacts with at least one search filter. This example searches for contacts at Microsoft.
Send the request
Read the response
Request anatomy
firstName | First name |
lastName | Last name |
email | Email address |
contactCity | Contact city |
contactState | Contact state |
contactCountry | Contact country ID |
titles | Job titles |
jobLevels | Seniority IDs |
jobFunctions | Function IDs |
active | Active employment |
minContactQualityScore | Minimum quality score |
companyName | Company name |
companyWebsite | Company website |
companyIdsToInclude | Demandbase company IDs |
industries | Industry IDs |
minEmployees | Minimum employees |
maxEmployees | Maximum employees |
Response anatomy
Each result contains person-level details and employment-level details. Use dbPersonId to identify the person and contactId to identify a specific employment record.
Persistent person profile
Contains the Demandbase person ID and basic person attributes.
dbPersonId | Persistent person identifier |
firstName | First name |
lastName | Last name |
Company-specific role
Contains the contact ID, company ID, title, seniority, function, active status, and quality score.
contactId | Employment/contact identifier |
companyId | Demandbase company ID |
titles | Current known titles |
jobLevels | Seniority classifications |
jobFunctions | Functional classifications |
active | Whether the employment is active |
Important rules
Include one search filter
You must include at least one parameter other than sorting and pagination.
Use 1–50 results per page
perPage must be between 1 and 50. page must be 1 or greater.
Sort only supported fields
Sorting is supported for active, title, and companyName.
Filter reference
| Filter | Use it to | Example |
|---|---|---|
companyName | Find contacts at a named company. | Microsoft |
companyWebsite | Find contacts at a company by domain. | microsoft.com |
companyIdsToInclude | Find contacts at specific Demandbase company IDs. | ["726263"] |
titles | Find contacts by title keywords. | ["Director", "VP"] |
jobLevels | Find contacts by seniority level IDs. | ["3", "4"] |
jobFunctions | Find contacts by functional role IDs. | ["9"] |
emailRequired | Require contacts with email data. | "true" |
emailValidationStatus | Filter by email validation status. | ValidEmail |
phoneRequired | Require contacts with phone data. | "true" |
phoneType | Filter by phone type. | mobile |
active | Filter active or inactive employment records. | "true" |
minContactQualityScore | Require a minimum quality score. | A |
Empty results
If no contacts match the query, the API returns a successful response with an empty contactResults array.
Common errors
| Status | Error | How to fix it |
|---|---|---|
400-107 |
At least one parameter must be provided. | Add at least one search filter such as companyName, companyWebsite, titles, or jobFunctions. |
400-101 |
perPage must be between 1 and 50. |
Set perPage to a value from 1 to 50. |
400-100 |
Page number must be greater than or equal to 1. | Set page to 1 or greater. |
400-108 |
Invalid sort field. | Use active, title, or companyName. |
400-109 |
Invalid sort order. | Use asc or desc. |
400-123 |
Invalid minimum contact quality score. | Use one of A+, A, B, or C. |
401 |
Authentication failed. | Generate a valid token and send it in the Authorization: Bearer YOUR_ACCESS_TOKEN header. |
403 |
Forbidden. | Your token is valid, but does not have access to this endpoint or the requested resource. Confirm your API Key Set includes B2B API access. |
429 |
Too many requests. | You exceeded the rate limit. Retry after waiting, reduce request volume, and use backoff for automated jobs. |
Next steps
After finding contacts, use related endpoints to fetch company details, resolve records, or enrich larger datasets.
Company Profile → · Match records → · Bulk jobs →