Company API (log in required)

Introduction

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

Parameters

Request Example

XML Format

api.company-target.com/api/v2/ip.xml?key=YOUR_KEY_HERE

JSON Format

api.company-target.com/api/v2/ip.json?key=YOUR_KEY_HERE

JAVASCRIPT Format

api.company-target.com/api/v2/ip.js?key=YOUR_KEY_HERE

Response Conditions

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 https://status.demandbase.com/.

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

Data Types and Definitions

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

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": "demandbase.com",
  "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": "69.181.105.169",
  "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": "1.0.0.0",
  "region_name": "Victoria"
}

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.

Caching

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.

Considerations 

• 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.

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

Code Sample

Javascript

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 = "https://api.company-target.com/api/v2/ip.json?key=YOUR_API_KEY" + "&referrer=" + referrer + "&page=" + page + "&title=" + title;
xmlhttp.open("GET", url, true);
xmlhttp.send();