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

  • Updated

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

Request  Endpoint Description

GET

.../api/v3/ip.json

Returns response formatted in JSON.

GET

.../api/v3/ip.js

Returns the response as a javascript object. The data is returned against the variable, organization which can be modified by adding a var parameter to the request.

Parameters

Request  Value Required Description

auth

string

required

A valid Demandbase API key.
It is generally 32-48 characters in length and consists of alphanumeric characters + ‘_’.

Contact your CSM for assistance with your API token.

query 

string

only available
for server-side if
token is allowed
to by-pass
query
parameter

This is the IP Address to perform identification on.

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. 

var

string

optional

By default, JSON block is returned. However, if a var is provided the JSON is wrapped within the Javascript block. The response in standard JSON-P format.

Request Example

Important: Replace "YOUR_TOKEN_HERE" with your API token

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

HTTP Response Status Service Result Description

200

Detailed (IP Resolved)

All information about this company is provided from Demandbase and the customer’s database. See Response examples below.

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. 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 examples below.

404

Not found

If the IP cannot be found the API will return a 404 status. 

401

Unauthorized

Typically an invalid API token or an incorrect configuration.

429

Rate limited

This occurs when the API rate limits the token.

500

Internal Server Error

Service availability is provided at the API status page.

502-503

Load Balancing
Issues

Service availability is provided at the API status page.

504

Connection Timeout

Service availability is provided at the API status page.

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

Value Description

information_level = Basic

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 attributes matching the IP address from the Demandbase database. Attribute values may differ, depending on Demandbase and 3rd party information.

Account Connector values

Account Connector values specified for the matched company are returned in the `custom_fields` element of the response. 

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": "680 Folsom St Suite 400",

"city": "San Francisco",

"state": "CA",

"zip": "94107",

"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"

}

Important: Some of our data comes from third party data sources. When data is unavailable for a given field the response 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 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.
Important: 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. company_id
  8. audience
  9. audience_segment
  10. custom_field (remember this is an object of custom key-value pairs)
  11. information_level
Important: If you'd like to use registry attributes, consult your CSM and account team first.

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();

Was this article helpful?

0 out of 0 found this helpful