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.
It includes support for:
- **Company records:** Firmographic details, news, technologies, and more.
- **Contact records:** Current role, employment history, and professional details.
- **Demandbase Person profiles:** Persistent identities tied to individuals across multiple roles or companies.
- **Subscriptions:** Monitoring updates to companies and DB Person records.
## Authentication
All 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.
### Obtaining an API Token
For 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.
### Authorization Header
Include 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.
#### Example
```
Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json
```
> **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
/companies:
post:
tags:
- Sync API
summary: Search companies
description: "Use this endpoint to search for companies based on a variety of attributes.\n\nYou can search companies\
\ by name, website, ticker, location (city, state, country, ZIP), industry classification (NAICS, SIC), or attributes\
\ like fiscal year end, business structure, and fortune ranking. \n\nAdditional filters let you set employee or revenue\
\ ranges, include only primary industry or SIC classifications, and apply diversity criteria (e.g., minority-owned\
\ or women-owned businesses). \n\nSorting and pagination are supported. You can sort results by fields such as `companyRevenue`\
\ and more, and control the number of results returned using `page` and `perPage`."
operationId: companySearch_1
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CompanySearchRequestDTO'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CompanySearchRequestDTO'
responses:
'200':
description: Successful operation or No companies found for query.
content:
application/json:
schema:
$ref: '#/components/schemas/CompanySearchResponseDTO'
examples:
SuccessResponse:
description: SuccessResponse
value:
companies:
- name: Northgate Logistics LLC
city: New Plymouth
state: ID
country: US
companyId: 406321
- name: Blue Ridge Transport Inc.
city: Walcott
state: IA
country: US
companyId: 1013683
- name: Horizon Freight Services
city: North Baltimore
state: OH
country: US
companyId: 8664201
- name: Summit Distribution Co.
city: Johnstown
state: CO
country: US
companyId: 9557195
- name: Granite Commerce Group
city: New Plymouth
state: ID
country: US
companyId: 284576424
- name: Lakeside Operations LLC
city: Oak Grove
state: MO
country: US
companyId: 8679793
- name: Pioneer Mobility Partners
city: Mineral Wells
state: WV
country: US
companyId: 6242601
- name: Meridian Media Group
city: New York
state: NY
country: US
companyId: 8108950
- name: Redwood Industrial Supply
city: Pine Bluffs
state: WY
country: US
companyId: 5914035
- name: Willow Creek Services
city: Calhoun City
state: MS
country: US
companyId: 6632012
totalCount: 165
pageNo: 1
pageSize: 10
EmptyCompaniesResponse:
description: EmptyCompaniesResponse
value:
companies: []
totalCount: 0
pageNo: 1
pageSize: 10
application/xml:
schema:
$ref: '#/components/schemas/CompanySearchResponseDTO'
examples:
SuccessResponseXml:
description: SuccessResponseXml
value:
companies:
- name: Northgate Logistics LLC
city: New Plymouth
state: ID
country: US
companyId: 406321
- name: Blue Ridge Transport Inc.
city: Walcott
state: IA
country: US
companyId: 1013683
totalCount: 165
pageNo: 1
pageSize: 10
EmptyCompaniesResponseXml:
description: EmptyCompaniesResponseXml
value:
companies: []
totalCount: 0
pageNo: 1
pageSize: 10
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
BadRequestResponse:
description: BadRequestResponse
value:
errorCode: 400-102
errorMessage: At least one parameter must be provided for company search.
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
InvalidSortByParam:
description: InvalidSortByParam
value:
errorCode: 400-135
errorMessage: Sorting is allowed only on employeeCount, businessType, companyRevenue and location
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-214
errorMessage: Invalid country. Please enter valid country ID in country.
diagnosticCode: 2ec12de8-1000-4620-8757-6091a1cffab7
InvalidNewsCategories:
description: InvalidNewsCategories
value:
errorCode: 400-112
errorMessage: 'Invalid newsCategories. Valid values are: leadership Changes, new Offerings, acquisitions,
partnerships, expanding operations, cost cutting, outperforming, underperforming, company presentation,
litigation, compliance, research and development, data security, funding developments, bankruptcy and
restructuring, real estate: deals, real estate: construction, corporate challenges'
diagnosticCode: ccb84f25-236e-4bcf-be01-88b7dd673fb4
InvalidNewsDuration:
description: InvalidNewsDuration
value:
errorCode: 400-113
errorMessage: Invalid newsDuration. Valid values are between 1 and 30
diagnosticCode: ccb84f25-236e-4bcf-be01-88b7dd673fb4
InvalidIndustry:
description: InvalidIndustry
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
InvalidMaxRevenue:
description: InvalidMaxRevenue
value:
errorCode: 400-119
errorMessage: maxRevenue must be greater than or equal to 0.
diagnosticCode: 88ea1636-3c9d-40ec-bdc4-e28d8ec1d069
InvalidMinRevenue:
description: InvalidMinRevenue
value:
errorCode: 400-118
errorMessage: minRevenue must be greater than or equal to 0.
diagnosticCode: 88ea1636-3c9d-40ec-bdc4-e28d8ec1d069
InvalidBusinessStructure:
description: InvalidBusinessStructure
value:
errorCode: 400-128
errorMessage: 'Invalid businessStructure. Valid values are: uncategorized, globalParent, subsidiary, group,
branch, independent'
diagnosticCode: cebdea29-25ac-40e5-af41-0626e34e6f46
InvalidBusinessType:
description: InvalidBusinessType
value:
errorCode: 400-129
errorMessage: 'Invalid businessType. Valid values are: public, private, school, government, organization'
diagnosticCode: 2b7cd799-e532-46a4-bc4e-e967b0a40f4b
InvalidCompanyStatus:
description: InvalidCompanyStatus
value:
errorCode: 400-130
errorMessage: 'Invalid companyStatus. Valid values are: unassigned, operating, non-operating, acquired,
liquidating, outOfBusiness'
diagnosticCode: bb841d37-ed8f-4a82-a5c5-fd11ea6d8e3d
InvalidFiscalYearEnd:
description: InvalidFiscalYearEnd
value:
errorCode: 400-131
errorMessage: Invalid fiscalYearEnd. fiscalYearEnd should be a valid month name.
diagnosticCode: 67521433-a92b-49ee-9d21-21d4007f8486
InvalidFortuneRanking:
description: InvalidFortuneRanking
value:
errorCode: 400-132
errorMessage: 'Invalid fortuneRanking. Valid values are: fortune500, fortune1000'
diagnosticCode: 1921c127-a8e6-4685-aaa0-1f6bce967a18
InvalidEmployeeRange:
description: InvalidEmployeeRange
value:
errorCode: 400-126
errorMessage: minEmployees must be less than or equal to maxEmployees.
diagnosticCode: ddda8332-696c-4e74-897b-f5cc5525ddbe
InvalidRevenueRange:
description: InvalidRevenueRange
value:
errorCode: 400-127
errorMessage: minRevenue must be less than or equal to minRevenue.
diagnosticCode: cbc2bbd0-a801-41c1-a546-be6ea0e75797
InvalidRegions:
description: InvalidRegions
value:
errorCode: 400-133
errorMessage: 'Invalid region. Valid values are: Africa, Asia, Europe, MiddleEast, NorthAmerica, Oceania,
SouthAmerica'
diagnosticCode: 88d76e2d-6f09-4018-97fe-b41c64f5ac67
InvalidCompanyType:
description: InvalidCompanyType
value:
errorCode: 400-134
errorMessage: 'Invalid companyType. Valid values are: unknown, public, private, government, organization'
diagnosticCode: ed1cfeb5-a7bf-4621-a4f3-51b1e8f106ae
InvalidGender:
description: InvalidGender
value:
errorCode: 400-117
errorMessage: Invalid gender. Valid values are male and female
diagnosticCode: fa7db512-d0ef-4c9d-aa8b-6e6bc21a61bc
InvalidEthnicity:
description: InvalidEthnicity
value:
errorCode: 400-136
errorMessage: Invalid Ethnicity Ids. Ethnicity Ids should be between 1 and 7
diagnosticCode: 126df328-b3d1-4d62-9464-e435aa706805
application/xml:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
BadRequestResponseXml:
description: BadRequestResponseXml
value:
errorCode: 400-102
errorMessage: At least one parameter must be provided for company search.
diagnosticCode: ccb84f25-236e-4bcf-be01-88b7dd673fb4
ResultsPerPageErrorResponseXml:
description: ResultsPerPageErrorResponseXml
va
# --- truncated at 32 KB (305 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/demandbase/refs/heads/main/openapi/demandbase-b2b-openapi.yml