BIGDBM API Reference

Getting Started

Overview

The BIGDBM API suite lets you query behavioral intent signals, resolve identifiers, and enrich profiles, all over HTTPS using JSON payloads. Every response includes structured data you can pipe directly into your CRM, CDP, or data warehouse.

• Query consumer intent by keyword, date range, and volume
• Enrich emails, phones, addresses, MAIDs, and IPs in real time
• Receive hashed email (HEM) lists for audience activation
• All endpoints return standard JSON with consistent error shapes

Base URL

All API requests must be made over HTTPS. HTTP requests will be rejected. API keys are issued per account and scoped to the products you have licensed.

Security

Authentication

All BIGDBM API endpoints require a Bearer token passed in the Authorization header.

Tokens are issued by your BIGDBM account representative. Each token is scoped to specific API products and rate limits. Do not share tokens or commit them to version control, use environment variables or a secrets manager.

• Tokens do not expire on a fixed schedule, but can be rotated on request
• Each token is tied to your organization and audit-logged
• A missing or invalid token returns 401 Unauthorized

B2B Lookup API

B2B API Lookup

One endpoint, multiple data outputs. Submit any B2B identifier — email, phone, company name, or PII — with an OutputID that defines exactly what data comes back. One request structure, one auth header, one response shape across every output type.

1. Send a Request

{
  "requestId": "123456789",
  "input":     "john.snow@example.com",
  "outputId":  2
}

2. Choose Your OutputID

Each OutputID returns a distinct, pre-defined set of fields. Pick the one that matches your use case — no need to request all data every time.

{
  "requestId": "123456789",
  "returnData": {
    "john.snow@example.com": [{
      "EmployeeID":          "E1234567",
      "First_Name":          "John",
      "Last_Name":           "Snow",
      "Address":             "123 Main Street",
      "City":                "Anytown",
      "State":               "CA",
      "Zip5":                "90210",
      "Job_Title":           "Manager",
      "Level":               "",
      "Job_Function":        "MANAGEMENT",
      "Company_Name":        "EXAMPLE CORP",
      "Company_Website":     "example.com",
      "Headquarters_Branch": "2",
      "Num_Employees":       "1 TO 49",
      "NAICS_CODE":          "541512",
      "Sales_Volume":        "$500K TO $1M",
      "Year_Founded":        "2010",
      "B2B_Email":           "john.snow@example.com",
      "LastSeenDate":        "01/15/2024",
      "LinkedIn":            ""
    }]
  }
}

{
  "requestId": "123456789",
  "returnData": {
    "john.snow@example.com": [{
      "EmployeeID":          "E7654321",
      "First_Name":          "John",
      "Last_Name":           "Snow",
      "Address":             "123 Main Street",
      "City":                "Anytown",
      "State":               "CA",
      "Zip5":                "90210",
      "Job_Title":           "DIRECTOR",
      "Level":               "DIRECTOR-LEVEL",
      "Job_Function":        "MANAGEMENT",
      "Company_Name":        "EXAMPLE SOLUTIONS INC",
      "Company_Website":     "examplesolutions.com",
      "Headquarters_Branch": "2",
      "Num_Employees":       "100 TO 249",
      "NAICS_CODE":          "813910",
      "Sales_Volume":        "$10 TO 20 MILLION",
      "Year_Founded":        "2015",
      "B2B_Email":           "john.snow@example.com",
      "LastSeenDate":        "01/01/2023",
      "LinkedIn":            ""
    }]
  }
}

{
  "requestId": "123456789",
  "returnData": {
    "john.snow@example.com": [{
      "EmployeeID":       "E9968776",
      "Phone1_Employee":  "5551234567",
      "Phone1_Company":   "5559876543"
    }]
  }
}

{
  "requestId": "123456789",
  "returnData": {
    "192.0.2.1": [{
      "EmployeeID":            "E4102710",
      "First_Name":            "John",
      "Last_Name":             "Snow",
      "Gender":                "M",
      "Name_Prefix":           "MR",
      "Job_Title":             "Manager",
      "Level":                 "MANAGER-LEVEL",
      "Job_Function":          "MANAGEMENT",
      "Department":            "ADMINISTRATION & OPS",
      "B2B_Email":             "john.snow@example.com",
      "Personal_Address":      "123 Main Street",
      "Personal_City":         "Anytown",
      "Personal_State":        "CA",
      "Personal_Zip5":         "90210",
      "Personal_Email":        "john.snow@example.com",
      "Ip_Address":            "192.0.2.1",
      "Phone":                 "5551234567",
      "PhoneType":             "1",
      "Language_Code":         "EN",
      "Rank":                  "CX"
    }]
  }
}

{
  "email":          "john.snow@example.com",
  "emailStatus":   "Active",
  "emailConfidence":"High",
  "isDeliverable": true,
  "riskScore":     "Low",
  "emailSource":   "Verified"
}

Sync APIs

B2B Sync APIs

Enrich business records in real time using a wide range of B2B identifiers. Whether you're starting from a company name, an IP address, a LinkedIn profile, or a hashed email, these APIs instantly append firmographic, contact, and intent data to your existing records — accelerating sales, marketing, and operational workflows.

• Account-Based Marketing — match inbound signals to company records and trigger targeted campaigns
• Lead Enrichment — append missing firmographic and contact data to incomplete CRM records
• Real-time Scoring — enrich leads the moment they enter your pipeline for immediate sales prioritization
• Identity Resolution — match across identifiers (IP, email, LinkedIn, phone) to a single company profile

Available Endpoints

Consumer Lookup API

Consumer API Lookup

One endpoint, multiple data outputs. Submit any consumer identifier — email, phone, mobile, or address — with an OutputID that defines exactly what data comes back. One request structure, one auth header, one response shape across every output type.

1. Send a Request

{
  "requestId": "123456789",
  "input":     "john.snow@example.com",
  "outputId":  2
}

2. Choose Your OutputID

Each OutputID returns a distinct, pre-defined set of consumer fields. Pick the one that matches your use case.

{
  "requestId": "123456789",
  "returnData": {
    "john.snow@example.com": [{
      "Id":         "C1234567",
      "First_Name": "John",
      "Last_Name":  "Snow",
      "Address":    "123 Main Street",
      "City":       "Anytown",
      "State":      "CA",
      "Zip":        "90210",
      "Email":      "john.snow@example.com",
      "Phone":      "5551234567"
    }]
  }
}

{
  "requestId": "123456789",
  "returnData": {
    "john.snow@example.com": [{
      "Id":    "C1234567",
      "Email": "john.snow@example.com"
    }]
  }
}

{
  "requestId": "123456789",
  "returnData": {
    "john.snow@example.com": [{
      "Id":         "C1234567",
      "First_Name": "John",
      "Last_Name":  "Snow",
      "Phone_PhoneType": [{
        "phone":     "5551234567",
        "phoneType": "1"
      }]
    }]
  }
}

{
  "requestId": "123456789",
  "returnData": {
    "john.snow@example.com": [{
      "Id":                      "C1234567",
      "First_Name":              "John",
      "Last_Name":               "Snow",
      "Address":                 "123 Main Street",
      "City":                    "Anytown",
      "State":                   "CA",
      "Zip":                     "90210",
      "NationalConsumerDatabase":"1",
      "Email_Array":             ["john.snow@example.com"],
      "Phone_Array":             ["5551234567"]
    }]
  }
}

{
  "requestId": "123456789",
  "returnData": {
    "john.snow@example.com": [{
      "Id":                   "C1234567",
      "First_Name":           "John",
      "Last_Name":            "Snow",
      "Address":              "123 Main Street",
      "City":                 "Anytown",
      "State":                "CA",
      "Zip":                  "90210",
      "Gender":               "Male",
      "Age":                  "37",
      "Children_HH":          "2",
      "Credit_Range":         "C. 700-749",
      "Home_Owner":           "Home Owner",
      "Income_HH":            "K. $100,000-$149,999",
      "Marital_Status":       "Single",
      "Net_Worth_HH":         "J. Greater than $499,999",
      "Occupation_Detail":    "Manager",
      "Veteran_HH":           "1",
      "NationalConsumerDatabase":"1",
      "Mobile_Phone_1":       "5551234567",
      "Mobile_Phone_1_DNC":   "",
      "Mobile_Phone_2":       "",
      "Mobile_Phone_2_DNC":   "",
      "Email_Array": [
        "john.snow@example.com",
        "j.snow@example.net"
      ],
      "Email_LastSeenDate_1": "01/15/2024",
      "Email_LastSeenDate_2": ""
    }]
  }
}

Sync APIs

Consumer Sync APIs

Enhance existing consumer records with additional attributes in real time. All consumer sync endpoints use a configurable Output ID (10008), fully customizable to your requirements before production deployment. Ideal for identity resolution, profile enrichment, and improving match rates across marketing, analytics, and activation workflows.

Available Endpoints (14)

Intent APIs

Intent by Item (IAB, Keyword, Domain)

The Intent API 2.4 enables you to discover individuals actively researching specific products, brands, or services. By surfacing people who are already showing buying intent, you can prioritize your highest-value prospects and reach them when they're most likely to convert.

POST /intent/createList

Creates an intent-based audience list and returns matching hashed email addresses (HEMs) for activation or enrichment.

Request Example

curl --location 'https://aws-behavioral-intent-api.bigdbm.com/intent/createList' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
    "StartDate": "2025-12-03",
    "EndDate": "2025-12-03",
    "Keywords": "audi",
    "NumberOfHems": 1000
}'

Parameters

Sample Response

{
  "status": "success",
  "listId": "lst_7f3a9b2c4d1e",
  "count": 1000,
  "hems": [
    {
      "hem": "a3f4e8b7c2d1901ef56a3b2c4d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
      "signal_date": "2025-12-03",
      "confidence": 0.94,
      "signal_count": 7
    }
  ],
  "metadata": {
    "processing_ms": 143,
    "keyword_match_pool": 48291,
    "api_version": "2.4"
  }
}

Intent APIs

Intent by MD5

The Intent 3.0 API works in reverse: by submitting an MD5 identifier, you can retrieve the topics, products, or services that an individual has recently searched for. This allows for deeper audience insights, personalized messaging, smarter segmentation, and more effective downstream activation.

Audience APIs

Audience Creation APIs

Build precise, addressable audiences at scale across consumer, B2B, property, and healthcare datasets. Define your ideal customer profile and receive a matched audience ready for activation across any channel — DSP, CRM, email, or direct mail.

All audience creation endpoints share the same SmartSelector API documentation. Select the audience type below to access the technical reference for that dataset.

Consumer Audience

Build precise consumer audiences using demographic, behavioral, and lifestyle attributes. Receives a matched, addressable audience ready for activation.

B2B Audience

Create targeted B2B audiences from company size, industry, job function, seniority, and intent signals. Reach the right decision-makers at the right accounts with precision account-based targeting.

Property Audience

Build audiences based on property ownership, home value, mortgage status, and neighborhood attributes. Ideal for real estate, home services, insurance, and financial services campaigns targeting homeowners.

Healthcare Audience

Build compliant healthcare audiences from provider specialty, therapeutic category interest, and patient segment indicators. Designed for pharmaceutical, medical device, and health system marketing teams.

Service APIs

OPQL Phone Validation

The OPQL API verifies phone number reachability by querying telecom provider data directly. The response returns a numeric score from 0 to 5 — each value maps to a specific level of network activity and verification confidence, letting you make precise decisions about contact quality rather than a simple active/inactive flag.

Response Score Reference

Use Cases

Coming Soon

Coming Soon

Email APIs

Batch Email Validation

The Email Validation API lets you submit a list of email addresses and receive a deliverability verdict for each one. Use it to clean contact lists, suppress undeliverables before sends, and flag risky addresses that could harm sender reputation.

POST /email-cleansing/batch

Validates up to 10 email addresses in a single request and returns a deliverability status for each.

Request Example

curl --location 'https://r6q7ghcrah.execute-api.us-west-2.amazonaws.com/Prod/email-cleansing/batch' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--data '{
  "ValidatorId": 10,
  "Emails": [
    "alice@example.com",
    "bob@example.org"
  ]
}'

Request Parameters

Response Fields

Validation Status Codes

Sample Response

{
  "results": [
    {
      "email": "alice@example.com",
      "status": 10
    },
    {
      "email": "bob@example.org",
      "status": 30
    }
  ]
}

Error Messages (400 Bad Request)

Reference

Response Codes

All BIGDBM API endpoints return standard HTTP status codes. Errors include a message field with a human-readable description.