The Demandbase IP-API returns firmographic data for a specific IP address or cookie depending on configuration with Demandbase per licensing.
Important: The information provided is for Demandbase IP-API v2. For information about the updated version (v3), see Reference: Demandbase IP-API v3 for Demandbase One (Updated Version).
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, |
Parameters
Request | Value | Required | Description |
---|---|---|---|
auth |
string |
required |
A valid Demandbase API key. |
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
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 |
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, consult your account team. 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 third-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"
}
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
- You must have a valid Demandbase account and a Demandbase server side API token (separate from any other token)
- You must pass in the IP address to the API and make a full HTTPS request.
Client-Side Requirements
- These are standard REST calls to the Demandbase API
- You must have a valid Demandbase account and client-side API token.
- 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.
Recommended Attributes
By default, there is a recommended set of attributes to collect when implementing via API.
- marketing_alias
- company_name
- industry
- sub_industry
- revenue_range
- employee_range
- demandbase_sid
- audience
- audience_segment
- custom_field (remember this is an object of custom key-value pairs)
- 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?auth=YOUR_API_KEY" + "&referrer=" + referrer + "&page=" + page + "&title=" + title;
xmlhttp.open("GET", url, true);
xmlhttp.send();