---
updatedAt: 2026-07-30T12:11:10.000Z
agentTools:
projectIndex: https://developer.demandbase.com/llms.txt
---
# Search contacts
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.
# OpenAPI definition
````json
{
"openapi": "3.0.1",
"info": {
"version": "1.0",
"title": "B2B API",
"description": "The B2B API provides access to endpoints for searching, retrieving, and matching company and contact data.\n\nIt includes support for:\n- **Company records:** Firmographic details, news, technologies, and more.\n- **Contact records:** Current role, employment history, and professional details.\n- **Demandbase Person profiles:** Persistent identities tied to individuals across multiple roles or companies.\n- **Subscriptions:** Monitoring updates to companies and DB Person records.\n## Authentication\nAll requests to the B2B API must be authenticated using a valid API token. If authentication fails, the API will respond with a `401 Unauthorized` status code.\n### Obtaining an API Token\nFor instructions on generating API tokens, see the [Generate and Manage API Key Set](https://support.demandbase.com/hc/en-us/articles/38999526296603-Generate-and-Manage-API-Key-Set) article at the Demandbase Help Center.\n### Authorization Header\nInclude your API token in the `Authorization` header of each request using the Bearer token scheme. Also set the `Content-Type` header to `application/json` when sending JSON payloads.\n#### Example\n```\nAuthorization: Bearer YOUR_API_KEY_HERE\nContent-Type: application/json\n```\n\n> **Note:** Tokens should be treated as sensitive credentials. Do not expose them in public code repositories or client-side applications.",
"contact": {
"name": "Support",
"url": "https://www.demandbase.com/",
"email": "support@demandbase.com"
}
},
"servers": [
{
"url": "https://uapi.demandbase.com/data/b2b/v1",
"description": "Server URL in Production environment"
}
],
"paths": {
"/contacts": {
"post": {
"tags": [
"Sync API"
],
"summary": "Search contacts",
"description": "Use this endpoint to search for individuals at specific companies. \n\nYou 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.\n\nSorting and pagination are supported. You can sort results by fields such as `companyName`, and control the number of results returned using `page` and `perPage`.\n\nYou must include at least one parameter (excluding sorting and pagination) to perform a search.",
"operationId": "contactSearch_1",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactSearchRequestDTO"
}
},
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/ContactSearchRequestDTO"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation or No contacts found for query.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactSearchResponseDTO"
},
"examples": {
"SuccessResponse": {
"description": "SuccessResponse",
"value": {
"contactResults": [
{
"dbPersonDetails": {
"dbPersonId": 15568398,
"firstName": "Jamie",
"lastName": "Taylor",
"country": "United States",
"city": "Seattle"
},
"employmentDetails": {
"contactId": 17864319,
"companyId": 731691,
"companyName": "Example Corp",
"titles": [
"Senior Security Officer"
],
"jobLevels": [
{
"id": "3",
"name": "Vice President"
}
],
"jobFunctions": [
{
"id": "9",
"name": "Information Technology"
}
],
"active": true,
"hasPhone": true,
"hasEmail": true,
"contactQualityScore": "A"
}
},
{
"dbPersonDetails": {
"dbPersonId": 124458755,
"firstName": "Morgan",
"lastName": "Lee",
"country": "Canada",
"city": "Toronto"
},
"employmentDetails": {
"contactId": 171412410,
"companyId": 990700,
"companyName": "Sample Industries",
"titles": [
"Senior Director, Technology"
],
"jobLevels": [
{
"id": "2",
"name": "Senior Executive"
},
{
"id": "4",
"name": "Director"
}
],
"jobFunctions": [
{
"id": "9",
"name": "Information Technology"
}
],
"active": true,
"hasPhone": false,
"hasEmail": true,
"contactQualityScore": "C"
}
}
],
"totalCount": 233,
"pageNo": 1,
"pageSize": 10
}
},
"EmptyCompaniesResponse": {
"description": "EmptyCompaniesResponse",
"value": {
"contactResults": [],
"totalCount": 0,
"pageNo": 1,
"pageSize": 10
}
}
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/ContactSearchResponseDTO"
},
"examples": {
"SuccessResponseXml": {
"description": "SuccessResponseXml",
"value": {
"contactResults": [
{
"dbPersonDetails": {
"dbPersonId": 15568398,
"firstName": "Jamie",
"lastName": "Taylor",
"country": "United States",
"city": "Seattle"
},
"employmentDetails": {
"contactId": 17864319,
"companyId": 731691,
"companyName": "Example Corp",
"titles": [
"Senior Security Officer"
],
"jobLevels": [
{
"id": "3",
"name": "Vice President"
}
],
"jobFunctions": [
{
"id": "9",
"name": "Information Technology"
}
],
"active": true,
"hasPhone": true,
"hasEmail": true,
"contactQualityScore": "A"
}
}
],
"totalCount": 233,
"pageNo": 1,
"pageSize": 10
}
},
"EmptyCompaniesResponseXml": {
"description": "EmptyCompaniesResponseXml",
"value": {
"contactResults": [],
"totalCount": 0,
"pageNo": 1,
"pageSize": 10
}
}
}
}
}
},
"400": {
"description": "Bad Request because required query params are missing, perPage must be greater than 0 and less than equal to 50, or page number must be greater than or equal to 1.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"BadRequestResponse": {
"description": "BadRequestResponse",
"value": {
"errorCode": "400-107",
"errorMessage": "At least one parameter must be provided.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidSortByParam": {
"description": "InvalidSortByParam",
"value": {
"errorCode": "400-108",
"errorMessage": "Sorting is allowed only on active, title and companyName.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidSortOrder": {
"description": "InvalidSortOrder",
"value": {
"errorCode": "400-109",
"errorMessage": "Sorting order can be either asc or desc.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidCompanyCountryId": {
"description": "InvalidCompanyCountryId",
"value": {
"errorCode": "400-111",
"errorMessage": "Invalid companyCountry. Please enter valid country ID in companyCountry.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidContactCountryId": {
"description": "InvalidContactCountryId",
"value": {
"errorCode": "400-110",
"errorMessage": "Invalid contactCountry. Please enter valid country ID in contactCountry.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"ResultsPerPageErrorResponse": {
"description": "ResultsPerPageErrorResponse",
"value": {
"errorCode": "400-101",
"errorMessage": "perPage must be between 1 and 50.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"PageNumberErrorResponse": {
"description": "PageNumberErrorResponse",
"value": {
"errorCode": "400-100",
"errorMessage": "page number must be greater than or equal to 1.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidJobLevels": {
"description": "InvalidJobLevels",
"value": {
"errorCode": "400-124",
"errorMessage": "jobLevel must be an integer. ",
"diagnosticCode": "8ee03d66-a07b-43bd-9bd0-eee448ed7a98"
}
},
"InvalidMinContactQualityScore": {
"description": "InvalidMinContactQualityScore",
"value": {
"errorCode": "400-123",
"errorMessage": "minContactQualityScore must one of: [A+, A, B, C]",
"diagnosticCode": "467e469f-2146-4af8-ac0f-5fb487fbba02"
}
},
"InvalidFunction": {
"description": "InvalidFunction",
"value": {
"errorCode": "400-125",
"errorMessage": "jobFunction must be an integer. ",
"diagnosticCode": "3640f569-4d90-40cd-b0c6-2c72f671ab72"
}
},
"InvalidPhoneType": {
"description": "InvalidPhoneType",
"value": {
"errorCode": "400-137",
"errorMessage": "phoneType must be one of: [DIRECT, CORP, MOBILE, ANY, DIRECTORCORP]",
"diagnosticCode": "8ee03d66-a07b-43bd-9bd0-eee448ed7a98"
}
},
"InvalidEmployeeRange": {
"description": "InvalidEmployeeRange",
"value": {
"errorCode": "400-126",
"errorMessage": "minEmployees must be less than or equal to maxEmployees.",
"diagnosticCode": "ddda8332-696c-4e74-897b-f5cc5525ddbe"
}
},
"InvalidIndustries": {
"description": "InvalidIndustries",
"value": {
"errorCode": "400-114",
"errorMessage": "Industry Id must be an integer.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidMaxEmployees": {
"description": "InvalidMaxEmployees",
"value": {
"errorCode": "400-121",
"errorMessage": "maxEmployees must be greater than or equal to 0.",
"diagnosticCode": "88ea1636-3c9d-40ec-bdc4-e28d8ec1d069"
}
},
"InvalidMinEmployees": {
"description": "InvalidMinEmployees",
"value": {
"errorCode": "400-120",
"errorMessage": "minEmployees must be greater than or equal to 0.",
"diagnosticCode": "88ea1636-3c9d-40ec-bdc4-e28d8ec1d069"
}
},
"InvalidEmailValidationStatus": {
"description": "InvalidEmailValidationStatus",
"value": {
"errorCode": "400-138",
"errorMessage": "emailValidationStatus must be one of: [ValidEmail, ValidDomain]",
"diagnosticCode": "e32c6e5e-29cb-40c0-a37a-2c8e8213a477"
}
},
"InvalidCompanyId": {
"description": "InvalidCompanyId",
"value": {
"errorCode": "400-122",
"errorMessage": "Invalid companyId in companyIdsInclude. companyId must be an integer.",
"diagnosticCode": "ffa69cf0-b316-4a12-84d5-e4afb6bb23ee"
}
}
}
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"BadRequestResponseXml": {
"description": "BadRequestResponseXml",
"value": {
"errorCode": "400-107",
"errorMessage": "At least one parameter must be provided.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidSortByParam": {
"description": "InvalidSortByParam",
"value": {
"errorCode": "400-108",
"errorMessage": "Sorting is allowed only on active, title and companyName.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidSortOrder": {
"description": "InvalidSortOrder",
"value": {
"errorCode": "400-109",
"errorMessage": "Sorting order can be either asc or desc.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidCompanyCountryId": {
"description": "InvalidCompanyCountryId",
"value": {
"errorCode": "400-111",
"errorMessage": "Invalid companyCountry. Please enter valid country ID in companyCountry.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidContactCountryId": {
"description": "InvalidContactCountryId",
"value": {
"errorCode": "400-110",
"errorMessage": "Invalid contactCountry. Please enter valid country ID in contactCountry.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"ResultsPerPageErrorResponseXml": {
"description": "ResultsPerPageErrorResponseXml",
"value": {
"errorCode": "400-101",
"errorMessage": "perPage must be between 1 and 50.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"PageNumberErrorResponseXml": {
"description": "PageNumberErrorResponseXml",
"value": {
"errorCode": "400-100",
"errorMessage": "page number must be greater than or equal to 1.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidJobLevels": {
"description": "InvalidJobLevels",
"value": {
"errorCode": "400-124",
"errorMessage": "jobLevel must be an integer. ",
"diagnosticCode": "8ee03d66-a07b-43bd-9bd0-eee448ed7a98"
}
},
"InvalidMinContactQualityScore": {
"description": "InvalidMinContactQualityScore",
"value": {
"errorCode": "400-123",
"errorMessage": "minContactQualityScore must one of: [A+, A, B, C]",
"diagnosticCode": "467e469f-2146-4af8-ac0f-5fb487fbba02"
}
},
"InvalidFunction": {
"description": "InvalidFunction",
"value": {
"errorCode": "400-125",
"errorMessage": "jobFunction must be an integer. ",
"diagnosticCode": "3640f569-4d90-40cd-b0c6-2c72f671ab72"
}
},
"InvalidPhoneType": {
"description": "InvalidPhoneType",
"value": {
"errorCode": "400-137",
"errorMessage": "phoneType must be one of: [DIRECT, CORP, MOBILE, ANY, DIRECTORCORP]",
"diagnosticCode": "8ee03d66-a07b-43bd-9bd0-eee448ed7a98"
}
},
"InvalidEmployeeRange": {
"description": "InvalidEmployeeRange",
"value": {
"errorCode": "400-126",
"errorMessage": "minEmployees must be less than or equal to maxEmployees.",
"diagnosticCode": "ddda8332-696c-4e74-897b-f5cc5525ddbe"
}
},
"InvalidIndustries": {
"description": "InvalidIndustries",
"value": {
"errorCode": "400-114",
"errorMessage": "Industry Id must be an integer.",
"diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}
},
"InvalidMaxEmployees": {
"description": "InvalidMaxEmployees",
"value": {
"errorCode": "400-121",
"errorMessage": "maxEmployees must be greater than or equal to 0.",
"diagnosticCode": "88ea1636-3c9d-40ec-bdc4-e28d8ec1d069"
}
},
"InvalidMinEmployees": {
"description": "InvalidMinEmployees",
"value": {
"errorCode": "400-120",
"errorMessage": "minEmployees must be greater than or equal to 0.",
"diagnosticCode": "88ea1636-3c9d-40ec-bdc4-e28d8ec1d069"
}
},
"InvalidEmailValidationStatus": {
"description": "InvalidEmailValidationStatus",
"value": {
"errorCode": "400-138",
"errorMessage": "emailValidationStatus must be one of: [ValidEmail, ValidDomain]",
"diagnosticCode": "e32c6e5e-29cb-40c0-a37a-2c8e8213a477"
}
},
"InvalidCompanyId": {
"description": "InvalidCompanyId",
"value": {
"errorCode": "400-122",
"errorMessage": "Invalid companyId in companyIdsInclude. companyId must be an integer.",
"diagnosticCode": "ffa69cf0-b316-4a12-84d5-e4afb6bb23ee"
}
}
}
}
}
},
"401": {
"description": "Unauthorized because the user is not authenticated.",
"content": {
"application/json": {
"examples": {
"UnauthorizedResponse": {
"description": "UnauthorizedResponse",
"value": {
"status": "Authentication Failed - Unauthorized."
}
}
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
],
"servers": [
{
"url": "https://uapi.demandbase.com/data/b2b/v1",
"description": "Server URL in Production environment"
}
]
}
}
},
"tags": [
{
"name": "Sync API",
"description": "Synchronous company, contact, matching, news, and logo operations."
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"description": "[How To Generate Bearer Tokens](https://developer.demandbase.com/docs/auth-api)",
"scheme": "bearer"
}
},
"schemas": {
"ContactSearchRequestDTO": {
"type": "object",
"properties": {
"firstName": {
"type": "string",
"example": "John"
},
"lastName": {
"type": "string",
"example": "Doe"
},
"email": {
"type": "string",
"example": "john.doe@example.com"
},
"contactCity": {
"type": "string",
"example": "New York"
},
"contactState": {
"type": "string",
"example": "NY"
},
"contactCountry": {
"type": "string",
"description": "Country Id",
"example": "1"
},
"titles": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Manager",
"Director"
]
},
"companyName": {
"type": "string",
"example": "Demandbase"
},
"companyCity": {
"type": "string",
"example": "San Francisco"
},
"companyState": {
"type": "string",
"example": "CA"
},
"companyCountry": {
"type": "string",
"description": "Country Id",
"example": "1"
},
"companyWebsite": {
"type": "string",
"example": "demandbase.com"
},
"jobLevels": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"1",
"2"
]
},
"jobFunctions": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"1",
"2"
]
},
"active": {
"type": "string",
"default": "true"
},
"emailRequired": {
"type": "string",
"default": "false"
},
"phoneRequired": {
"type": "string",
"default": "false"
},
"phoneType": {
"type": "string",
"enum": [
"direct",
"corp",
"mobile",
"any"
],
"example": "mobile"
},
"emailValidationStatus": {
"type": "string",
"example": "ValidEmail"
},
"minContactQualityScore": {
"type": "string",
"example": "A"
},
"companyIdsToInclude": {
"type": "array",
"items": {
"type": "string"
},
"default": [
"726263"
],
"example": [
"726263",
"726256"
]
},
"contactIdsToExclude": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"726263",
"726256"
]
},
"primaryIndustryOnly": {
"type": "string",
"default": "false"
},
"sortBy": {
"type": "string",
"example": "companyName"
},
"sortOrder": {
"type": "string",
"enum": [
"asc",
"desc"
],
"example": "asc"
},
"maxEmployees": {
"type": "string",
"example": "100"
},
"minEmployees": {
"type": "string",
"example": "10"
},
"industries": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"1",
"2"
]
},
"subIndustries": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"1_1",
"2_1"
]
},
"page": {
"type": "string",
"default": "1"
},
"perPage": {
"type": "string",
"default": "10"
}
}
},
"ContactSearchResponseDTO": {
"type": "object",
"properties": {
"contactResults": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ContactResultsDTO"
},
"xml": {
"name": "contactResult"
}
},
"totalCount": {
"type": "integer",
"format": "int64"
},
"pageNo": {
"type": "integer",
"format": "int64"
},
"pageSize": {
"type": "integer",
"format": "int64"
}
},
"xml": {
"name": "contactResults"
}
},
"ContactResultsDTO": {
"type": "object",
"properties": {
"dbPersonDetails": {
"$ref": "#/components/schemas/PersonDTO"
},
"employmentDetails": {
"$ref": "#/components/schemas/EmploymentDTO"
}
}
},
"PersonDTO": {
"type": "object",
"properties": {
"dbPersonId": {
"type": "integer",
"format": "int64"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"country": {
"type": "string"
},
"city": {
"type": "string"
}
}
},
"EmploymentDTO": {
"type": "object",
"properties": {
"contactId": {
"type": "integer",
"format": "int64"
},
"companyId": {
"type": "integer",
"format": "int64"
},
"companyName": {
"type": "string"
},
"titles": {
"type": "array",
"items": {
"type": "string",
"xml": {
"name": "title"
}
},
"xml": {
"wrapped": true
}
},
"jobLevels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobLevelsV2"
},
"xml": {
"wrapped": true
}
},
"jobFunctions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobFunctionsV2"
},
"xml": {
"wrapped": true
}
},
"active": {
"type": "boolean"
},
"hasPhone": {
"type": "boolean"
},
"hasEmail": {
"type": "boolean"
},
"contactQualityScore": {
"type": "string"
}
}
},
"JobLevelsV2": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"JobFunctionsV2": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"errorCode": {
"type": "string"
},
"errorMessage": {
"type": "string"
},
"diagnosticCode": {
"type": "string"
}
},
"xml": {
"name": "error"
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
````