Match companies and contacts
Resolve company and contact records against Demandbase using the firmographic and person details you already have. Submit up to 30 uniquely identified records in one synchronous request and correlate each result with your original input ID.
What you can match
Each request can contain company evidence, contact evidence, or both. Supplying complementary attributes generally gives the service more context for selecting the best result.
Resolve an organization
Match using a company name, website, ticker, location, phone number, or other available firmographic details.
Resolve a person and role
Add a name, title, email address, phone number, or LinkedIn handle to identify a contact associated with the company.
Connect the person to the company
Submit company and contact attributes together to return the best contact match and its corresponding company.
Match several records at once
Place up to 30 input objects in the requests array for synchronous matching.
Filter contact quality
Use minContactQualityScore to require a minimum contact quality grade.
Preserve your source identifier
The response returns each input id, making it straightforward to map results back to your records.
Common matching patterns
Match by company name and website
Match a contact at a company
Match by email
Match multiple records
Quickstart
Give every request a unique id and include enough company or contact information to identify the record.
Send company and contact evidence
Correlate the match by ID
An unmatched record is still a successful response
When no result meets the matching criteria, the API returns 200 OK with the input id and empty
companyMatches and contactMatches arrays.
Request anatomy
Provide the request array
The JSON body contains a required, non-empty requests array.
requests |
1–30 match objects |
Identify every source record
Each object needs a non-blank id that is unique within the request.
id |
Required correlation identifier |
Authenticate and send JSON
Authenticate with a bearer token and identify the request body as JSON.
Authorization |
Bearer access token |
Content-Type |
application/json |
Accept |
application/json or application/xml |
Include at least one identifying attribute
Every request item must contain at least one of name, websites, ticker,
email, or executiveLinkedInHandle. Add location and contact details when available to provide more matching context.
Input fields
Only id is universally required. Provide the fields you know and omit unknown values instead of sending empty strings.
Organization attributes
name | Company name |
websites | Array of company websites or domains |
ticker | Stock ticker |
country | Country |
state | State or region |
city | City |
street | Street address |
zip | Postal code |
phone | Company or contact phone number |
Person and employment attributes
firstName | Contact first name |
lastName | Contact last name |
fullName | Contact full name |
title | Current or expected title |
email | Business email address |
executiveLinkedInHandle | LinkedIn profile handle |
isPhoneRequired | Boolean phone-match requirement |
isEmailRequired | Boolean email-match requirement |
contactMatching | active to restrict matching to active contacts |
contactStatus | current or all |
Response anatomy
The top-level matches array contains a result for each submitted input ID.
Match result
id | Your original request identifier |
companyMatches | Matched company records |
contactMatches | Matched contact records |
Company fields
companyId | Demandbase company ID |
name | Matched company name |
street | Street address |
city | City |
state | State or region |
country | Country |
Contact fields
contactId | Demandbase contact ID |
dbPersonId | Demandbase Person ID |
companyId | Associated company ID |
firstName | First name |
lastName | Last name |
title | Current title |
contactQualityScore | Contact quality grade |
active | Employment activity indicator |
Classification and location fields
| Field | Description | Field | Description |
|---|---|---|---|
jobLevels |
Job-level IDs | jobLevelCodes |
Job-level codes |
jobFunctions |
Job-function IDs | jobFunctionCodes |
Job-function codes |
dbPersonCity |
Person city | dbPersonState |
Person state or region |
dbPersonCountry |
Person country |
Use the returned ID instead of array position
Associate each result with its source record using id. Do not rely on the response array using the same position as the request array.
Important rules
Keep the requests array non-empty
Submit at least one request object and no more than 30 objects in a single API call.
Assign one ID per input record
Every item needs a non-blank id, and duplicate IDs are not allowed within the same request.
Provide a useful identifier
Each item must provide at least one of name, websites, ticker, email, or executiveLinkedInHandle.
Stay within the supported range
limitResults must be from 1 through 20. The default is 10.
Use a supported contact grade
When supplied, minContactQualityScore must be A+, A, B, or C.
Omit fields you do not know
Avoid placeholder text and empty strings. Send accurate attributes and leave unavailable optional fields out of the request.
Top-level parameters
| Parameter | Required | Use it to | Accepted value |
|---|---|---|---|
requests |
Yes | Provide the company and contact records to match. | Array containing 1–30 objects |
limitResults |
No | Set the maximum number of matching candidates considered for each request. | 1–20; default 10 |
matchBranch |
No | Control whether company branch matching is enabled. | "true" or "false" |
minContactQualityScore |
No | Set the minimum acceptable contact quality grade. | A+, A, B, or C |
Common errors
| Status | Error | How to fix it |
|---|---|---|
400-164 |
Required matching evidence is missing. | Add name, websites, ticker, email, or executiveLinkedInHandle to every request item. |
400-165 |
The match request has an empty requests list. |
Include at least one request object. |
400-166 |
The request body is null or unreadable. | Send a valid JSON body with Content-Type: application/json. |
400-167 |
A request ID is missing, blank, or duplicated. | Give every request item a unique, non-blank id. |
400-168 |
The request contains more than 30 records. | Split the input into batches of no more than 30, or use the bulk match workflow. |
400-169 |
limitResults is outside the supported range. |
Set limitResults to a value from 1 through 20. |
400-123 |
The minimum contact quality score is invalid. | Use A+, A, B, or C. |
401 |
Authentication failed. | Generate a valid token and send it in the Authorization: Bearer YOUR_ACCESS_TOKEN header. |
Next steps
Try the synchronous endpoint, move larger datasets to the bulk match workflow, or retrieve complete records using the returned identifiers.
Try synchronous matching → · Bulk company and contact match → · Company details → · Contact details →