Demandbase IP-API v3 Overview

The Demandbase IP-API identifies companies using IP addresses or cookies and returns firmographic data, such as company name, industry, revenue, and employee range.

For a complete list of available attributes, see Firmographic Attributes Overview for Demandbase IP-API v3.

How Demandbase Identifies Companies

Demandbase uses the following methods to identify companies:

• IP addresses.
• User agent strings.
• Cookies, when available.
• Ad creative validation scans.

Client-Side Identification with the Demandbase Cookie

Client-side identification uses Demandbase cookies to identify companies when a cookie-to-company mapping exists.

To enable this feature, in Demandbase One for Marketing, go to Settings > Demandbase-Wide Settings > Account Connector. See Set Up Data Export to Third-Party Integrations Using Account Connector​.

If Demandbase cannot identify a company using a cookie, it uses IP-based and registry-based identification.

Implementation Requirements for Demandbase IP-API

Review the requirements for your implementation method before making API requests.

Server-Side Implementation Requirements

Server-side implementations require:

• A valid Demandbase account and server-side API token.
• An IP address included in the request.
• HTTPS.

Client-Side Implementation Requirements

Client-side implementations require:

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

Handle API Response Attributes

Demandbase IP-API response attributes can vary between requests. Do not assume that every response contains the same attributes or that all attributes have values.

Demandbase may add, remove, or modify attributes at any time. Although Demandbase aims to notify customers about significant changes, your implementation must handle changes to response attributes.

Retrieve Account Connector Custom Fields

When Account Connector integrations are configured and active, the API returns custom fields in the custom_fields object.

To configure Account Connector, in Demandbase One for Marketing, go to Settings > Demandbase-Wide Settings > Account Connector. See Set Up Data Export to Third-Party Integrations Using Account Connector​.

Prevent Caching from Affecting Demandbase Analytics

Do not cache Demandbase IP-API responses. Caching prevents requests from reaching Demandbase and can cause inaccurate analytics in Demandbase and related services.

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

Reuse API Data for Personalization

If you reuse API data for purposes such as website personalization, continue making an API request on every page to maintain accurate reporting.

You can store API data separately for reuse, but stored data must not replace API requests.

Maintain Stored API Data

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

Monitor the following attributes for changes:

• information_level: Identifies changes in the level of available company data, such as from Basic to Detailed.
• company_id: Identifies changes to the company associated with a visitor.

Update stored data 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 using the following attributes:

Important: To use registry attributes, contact your Demandbase Account Team.

Demandbase IP-API Request Endpoints

The Demandbase IP-API supports JSON and JavaScript response formats.

Demandbase IP-API Request Parameters

Demandbase IP-API Request Examples

JSON Request Examples

Server-side request

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 request using the Demandbase Tag

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

JavaScript Request Examples

Server-side request

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 request using the Demandbase Tag

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

Understanding Demandbase IP-API Responses

The IP-API returns company information based on whether Demandbase identifies a matching company.

Important: For server errors or service issues, check the Demandbase Status Page.

Response Values

Example Detailed Response for a Resolved IP Address

{
  "company_id": 645072,
  "company_name": "Demandbase, Inc.",
  "marketing_alias": "Demandbase",
  "industry": "Computer Software",
  "sub_industry": "Marketing Automation Software",
  "employee_count": 750,
  "annual_sales": 235000000,
  "revenue_range": "$100M - $250M",
  "employee_range": "Mid-Market",
  "information_level": "Detailed",
  "Audience": "Mid-Market Business",
  "audience_segment": "Software & Technology",
  "access_type": "corporate",
  "isp": false
}

Example Basic Response for an Unresolved IP Address

{
  "registry_company_name": "Example Registry",
  "registry_city": "Adelaide",
  "registry_state": "SA",
  "registry_country": "Australia",
  "registry_country_code": "AU",
  "registry_latitude": -34.93,
  "registry_longitude": 138.60,
  "isp": false,
  "information_level": "Basic",
  "Audience": "",
  "audience_segment": "",
  "ip": "1.0.0.0",
  "region_name": "South Australia"
}

Important: Response attributes vary depending on the available data. Some attributes may be missing or return null.

Demandbase IP-API JavaScript Code Example

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

Important: Replace YOUR_API_KEY with your Demandbase API key before making a request.

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