Company API (log in required)

  • Updated


The Demandbase Company API returns firmographic data for a specific IP address or cookie depending on configuration with Demandbase per licensing.

Identification Methodology

  1. (SERVER-SIDE and CLIENT-SIDE) The first method of identification is via IP Address
  2. (CLIENT-SIDE ONLY) The second method is attempted if the IP Address does not resolve to a Company Identification and happens automatically.
    1. This method is attempted if a customer has this feature enabled on their Demandbase account:
      1. Visitor has been previously cookied with Demandbase and
      2. Cookie was mapped to a company

API Request

Request Endpoint Description
GET Returns the response formatted as XML.
GET Returns response in formatted as JSON.
GET Returns the response as a javascript object. Used for synchronous response handling, the data is returned against the variable, organization which can be modified by adding a var parameter to the request.


Parameter Value Required Description
key string required

A valid Demandbase or Developer key.

  • alpha-numeric
  • 32 characters
Contact your CSM for assistance with your key.
query  string only required for server-side This is defined as the client IP address. Typically, when you google "what is my ip" that IP is inferred in the API request for client-side and for server-side you will need to pass it in the query parameter.
page string

required client-side

Indicates the URL of the current page for Dashboard metrics. Recommended value document.location.href
page_title string

required client-side

Indicates the title of the current page for Dashboard metrics. Recommended value document.title
referrer string required client-side Indicates the URL of the previous page for Dashboard metrics. Recommended value document.referrer
callback string optional The name of the function that will be called with the result of the API. Effectively required for client-side requests.
var string optional When using the JavaScript format (.js format). When synchronously assigning a variable, this parameter overrides the default variable name (organization) to which the API response is assigned. See JSON Response example for more details.

Request Example


Replace "YOUR_KEY_HERE" with your API key.

XML Format

JSON Format


Response Conditions

HTTP Response Status Service Result Description
200 Detailed (IP Resolved) All information about this company is available from Demandbase’s proprietary database. See Response Values for expected values returned with a Resolved IP.
200 Basic (Unresolved IP) This means the IP address does not correlate to a company in the Demandbase database, but it is in one of the worldwide Internet Registries such as ARIN ( and RIPE (, etc. Typically the companies that are unresolved are less than 1 million dollars in annual revenue, ISPs, or small home offices. The information from the registries is limited but provides baseline information about a company related to an IP. The returned attributes for an unresolved IP will be prefixed with the word registry as represented in the following example. The registry information is also returned with a resolved IP. (
404 Not found If the IP cannot be found in either Demandbase’s database or the ARIN Registry the API will return a 404 status. While this is a rare scenario, your solution should still ensure a seamless user experience if the API call fails. (
401 Unauthorized Typically an invalid API Key or an incorrect configuration.
500 Internal Server Error Sometimes this is very temporary while our infrastructure scales up during business hours. Please give it a few minutes, if anything is seriously wrong we will communicate it via our status page.

Service Level Agreements

For information about your customer-specific Service Level Agreement please consult with your Customer Success Manager and account representative. You may also review current metrics and stay up to date with changes on

Response Formats

Both XML and JSON are available to suit a variety of programming needs and parsing mechanisms. Most programming languages include an XML parser, making it easy to work with XML data. If you are working with dynamic webpage manipulations using JavaScript, JSON is a better choice as JavaScript can parse JSON.

Response Values

Value Type Description
information_level = Basic Typically this response is not useful to take Marketing actions and should be considered a Non-Company visitor. This response is if the IP address does not match to a company and the "basic" information of the IP is returned such as ISP registration city, state, country etc (reverse DNS lookups).
information_level = Detailed These will be all entitled attributes matching the IP address, from the Demandbase database. Attribute values may differ, depending on if a mapping was provided to Demandbase.
Account Watch Values Account Watch values specified for the matched company will be returned as part of the dataset. If you have questions about your watch values, contact your CSM.


Attribute entitlement is a per-key match that indicates which attributes to return to that key. If you are not seeing expected attributes in a detailed API response, raise a request to your Demandbase support representative.

Data Types and Definitions

See Company Profile Attributes for a complete definition of the available attributes in the data set and data types.

Note: Registry Attributes have been depricated.

Sample Detailed (IP Resolved) Response

(information_level = Detailed)

"registry_company_name": "Level 3 Communications",
  "registry_city": "San Francisco",
  "registry_state": "CA",
  "registry_zip_code": "94108",
  "registry_dma_code": 807,
  "registry_country": "United States",
  "registry_country_code": "US",
  "registry_latitude": 37.79,
  "registry_longitude": -122.40,
  "company_name": "Demandbase Inc",
  "demandbase_sid": 3415304,
  "marketing_alias": "Demandbase",
  "industry": "Software & Technology",
  "sub_industry": "Software Applications",
  "employee_count": 200,
  "isp": false,
  "primary_sic": "7372",
  "primary_naics": null,
  "street_address": "680 Folsom St Suite 400",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94107",
  "country": "US",
  "country_name": "United States",
  "phone": "415-683-2660",
  "stock_ticker": null,
  "web_site": "",
  "annual_sales": 40000000,
  "revenue_range": "$25M - $50M",
  "employee_range": "Mid-Market",
  "b2b": true,
  "b2c": false,
  "traffic": "Medium",
  "latitude": 37.7894,
  "longitude": -122.394,
  "fortune_1000": false,
  "forbes_2000": false,
  "information_level": "Detailed",
  "audience": "SMB",
  "audience_segment": "Software & Technology",
  "watch_list": {
    "Group_Id": "362",
    "Is_Primary": "1",
    "account_id": "001AL",
    "ao": "Brian",
    "mdr": "Leah",
    "asr": "Brian",
    "csm": "Anthony",
    "account_type": "Customer",
    "partner_owner": null,
    "demandbase_qualification_score": null,
    "ae_top_30": null
  "access_type": "remote",
  "ip": "",
  "region_name": "California"


Sample Basic Response

(information_level = Basic)

"registry_company_name": "Level 3 Communications",
  "registry_city": "San Francisco",
  "registry_state": "CA",
  "registry_zip_code": "94108",
  "registry_dma_code": 807,
  "registry_country": "United States",
  "registry_country_code": "US",
  "registry_latitude": 37.79,
  "registry_longitude": -122.40,
  "isp": false,
  "information_level": "Basic",
  "audience": "SOHO",
  "audience_segment": "",
  "access_type": "unidentified",
  "ip": "",
  "region_name": "Victoria"

Note: As a result of an update to one of our 3rd party data sources, we are no longer returning data for two fields previously available in the API response: Registry_country_code3 and Registry_area_code. These fields will continue to be included in the API response from Demandbase, but they will return a “null” value.

Implementation Considerations

Defensive Coding:

API response data attributes will vary. While we will do our best to inform our customers of changes that we believe will impact them, do not code against an exact count of properties in the response or expect all properties at all time, we expect to remove or introduce new properties and your code should handle all scenarios defensively.

Server-side Requirements

  1. You must have a valid Demandbase account and a Demandbase key (separate from any other key)
  2. You must pass in the IP address to the API and make a full HTTP/HTTPS request.
  3. Your implementation must be certified before deploying. Please contact your Customer Success Manager and Implementation team for more information.

Client-side Requirements

  1. These are standard REST calls to the Demandbase API
  2. You must have a valid Demandbase account and a Demandbase key (separate from any other key)
  3. Given modern best practices for deploying API's client-side, we recommend customers implement Demandbase asynchronously. Otherwise, deploying synchronously may result in your site having downtime during a rare API service outage for example.
  4. Your implementation must be certified before deploying

Account Watch (watch_list):

The watch_list property of the JSON response is returned only when a customer has configured their Demandbase account to include these special Audiences(lists). See Account Watch Overview.

For using Account Watch in development considerations, see Using Account Watch Attributes.


Demandbase is already optimized for performance, customers should NOT cache the response. By introducing additional caching, Demandbase will not receive an API request which will result in inconsistent analytics in Demandbase Platform and services.

Demandbase does not recommend caching and is not able to support use cases where caching is used and there are data discrepancies. Each unique implementation can cache in a variety of ways and have a vast amount of implications in terms of architecture used and caching mechanisms implemented. However, we understand there are use cases where caching is preferable given the consequences.


  • User Experience: If the goal is to use the data in some form or fashion without having to retrieve it every time to enhance end user experience - for example using it to personalize a page - then you still call the API on every page (for Demandbase to work properly and report accurately on the API calls) but you can still cache the data for re-use separately.
  • Syncing: Keep in mind doing the above means you, the customer/partner, have to maintain the identity of your website visitors. If Demandbase data changes or the identity of the visitor changes (as indicated by our Company API) you must maintain the changes as they come in. You can do this by observing the information_level attribute for changes from "Basic" to "Detailed" (See above Response Conditions) and the demandbase_sid for changes to the company identifier.
Note: Demandbase reserves the right to change any attribute at any time and these indicators are current as of the date of this document. Any changes to these attributes, you will be notified and may be required to change your implementation.

Recommended Attributes 

By default, there is a recommended set of attributes to collect when implementing via API.

  1. marketing_alias
  2. company_name
  3. industry
  4. sub_industry
  5. revenue_range
  6. employee_range
  7. demandbase_sid
  8. audience
  9. audience_segment
  10. watch_list (remember this is an object of custom key-value pairs)
  11. information_level


If you'd like to use registry attributes please consult with your Customer Success Manager before doing so. Demandbase reserves the right to change any part of this API at any time and this information is current as of the date of this document. If there are any significant changes to this API, you will be notified and may be required to change your implementation.

Code Sample


var xmlhttp;
if (window.XMLHttpRequest) { // IE7+, Firefox, Chrome, Opera, Safari
	xmlhttp = new XMLHttpRequest();
	xmlhttp.withCredentials = true;
} else { //IE6, IE5
	xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");
xmlhttp.onreadystatechange = function() {
	if (xmlhttp.readyState == 4 && xmlhttp.status == 200) {
		//xmlhttp.responseText will contain the text of our JSON response with company data.
var referrer = encodeURIComponent(document.referrer);
var page = encodeURIComponent(document.URL);
var title = encodeURIComponent(document.title);
var url = "" + "&referrer=" + referrer + "&page=" + page + "&title=" + title;"GET", url, true);

Was this article helpful?

7 out of 7 found this helpful