Reference: Demandbase IP-API for Demandbase One

  • Updated

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

IDENTIFICATION METHODOLOGY

First, most bot detection happens by looking at the IP address, user agent string, cookie, and scanning done for validation of Ad 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: →

Visitor has been previously cookied with Demandbase and →

Cookie was mapped to a company →

If no identification has been 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.company-target.com/api/v2/ip.json

Returns response formatted in JSON.

GET

api.company-target.com/api/v2/ip.xml

Returns the response formatted in XML.

GET

api.company-target.com/api/v2/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

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

NOTE: Replace "YOUR_TOKEN_HERE" with your API token

XML Format

api.company-target.com/api/v2/ip.xml?auth=YOUR_TOKEN_HERE

JSON Format

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

JAVASCRIPT Format

api.company-target.com/api/v2/ip.js?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.

500

Internal Server Error

Service availability is provided at the API 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 https://status.demandbase.com/.

RESPONSE FORMATS

Both XML and JSON are available to suit a variety of programming needs and parsing mechanisms.

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 will be 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

{

  "hq": {

"company_name": "Demandbase Inc",

"demandbase_sid": 3415304,

"marketing_alias": "Demandbase",

"employee_count": 200,

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

"b2b": true,

"b2c": false,

"traffic": "Medium",

"latitude": 37.79,

"longitude": -122.39,

"fortune_1000": false,

"forbes_2000": false,

"hq_sid": 3415304,

"domestichq_sid": 3415304,

"worldhq_sid": 3415304,

"session_id": null

  },

  "domestichq": {

"company_name": "Demandbase Inc",

"demandbase_sid": 3415304,

"marketing_alias": "Demandbase",

"employee_count": 200,

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

"b2b": true,

"b2c": false,

"traffic": "Medium",

"latitude": 37.79,

"longitude": -122.39,

"fortune_1000": false,

"forbes_2000": false,

"hq_sid": 3415304,

"domestichq_sid": 3415304,

"worldhq_sid": 3415304,

"session_id": null

  },

  "worldhq": {

"company_name": "Demandbase Inc",

"demandbase_sid": 3415304,

"marketing_alias": "Demandbase",

"employee_count": 200,

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

"b2b": true,

"b2c": false,

"traffic": "Medium",

"latitude": 37.79,

"longitude": -122.39,

"fortune_1000": false,

"forbes_2000": false,

"hq_sid": 3415304,

"domestichq_sid": 3415304,

"worldhq_sid": 3415304,

"session_id": null

  },

  "registry_company_name": "xxxxxxxx",

  "registry_city": "Ashburn",

  "registry_state": "VA",

  "region_name": "Virginia",

  "registry_zip_code": "xxxx",

  "registry_area_code": null,

  "registry_dma_code": xxx,

  "registry_country": "United States",

  "registry_country_code": "US",

  "registry_country_code3": null,

  "registry_latitude": xx.xx,

  "registry_longitude": -xx.xx

  "company_name": "Demandbase Inc",

  "demandbase_sid": 3415304,

  "marketing_alias": "Demandbase",

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

  "b2b": true,

  "b2c": false,

  "traffic": "Medium",

  "latitude": 37.79,

  "longitude": -122.39,

  "fortune_1000": false,

  "forbes_2000": false,

  "hq_sid": 3415304,

  "domestichq_sid": 3415304,

  "worldhq_sid": 3415304,

  "information_level": "Detailed",

  "audience": "SMB",

  "audience_segment": "Software & Technology",

  "access_type": "corporate",

  "custom_fields": {

"account_marketing_account_type__c": "Customer",

"account_sdr_owner__c": "John Doe",

"beta_Customer__c": false,

"billingCity": "Seattle",

"billingCountry": "United States",

"data_Quality_Score__c": 75,

"domain___e": "example.com",

"marketing_automation": "Eloquent Solutions",

"type": "Customer"

  },

  "experiences": [

{ "experience_id": 5, "priority": 1, "url": "https://mysite.com/contact"

},

{ "experience_id": 27, "priority": 2, "url": "https://example.com/about-us"

}

  ]

}

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"

}

NOTE: Some of our data comes from 3rd 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 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 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 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. custom_field (remember this is an object of custom key-value pairs)
  11. information_level
NOTE: If you'd like to use registry attributes please consult with your Customer Success Manager before doing so.

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?auth=YOUR_API_KEY" + "&referrer=" + referrer + "&page=" + page + "&title=" + title;

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

xmlhttp.send();

Was this article helpful?

2 out of 2 found this helpful