Reference: Demandbase IP-API v3 for Demandbase One (Updated Version)

The Demandbase IP-API returns firmographic data for a specific IP address or cookie.

Important: The information provided is for Demandbase IP-API v3. For information about the previous version (v2), see Reference: Demandbase IP-API for Demandbase One (Previous Version - v2).

Identification Methodology

Most identification happens by looking at the IP address, user agent string, cookie, and scanning done for validation of Advertising creatives. 

(CLIENT-SIDE ONLY) An identification is attempted based on the cookie passed with the request. This method is available if a customer has this feature enabled on their Demandbase account (Settings > Demandbase-Wide Settings > Account Connector). 

An identification is possible if:

• a visitor was previously cookied (this is only possible with a Demandbase cookie and tag), and 
• the cookie was mapped to a company. 

If no identification was obtained, the IP address is used to obtain company identification. In addition, Demandbase uses a “registry-based” Basic identification with internet registry data sources.

API Request

Parameters

Request Example

JSON Format

Server-side calls

api.demandbase.com/api/v3/ip.json?auth=YOUR_TOKEN_HERE

api.demandbase.com/api/v3/ip.json?auth=YOUR_TOKEN_HERE&query=4.16.87.226

Client-side calls made through Demandbase Tag

api.company-target.com/api/v3/ip.json?auth=YOUR_TOKEN_HERE

JAVASCRIPT Format

Server-side calls

api.demandbase.com/api/v3/ip.json?auth=YOUR_TOKEN_HERE

api.demandbase.com/api/v3/ip.json?auth=YOUR_TOKEN_HERE&query=4.16.87.226

Client-side calls made through Demandbase Tag

api.company-target.com/api/v3/ip.json?auth=YOUR_TOKEN_HERE

Response Conditions

Service Level Agreements

For information about your customer-specific Service Level Agreement, consult your CSM and account team. You can also review current metrics and stay up to date with changes on https://status.demandbase.com/.

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

{

"registry_dma_code": 807,

"registry_country_code3": null,

"company_id": 645072,

"company_name": "Demandbase, Inc.",

"marketing_alias": "Demandbase",

"account_ownership": "Private",

"stock_ticker": null,

"fye": null,

"industry": "Computer Software",

"sub_industry": "Marketing Automation Software",

"primary_naics": "513210",

"primary_sic": "7371",

"street_address": "6222 2nd St floor 24",

"city": "San Francisco",

"state": "CA",

"zip": "94105",

"country": "US",

"country_name": "United States",

"phone": "+1 415 683 2660",

"fax": "1-415-677-9668",

"web_site": "demandbase.com",

"parent": {

"company_id": null,

"marketing_alias": null,

"stock_ticker": null,

"industry": null,

"sub_industry": null,

"primary_naics": null,

"primary_sic": null,

"street_address": null,

"zip": null,

"country_name": null,

"web_site": null,

"employee_count": null,

"annual_sales": null,

"session_id": null

},

"parent_id": null,

"parent_name": null,

"ultimate_parent": {

"company_id": null,

"marketing_alias": null,

"stock_ticker": null,

"industry": null,

"sub_industry": null,

"primary_naics": null,

"primary_sic": null,

"street_address": null,

"zip": null,

"country_name": null,

"web_site": null,

"employee_count": null,

"annual_sales": null,

"session_id": null

},

"ultimate_parent_id": null,

"ultimate_parent_name": null,

"efx_id": "32705544",

"company_linkedin_profile": "https://www.linkedin.com/company/demandbase",

"company_status": "Operating",

"company_type": "Private",

"business_structure": "Global Parent",

"employee_count": 750,

"annual_sales": 235000000,

"revenue_range": "$100M - $250M",

"employee_range": "Mid-Market",

"fortune_1000": false,

"forbes_2000": false,

"registry_company_name": "LEVEL3",

"registry_city": "San Francisco",

"registry_state": "CA",

"region_name": "California",

"registry_zip_code": "94109",

"registry_area_code": null,

"registry_country": "United States",

"registry_country_code": "US",

"registry_latitude": 37.8,

"registry_longitude": -122.42,

"information_level": "Detailed",

"audience": "Mid-Market Business",

"audience_segment": "Software & Technology",

"access_type": "corporate",

"isp": false,

}

Sample Basic Response

(information_level = Basic)

{

"registry_company_name": "xxxxxxxx",

"registry_city": "Adelaide",

"registry_state": "SA",

"registry_zip_code": "xxxx",

"registry_area_code": null,

"registry_dma_code": null,

"registry_country": "xxxx",

"registry_country_code": "xx",

"registry_country_code3": null,

"registry_latitude": -xx.xx,

"registry_longitude": xx.xx,

"isp": false,

"information_level": "Basic",

"audience": "",

"audience_segment": "",

"ip": "1.0.0.0",

"region_name": "xxxx"

}

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 server side API token (separate from any other token)
2. You must pass in the IP address to the API and make a full HTTPS request.

Client-Side Requirements

1. These are standard REST calls to the Demandbase API
2. You must have a valid Demandbase account and client-side API token.
3. We recommend customers make API calls asynchronously.

Account Connector (Custom_Fields):

The custom_fields property of the JSON response is returned only when a customer has configured their Demandbase account to an integration through the Account Connector feature (Settings > Demandbase-Wide Settings > Account Connector), and that has an integration active.

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. 

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 reuse 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 IP-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 company_id 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. company_id
8. audience
9. audience_segment
10. custom_field (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/v3/ip.json?auth=YOUR_API_KEY" + "&referrer=" + referrer + "&page=" + page + "&title=" + title;

xmlhttp.open("GET", url, true);

xmlhttp.send();