FAQ

Use the Contact Search endpoint:

POST /contacts

Common fields you can include in the request body:

• firstName, lastName
• email
• contactCity, contactState, contactCountry
• titles, jobLevels, jobFunctions
• companyName, companyCity, companyState, companyCountry
• phoneRequired, emailRequired
• Pagination (page, perPage)

By default, page=1 and perPage=10. You can retrieve up to 50 results per page.

Use the Company Search endpoint:

POST /companies

In the request body, you can specify:

• name, website, ticker
• city, state, country, regions
• businessTypes, companyType, companyStatus
• industries, subIndustries
• minEmployees, maxEmployees
• minRevenue, maxRevenue
• fiscalYearEnd, fortuneRanking
• naics, sicCodes
• sortBy, sortOrder
• Pagination (page, perPage)

As with contact searches, perPage has a maximum of 50.

Contact Fetch (GET /contact/{contactId}):
Returns details about a contact record, including the person’s details plus employment-specific information such as start date, salary, description, etc.

In both cases, the ID in the path must be an integer. If invalid, you’ll receive a 400 error indicating “PersonId must be an integer” or “ContactId must be an integer.”

Use:

GET /company/{companyId}

By default, this returns basic company details (name, type, address, revenue, employee count, etc.). You can retrieve extra data using query parameters:

• fields=familytree
• fields=competitors
• fields=logos
• fields=installedtech

You can pass any combination of these comma-separated to see additional details in the response. (fields=familyTree,logos,competitors)

• /news: Fetches news articles for a specific set of categories. You must supply a newsCategories query parameter (e.g., LEADERSHIP_CHANGES or ACQUISITIONS).
• /newsFeed: Fetches news articles for a company without needing a category parameter, returning a broader feed.

Both support pagination with page and perPage.

The API limits perPage to a maximum of 50. If you provide a larger number, you’ll get a 400 error indicating:

errorCode: 400-101
errorMessage: perPage must be between 1 and 50.

Use:

GET /company/{companyId}/logos/{logoSize}

• logoSize can be 100, 200, or 400.
• A 400-108 error is returned if you supply an invalid size (anything other than 100, 200, or 400).
• A 400-109 error means no logo is available for the specified company.

Every endpoint can return errors in JSON or XML. The response typically includes:

• errorCode
• errorMessage
• diagnosticCode

For example, a 400 error might look like this in JSON:

{
  "errorCode": "400-103",
  "errorMessage": "companyId must be an integer.",
  "diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}

Use errorCode and errorMessage to diagnose what went wrong (e.g., invalid parameters, missing required fields, etc.). The diagnosticCode is for internal reference if you need to contact Support.

Yes. The search endpoints require at least one filter parameter to avoid returning huge result sets:

• Contact Search: If you submit an empty request body, you may get an error (e.g., 400-107, “At least one parameter must be provided.”)
• Company Search: If you submit an empty request body, you may get an error (e.g., 400-102, “At least one parameter must be provided for company search.”)

When searching for contacts or companies, you can include sortBy and sortOrder in your request:

• Contact Search

  • Valid sortBy: active, title, companyName.
  • Valid sortOrder: asc or desc.

• Company Search

  • Valid sortBy: employeeCount, businessType, companyRevenue, or location.
  • Valid sortOrder: asc or desc.

If you use an invalid sort field or order, you’ll get an error such as:

errorCode: 400-108
errorMessage: Sorting is allowed only on active, title and companyName.

or

errorCode: 400-135
errorMessage: Sorting is allowed only on employeeCount, businessType, companyRevenue and location

You can use:

GET /company/{companyId}?fields=installedtech

The response under the techUsed field provides a list of technology categories, subcategories, and specific product names in use by that company.

If you have questions, need additional guidance, or believe you’ve encountered a bug:

• Email: [email protected]
• Website: https://www.demandbase.com/

Be prepared to provide your diagnostic codes (from the error responses) and example requests/responses if applicable.

We hope this FAQ helps you get started! For more details, please see the rest of this API documentation or reach out to Demandbase Support.