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

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

See Firmographic Attributes Overview for Demandbase IP-API v3 (Current Version).

How Demandbase Identifies Companies

Demandbase uses the following methods to identify companies:

• IP address
• User agent string
• Cookies, when available
• Ad creative validation scans

Client-Side Identification with the Demandbase Cookie

Client-side identification is available when the feature is enabled in Settings > Demandbase-Wide Settings > Account Connector.

Client-side identification:

• Uses a Demandbase cookie, when available
• Requires a prior cookie-to-company mapping

If Demandbase cannot find a match, it falls back to IP-based and registry-based identification.

Implementation Requirements for Demandbase IP-API

Demandbase IP-API implementations must account for variable response attributes, valid authentication, and the requirements for the selected request method.

Handle Demandbase API Responses Defensively

Demandbase API response attributes can vary. Do not code against a fixed set or number of properties, or assume that every property is always present. Demandbase may add or remove properties at any time.

Although Demandbase aims to notify customers about impactful changes, implementations should handle response data defensively.

Server-Side Demandbase IP-API Requirements

Server-side implementations require:

• A valid Demandbase account and server-side API token
• An IP address passed with the request
• HTTPS

Client-Side Demandbase IP-API Requirements

Client-side implementations require:

• A valid API token
• Standard REST calls
• Asynchronous requests

Return Account Connector Custom Fields

The API returns custom fields in custom_fields when Account Connector integrations are configured and active in Settings > Demandbase-Wide Settings > Account Connector.

Prevent Caching from Affecting Demandbase Analytics

Do not cache Demandbase API responses. Caching prevents requests from reaching Demandbase, which can result in inaccurate analytics in the Demandbase platform and related services.

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

Reuse Demandbase Data for Personalization

If you need to reuse API data, such as for page personalization, continue calling the API on every page to ensure accurate reporting. You may store the data separately for reuse, but stored data must not replace API calls.

Keep Stored Demandbase Data 

If you store API data, you are responsible for maintaining visitor identity and keeping the data current. Monitor the following values:

• 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 Demandbase IP-API Attributes

Demandbase recommends the following 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

Demandbase IP-API Request Endpoints

Demandbase IP-API supports JSON and JavaScript response formats.

Demandbase IP-API Request Parameters

Demandbase IP-API Request Examples

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}

Demandbase IP-API Response Conditions

Demandbase IP-API Response Values

Demandbase IP-API Data Types and Definitions

See Company Profile Attributes for complete definitions of the available attributes and data types.

Important: Fields may return null when data is unavailable.

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

}

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

}

Demandbase IP-API JavaScript Code Sample

The following example makes an asynchronous client-side request to the Demandbase IP-API.

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