Demandbase IP-API v3 for Demandbase One (Current Version)

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

Identification Methodology

Demandbase identifies companies using:

• IP address
• User agent string
• Cookies (if available)
• Ad creative validation scans

Client-side identification (optional):
Important: This method is available if you enable the feature in Settings > Demandbase-Wide Settings > Account Connector).

• Uses a Demandbase cookie (if available)
• Requires prior cookie-to-company mapping

If no match is found, Demandbase falls back to IP-based and registry-based identification.

Service Level Agreements

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

Implementation Considerations

Defensive Coding

API response data attributes vary. Although Demandbase aims to notify customers of impactful changes, do not code against a fixed set or count of properties or assume all properties are always present. Properties may be added or removed at any time, implementations should handle responses defensively.

Server-Side Requirements

• Valid Demandbase account and server-side API token.
• Must pass IP address.
• Use HTTPS.

Client-Side Requirements

• Valid API token.
• Standard REST calls.
• Use asynchronous requests.

Account Connector (Custom_Fields)

Custom fields are returned in custom_fields when Account Connector integrations are configured and active in Settings > Demandbase-Wide Settings > Account Connector.

Caching

Demandbase is optimized for performance; do not cache API responses. Caching prevents API calls from reaching Demandbase, leading to inaccurate analytics in the platform and related services.

Demandbase does not support implementations that rely on caching when data discrepancies occur.

User Experience

If you need to reuse data (for example, for page personalization), continue calling the API on every page to ensure accurate reporting. You may store the data separately for reuse, but this should not replace API calls.

Syncing

If you store data, you are responsible for maintaining visitor identity and keeping data up to date. Monitor:

• information_level changes (for example, from Basic to Detailed)
• company_id changes

Update stored data accordingly when these values change.

Important: Demandbase may add, remove, or modify attributes at any time. Notifications are provided for significant changes, and you may need to update your implementation accordingly.

Recommended Attributes

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 (object of custom key-value pairs)
11. information_level

API Request

Parameters

Request Example

JSON Format

Server-side calls

api.demandbase.com/api/v3/ip.json?auth={YOUR_TOKEN_HERE}&query={IP_ADDRESS}&page={URL}&page_title={PAGE_TITLE}&referrer={REFERRER_URL}

Client-side calls made through Demandbase Tag

api.company-target.com/api/v3/ip.json?auth={YOUR_TOKEN_HERE}&page={URL}&page_title={PAGE_TITLE}&referrer={REFERRER_URL}

JAVASCRIPT Format

Server-side calls

api.demandbase.com/api/v3/ip.js?auth={YOUR_TOKEN_HERE}&query={IP_ADDRESS}&page={URL}&page_title={PAGE_TITLE}&referrer={REFERRER_URL}

Client-side calls made through Demandbase Tag

api.company-target.com/api/v3/ip.js?auth={YOUR_TOKEN_HERE}&page={URL}&page_title={PAGE_TITLE}&referrer={REFERRER_URL}

Response Conditions

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.

Important: Fields may return null when data is unavailable.

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"

}

Code Sample

Javascript

async function getDemandbaseData() {
    const apiKey = 'YOUR_API_KEY';
    const params = new URLSearchParams({
        auth: apiKey,
        referrer: document.referrer,
        page: window.location.href,
        title: document.title
    });
    const url = `https://api.company-target.com/api/v3/ip.json?${params.toString()}`;
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 5000); // 5 second timeout
    try {
        const response = await fetch(url, { signal: controller.signal });
        clearTimeout(timeout);
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        const data = await response.json();
        console.log("Demandbase Data:", data);
        // Utilize the data with your own logic here
    } catch (error) {
        console.error("Could not fetch Demandbase data:", error);
    }
}
getDemandbaseData();