Enrichment API · v1

Append PII to any phone.

POST a list of phone numbers and get back names, demographics, addresses, emails, and the IP plus source URL we carry, all resolved against our own identity graph. No third-party API-uptime dependency. You query our warehouse directly.

One request, up to 100 phones

Batch a request and get a row per phone back in the same call.

Counts only, never your data

We log how many phones matched for billing. We never store your phones or the appended PII.

Simple key auth

One header. Create, pause, or revoke keys yourself on the Developers page.

What each endpoint returns

Endpoint	Built for	Returns	Typical speed
POST /api/v1/resolve	Real time (sub-second): live call routing, bidding, pre-qualification	One identifier in (phone or hashed email). Modes: enrich (~24 core fields: identity, address, age, income + credit bands, homeowner, home value, best contacts), rtb (a single pass/fail against your filters, no PII), identity (hashes, IP, source URL).	typically a few hundred milliseconds round trip over the public internet; identifiers outside the hot index fall back to a deeper lookup (phones and sha256 emails resolve in well under a second; md5 is a slower legacy path, so prefer sha256 for hashed email)
POST /api/v1/enrich	Batch append: up to 100 phones per call	Core identity + demographics + best contacts per phone, PLUS optional field groups: ~160 curated consumer attributes, ~165 property fields, financial, vehicles with VIN, executive roles, geo precision, all contacts, and purchase behavior.	a few seconds for a full 100-phone batch (core fields); allow up to ~10 s with every field group attached
POST /api/v1/pull	List building: homeowner lists by ZIP, on demand	ZIPs + filters (home value, year built, owner age, phone/email requirements) + a required record cap in; a queued order out. The CSV is emailed to the account and downloadable by key. Delivered records count toward the account's monthly plan.	async; typically a few minutes to the file
POST /api/v1/append-phone	Contact discovery: email or name+address in, phones out	The matched person's identity block, a match confidence grade, and every phone on file (type, rank, carrier, last seen, DNC status, and a single best-to-dial flag).	1 to 3 s per batch

Speeds above are conservative planning figures that include real network time; most calls come back faster. The Playground shows your own latency from your network on every call.

Quickstart

Three steps to your first call.

1Sign up at talkdatatome.online/signup. Any plan works to start.
2Create a key on the Developers page. Copy it right away. The key is shown once and starts with rk_.
3Make a call with the key in the X-API-Key header. Pick your language below.

Prefer to skip straight to a running call? The API Playground runs every endpoint from your browser with your key, shows real latency, and hands you the exact cURL to reproduce it.

cURL

curl -X POST https://www.talkdatatome.online/api/v1/resolve \
  -H "X-API-Key: rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"identifier": "4155550142"}'

Python

import requests

resp = requests.post(
    "https://www.talkdatatome.online/api/v1/resolve",
    headers={"X-API-Key": "rk_your_key_here"},
    json={"identifier": "4155550142"},
)
print(resp.json())  # {"matched": true, "first_name": "...", ...}

Node.js

const resp = await fetch("https://www.talkdatatome.online/api/v1/resolve", {
  method: "POST",
  headers: {
    "X-API-Key": "rk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ identifier: "4155550142" }),
});
console.log(await resp.json()); // { matched: true, first_name: "...", ... }

That is the real-time /resolve endpoint, which answers a single identifier in well under a second. To append data to a whole list at once, use the batch /enrich endpoint below. Both take the same key.

Authentication

Every request must include your secret key in the X-API-Key header. Keys look like rk_… and are shown to you once at creation. Treat your key like a password and never expose it in client-side code. A missing, invalid, inactive, or expired key returns 401.

Create and manage keys yourself on the Developers page: issue a new key, pause or revoke any key, and watch this month's usage. The same key works for both endpoints below.

Header

X-API-Key: rk_your_key_here

Enrich phones

POST/api/v1/enrich

Send one phone via {"phone": "..."} or up to 100 via {"phones": ["...", "..."]}. Phones can be in any common format. We normalize to 10 digits and de-duplicate before resolving. Every submitted phone comes back in results, matched or not.

cURL

curl -X POST https://www.talkdatatome.online/api/v1/enrich \
  -H "X-API-Key: rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["+1 (415) 555-0142", "2025550173"]}'

Request body

{
  "phones": [
    "+1 (415) 555-0142",
    "2025550173"
  ]
}

Response

{
  "requested": 2,
  "matched": 1,
  "results": [
    {
      "phone": "+1 (415) 555-0142",
      "matched": true,
      "first_name": "Jordan",
      "last_name": "Avery",
      "age": 47,
      "gender": "M",
      "marital_status": "Married",
      "homeowner": "Home Owner",
      "household_income": 112500,
      "address": "1240 Oak Ridge Dr",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94110",
      "mobile_phone": "4155550142",
      "landline_phone": "4155550199",
      "email": "jordan.avery@example.com",
      "ip_address": "73.92.18.204",
      "source_url": "homeimprovementquotes.com"
    },
    {
      "phone": "2025550173",
      "matched": false
    }
  ]
}

Null fields are omitted from a matched result, so a record only carries the attributes we actually hold. An unmatched phone returns just {"phone": "...", "matched": false}. You are billed for matched rows only.

Response fields

Field	Type	Description
`phone`	string	The phone number you submitted, echoed back.
`matched`	boolean	Whether the phone resolved to an identity.
`first_name`	string	Given name on the resolved identity.
`last_name`	string	Family name on the resolved identity.
`age`	number	Estimated age.
`gender`	string	Gender on file.
`marital_status`	string	Marital status on file.
`homeowner`	string	Home ownership status.
`household_income`	number	Estimated household income midpoint.
`address`	string	Standardized street address.
`city`	string	Standardized city.
`state`	string	Two-letter state code.
`zip`	string	ZIP code.
`mobile_phone`	string	Best deliverable mobile number on the identity.
`landline_phone`	string	Best landline on the identity.
`email`	string	Best email on the identity.
`ip_address`	string	IP address associated with the identity.
`source_url`	string	Source URL associated with the identity.

Field groups: the full data dictionary on batch enrich

The default response carries the core identity + demographic set above. Pass fields to nest entire data-dictionary sections on every matched row. Billing is unchanged: a matched row counts once no matter how many groups you request.

Group	Returns	Shape
demographics	A curated ~160-attribute set from the consumer data tab: interests, purchase behavior, lifestyle, household composition, occupation, education, and more. Null-valued attributes are omitted per row. The full 2,000+ attribute tab is available through managed appends and file delivery.	`demographics: {...}`
property	The property tab for the person's address: ~165 fields (year built, square footage, beds/baths, lot, pool, valuation, sale history, owner occupancy).	`property: {...}`
financial	The financial tab: income, net-worth and investment indicators, credit activity.	`financial: {...}`
auto	The consumer auto tab: up to 5 vehicles per person with VIN, make, model, year, body type, fuel, purchase date, and more.	`vehicles: [{...}]`
geo	Territory precision for the person's address: latitude/longitude, county, DMA, MSA, CBSA, census tract and block group, congressional district, ZIP+4, urbanicity, plus birth month and year.	`geo: {...}`
contacts	Every contact point on the person: up to 10 phones (type, rank, carrier, work-phone flag, DNC, quality, last seen) and up to 5 emails (rank, quality, opt-in, md5/sha256, register and update dates).	`contacts: {phones: [...], emails: [...]}`
purchase_behavior	~114 recent-purchase aggregates by category: dollars, orders, items, and company counts (apparel, home goods, donations, subscriptions, gourmet, and more).	`purchase_behavior: {...}`
signals	Live in-market intent (rolling recent window): consumer and business topics the person is actively researching, with topic names, categories, frequency, and recency. Up to 25 of each per person.	`signals: {b2c: [...], b2b: [...]}`
behavior	Behavioral interest codes (IAB) with recency, the weekly behavioral feed. Up to 50 per person.	`behavior: [{...}]`
executive	The B2B executive-at-home overlay: up to 3 roles with company, title, executive level, SIC/industry, revenue band, and business contact points. Present when the person is a linked business executive.	`executive_roles: [{...}]`

Request with field groups

curl -X POST https://www.talkdatatome.online/api/v1/enrich \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["4155550142"], "fields": ["demographics", "property", "auto", "executive"]}'

Full example response (sample person, every group; field names are real)

{
  "requested": 1,
  "matched": 1,
  "results": [
    {
      "phone": "4155550142",
      "matched": true,
      "first_name": "Jordan",
      "last_name": "Avery",
      "age": 47,
      "gender": "M",
      "marital_status": "Married",
      "homeowner": "Home Owner",
      "household_income": 112500,
      "address": "1240 Oak Ridge Dr",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94110",
      "mobile_phone": "4155550142",
      "landline_phone": "4155550199",
      "email": "jordan.avery@example.com",
      "ip_address": "73.92.18.204",
      "source_url": "homeimprovementquotes.com",

      "demographics": {
        "age": 47,
        "birth_year": 1979,
        "credit_range": "B. 750-799",
        "credit_midpts": 775,
        "dwelling_type": "Single Family",
        "length_of_residence": 9,
        "children_hh": 2,
        "child_aged_7_9_hh": "Y",
        "occupation_category": "Management",
        "education": "College",
        "net_worth_hh": "$250,000-$499,999",
        "home_improvement": "Y",
        "diy": "Y",
        "cooking": "Y",
        "dog_owner": "Y",
        "camping_hiking": "Y",
        "travel_affinity": "Y",
        "investments": "Y",
        "credit_card": "Y",
        "catalog_affinity": "Y",
        "veteran_hh": "N",
        "donor_affinity": "Y"
        // ... ~108 more attributes on a real match (nulls omitted)
      },

      "property": {
        "yr_built_orig": 1987,
        "living_sqft": 2140,
        "land_sqft": 6300,
        "nmbr_bedrooms": 4,
        "tot_baths_est": 2.5,
        "full_baths": 2,
        "half_baths": 1,
        "pool": "Y",
        "owner_occupied": "Y",
        "estimated_value": 918000,
        "assess_val_prop": 742000,
        "sale_date": "2017-08-14",
        "sale_amt": 685000,
        "county_name": "San Francisco"
        // ... ~150 more property fields on a real match
      },

      "financial": {
        "discretionary_income": 38500,
        "mortgage_refinance_intent": "Y",
        "mortgage_open1st_intent": "N",
        "automotive_loan_intent": "N",
        "bank_card_intent": "Y",
        "personal_loan_intent": "N",
        "card_offer_response": "Y",
        "mortgage_offer_response": "N"
      },

      "vehicles": [
        {
          "vin": "SAMPLEVIN0000TEST",
          "make": "Toyota",
          "model": "Tundra",
          "year": 2019,
          "fuel": "Gasoline",
          "msrp": 41500,
          "body_type": "Truck",
          "class": "Mainstream",
          "drive_type": "4WD",
          "engine_cylinders": 8,
          "transmission_type": "Automatic",
          "purchase_date": "2021-03-02",
          "purchase_new": "N",
          "number_of_vehicles_in_hh": 2
          // ... full vehicle spec on a real match; up to 5 vehicles
        }
      ],

      "executive_roles": [
        {
          "company_name": "Avery Roofing Co",
          "standardized_title": "Owner",
          "executive_level": "C-Level",
          "executive_department": "Executive",
          "primary_sic_description": "Roofing Contractors",
          "location_sales_description": "$1M-$2.5M",
          "location_employee_description": "10-19",
          "bus_address_city": "San Francisco",
          "bus_address_state": "CA",
          "bus_phone": "4155550171"
          // ... ~100 more executive/business fields; up to 3 roles
        }
      ]
    }
  ]
}

The example is trimmed where marked: a real response carries ~160 demographics attributes and ~165 property fields per match, with null attributes omitted. Signed-in accounts can browse the complete field-by-field catalog on the Data catalog page.

Heads-up on size: demographics is wide; a full 100-phone batch with every group can run a few megabytes of JSON. Request only the groups you need. Groups are served from our own store; the batch cap stays 100 per request.

Need an attribute you do not see? The curated demographics set is a config choice, not a data limit. Any attribute from the full dictionary can be promoted into the API response, usually same day. Tell us which fields you need and they will be in your next call.

Error codes

Errors return a JSON body shaped like {"error": "..."} with the matching HTTP status.

Status	Meaning
`400`	Malformed request. Body is not valid JSON, or the phone count is outside 1 to 100.
`401`	Missing, invalid, inactive, or expired API key.
`429`	Monthly enrichment cap reached for this key.
`500`	Something failed on our side. Safe to retry shortly.
`503`	The service is not fully configured. Contact us if this persists.

Rate limits

Up to 100 phones per request. Larger batches return 400. Split bigger jobs into multiple calls.
Each key can carry a monthly matched-row cap. Once you reach it, requests return 429 until the next calendar month. Only matched rows count toward the cap.
Need a higher cap or volume pricing? Reach out and we will size a plan to your usage.

List pulls by ZIP

Build a homeowner list programmatically instead of looking up records you already have. POST ZIPs, optional filters, and a required max_records cap; the pull runs asynchronously, the CSV is emailed to your account, and the file is downloadable over the API. The cap is a hard ceiling, and a pull is refused up front if it would exceed the records remaining on your monthly plan, so a runaway job cannot surprise you.

Queue a pull

curl -X POST https://www.talkdatatome.online/api/v1/pull   -H "X-API-Key: YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "zips": ["77066", "77069", "77070"],
    "max_records": 5000,
    "filters": {
      "min_home_value": 150000,
      "year_built_on_or_before": 2010,
      "phone_requirement": "mobile"
    }
  }'
# → 202 {"queued": true, ...}

# Poll status + get the download link:
curl https://www.talkdatatome.online/api/v1/pull -H "X-API-Key: YOUR_KEY"
# → {"orders": [{"id": "...", "status": "completed", "record_count": 5000,
#                "download_url": "/api/v1/pull/<id>/download"}]}

Filters: min_home_value, max_home_value, year_built_on_or_after, year_built_on_or_before, min_owner_age, max_owner_age, require_email, phone_requirement ("mobile", "any", or "none"). Up to 1,000 ZIPs and 100,000 records per pull; bigger jobs run managed.

Bulk appends

The batch endpoints are deliberately capped at 100 records per request: it keeps latency flat, keeps any single failure small, and lets your integration stream results as they come back. For bulk jobs, loop your file in pages of 100. A one million row append is 10,000 sequential requests and typically finishes in under an hour from a single worker; run a few workers in parallel to go faster. Your monthly cap is enforced across all of them, and only matched rows count toward it.

Bulk loop (Node)

const rows = phones; // your full list
for (let i = 0; i < rows.length; i += 100) {
  const batch = rows.slice(i, i + 100);
  const resp = await fetch("https://www.talkdatatome.online/api/v1/enrich", {
    method: "POST",
    headers: { "X-API-Key": process.env.TDTM_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ phones: batch }),
  });
  const { results } = await resp.json();
  // append results to your output as you go
}

Prefer a one-shot file instead of an integration? Any list size can be run as a managed bulk job from your workspace: upload the file in the chat and the finished CSV is emailed to you with a download link in your History. Enterprise accounts can also hand us the file and we run it white glove.

Common recipes

Geo routing (phone to ZIP)

POST the caller’s number to /api/v1/resolve (default enrich mode) and read zip off the response, fast enough to sit inside live call routing. Route the call, then enrich the rest of the profile after connect if you want it.

Inbound call pre-qualification

Use resolve’s rtb mode: pass your filters (state, ZIP list, age range, homeowner, income floor) and get back a single pass boolean with no PII, built for bid or no-bid decisions on live calls.

Full data append (phone to PII++)

Batch up to 100 phones per call on /api/v1/enrich for name, address, demographics, email, IP, and source URL. For email or name-and-address keys instead of phones, use /api/v1/append-phone.

Realtime Resolution API · v1

Resolve a person in under 15ms

The Resolution API is the fast, single-identifier twin of the Enrichment API. Send any one identifier and get a small response back fast enough to sit inside an inbound-call routing loop. It is built for real-time bidding (RTB) pre-qualification, on-the-fly enrichment, and pixel resolution. Where /api/v1/enrich batches up to 100 phones against the warehouse, this endpoint answers a single lookup from a hot in-memory store, so it answers fast enough to sit inside a live call flow (typically a few hundred milliseconds end to end).

Under 15ms per lookup

One identifier in, a small answer out. Fast enough for the bid loop, not the batch job.

Any identifier, auto-detected

Phone, md5, sha1, or sha256. We pick the right index from the value’s shape.

Three response modes

Full enrich, a yes/no RTB pre-qual with no PII, or just the identity keys.

POST/api/v1/resolve

Authentication is identical to the Enrichment API. Send the same partner key in the X-API-Key header. A missing, invalid, inactive, or expired key returns 401.

The identifier

Send exactly one identifier as {"identifier": "..."}. We detect its kind automatically from its format, so you do not declare a type. For backward compatibility, the legacy {"phone": "..."} and {"sha256": "..."} fields are still accepted.

Format	Detected as
`Phone`	10 digits, or 11 with a leading 1. Normalized to 10 digits.
`md5`	32 hex characters (md5 of a normalized email).
`sha1`	40 hex characters (sha1 of a normalized email).
`sha256`	64 hex characters (sha256 of a normalized email).

Response modes

Choose what comes back with the optional mode field. The default is enrich. Any other value returns 400. On a miss every mode returns {"matched": false}. Null fields are always omitted, so a result only carries the attributes we actually hold.

mode: "enrich"default

Returns the populated PII and demographic fields for the resolved person, the same data points the batch /api/v1/enrich endpoint returns (including phones, email, IP, and source URL). Only non-null fields come back, so the example below shows a representative subset; the full set is in the table.

cURL

curl -X POST https://www.talkdatatome.online/api/v1/resolve \
  -H "X-API-Key: rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"identifier": "4155550142"}'

Request body

{
  "identifier": "4155550142"
}

Response

{
  "matched": true,
  "first_name": "Jordan",
  "last_name": "Avery",
  "address": "1240 Oak Ridge Dr",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94110",
  "age": 47,
  "income_band": "L. $150,000-$174,999",
  "income_midpoint": 162500,
  "credit_range": "A. 800+",
  "credit_midpoint": 820,
  "homeowner": "Home Owner",
  "email": "jordan.avery@example.com"
}

Field	Type	Description
`matched`	boolean	Whether the identifier resolved to a person.
`first_name`	string	Given name on the resolved identity.
`last_name`	string	Family name on the resolved identity.
`address`	string	Standardized street address.
`city`	string	Standardized city.
`state`	string	Two-letter state code.
`zip`	string	Five-digit ZIP code.
`age`	number	Estimated age.
`gender`	string	Gender on file.
`marital_status`	string	Marital status on file.
`income_band`	string	Household income band label, e.g. "L. $150,000-$174,999".
`income_midpoint`	number	Numeric household income midpoint, in dollars.
`credit_range`	string	Credit range label, e.g. "A. 800+".
`credit_midpoint`	number	Numeric credit-score midpoint.
`homeowner`	string	Home ownership status: "Home Owner", "Renter", or "Probable Home Owner".
`home_value`	number	Estimated home value, in dollars.
`household_size`	number	Number of people in the household.
`birth_month_and_year`	string	Birth month and year on file, e.g. "1977-04".
`year_built`	number	Year the residence was built.
`dnc`	number	Do Not Call state of the returned mobile. 0 means callable (the served mobile is DNC-clean by construction).
`mobile_phone`	string	Best deliverable mobile number on the identity.
`landline_phone`	string	Best landline on the identity.
`email`	string	Best email on the identity.
`ip`	string	IP address associated with the identity.
`source_url`	string	Opt-in or lead source URL on the identity.

mode: "rtb"pre-qualification, no PII

For real-time bidding. Send the identifier plus pre-qual filters and get back only {"matched", "pass"}, never any PII. Filters can sit at the top level or under a filters object. Every filter you send must pass, and a filter referencing a field the profile does not carry fails (we will not assert a qualification we have no data for). A miss, or any failed filter, returns "pass": false.

cURL

curl -X POST https://www.talkdatatome.online/api/v1/resolve \
  -H "X-API-Key: rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "4155550142",
    "mode": "rtb",
    "state": "CA",
    "age_min": 35,
    "income_min": 100000,
    "homeowner": true
  }'

Request body

{
  "identifier": "4155550142",
  "mode": "rtb",
  "state": "CA",
  "age_min": 35,
  "income_min": 100000,
  "homeowner": true
}

Response

{
  "matched": true,
  "pass": true
}

Pre-qual filters (all optional)

Field	Type	Description
`zip`	string	Profile ZIP must match these five digits exactly.
`state`	string	Profile state must match this two-letter code (case-insensitive).
`age_min`	number	Profile age must be at least this value.
`age_max`	number	Profile age must be at most this value.
`income_min`	number	Income midpoint must be at least this many dollars.
`credit_min`	number	Credit midpoint must be at least this value.
`homeowner`	boolean	When true, the profile must be a (probable) homeowner.

mode: "identity"identity keys only

Returns only the identity keys for the resolved person (hashes, IP, source URL, and registration date), with no demographics. Useful for pixel resolution and identity stitching. Only non-null fields come back.

cURL

curl -X POST https://www.talkdatatome.online/api/v1/resolve \
  -H "X-API-Key: rk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "5d41402abc4b2a76b9719d911017c592",
    "mode": "identity"
  }'

Request body

{
  "identifier": "5d41402abc4b2a76b9719d911017c592",
  "mode": "identity"
}

Response

{
  "matched": true,
  "md5": "5d41402abc4b2a76b9719d911017c592",
  "sha256": "9b2c…e4f1",
  "ip": "73.92.18.204",
  "source_url": "homeimprovementquotes.com",
  "registration_date": "2024-11-03"
}

Field	Type	Description
`matched`	boolean	Whether the identifier resolved to a person.
`md5`	string	md5 of the normalized email on the identity.
`sha256`	string	sha256 of the normalized email on the identity.
`ip`	string	IP address associated with the identity.
`source_url`	string	Opt-in or lead source URL on the identity.
`registration_date`	string	Registration date on the source record.

Error codes

Errors return a JSON body shaped like {"error": "..."} with the matching HTTP status. Note there is no rate-cap status here: a miss is a normal 200 with "matched": false.

Status	Meaning
`400`	Body is not valid JSON, the mode is unknown, or no valid identifier was supplied.
`401`	Missing, invalid, inactive, or expired API key.
`503`	The backend is not configured. Contact us if this persists.

Phone Append API

Append phones from an email or a mailing address

The reverse of the Enrichment API. Send up to 100 plaintext emails and/or up to 100 name-and-address records per call, and get back each person's phones (best number flagged), plus their name and postal address. Built for CRM phone-fill and outreach list preparation. Plan for 1 to 3 seconds per batch.

POST/api/v1/append-phone

Authentication is identical to the other endpoints: send your partner key in the X-API-Key header. Emails must be plaintext (we hash them server-side to hit the index; a pre-hashed value cannot be converted, so it will not match). Records match through the postal graph first; when only the record's email matches, a last-name gate keeps us from returning a different person, and a same-surname, different-first-name match comes back flagged at low confidence. We log match counts only: the emails you submit and the phones we return are never persisted.

cURL (emails)

curl -X POST https://www.talkdatatome.online/api/v1/append-phone \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"emails": ["jane.doe@example.com"]}'

Request body (records)

{
  "records": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "address": "123 Main St",
      "city": "Tampa",
      "state": "FL",
      "zip": "33601",
      "email": "jane.doe@example.com"
    }
  ]
}

Response

{
  "requested": 1,
  "matched": 1,
  "results": [
    {
      "input": "jane.doe@example.com",
      "matched": true,
      "confidence": "medium",
      "first_name": "JANE",
      "last_name": "DOE",
      "address": "123 MAIN ST",
      "city": "TAMPA",
      "state": "FL",
      "zip": "33601",
      "phones": [
        { "phone": "8135550142", "type": "mobile", "rank": 1, "carrier": "T-MOBILE",
          "last_seen": "2026-04-18", "dnc": "callable", "best": true },
        { "phone": "8135550177", "type": "landline", "rank": 1, "carrier": null,
          "last_seen": "2025-11-02", "dnc": "callable", "best": false }
      ]
    }
  ]
}

Result fields

Email inputs come back in results (same order as submitted). Record inputs come back in record_results, each echoing the record you sent. A miss is a normal 200 with "matched": false.

Field	Type	Description
`input`	string	The email you submitted, echoed back (record results echo the record fields instead).
`matched`	boolean	Whether the input resolved to a person with at least one phone.
`confidence`	string	"medium" or "low". Low means treat with care (for example, the match may be another member of the same household).
`first_name`	string	Given name on the matched identity. Null on a miss.
`last_name`	string	Family name on the matched identity. Null on a miss.
`address`	string	Street address on the matched identity.
`city`	string	City on the matched identity.
`state`	string	Two-letter state code.
`zip`	string	ZIP code.
`phones`	array	Every phone on the identity, ordered best-first. Empty on a miss.

Each entry in `phones`

Field	Type	Description
`phone`	string	Ten-digit phone number.
`type`	string	"mobile", "landline", or "voip".
`rank`	number	Position within its tier (lower is fresher/stronger).
`carrier`	string	Carrier name when known, else null.
`last_seen`	string	Date this number was last confirmed active for the person.
`dnc`	string	"callable" or "DNC" (on the national Do Not Call registry).
`best`	boolean	True on exactly one phone per match: the single number to dial first.

Error codes

Status	Meaning
`400`	Malformed request. Body is not valid JSON, no inputs given, or more than 100 emails / 100 records.
`401`	Missing, invalid, inactive, or expired API key.
`429`	Monthly matched-row cap reached for this key.
`500`	Something failed on our side. Safe to retry shortly.

Ready to start enriching?

Create your key on the Developers page and make your first call in minutes. Need a higher cap or volume pricing? Talk to us.

Create a key See pricing Contact sales

Append PII to any phone.

One request, up to 100 phones

Counts only, never your data

Simple key auth

What each endpoint returns

Quickstart

Authentication

Enrich phones

Request body

Response

Response fields

Field groups: the full data dictionary on batch enrich

Error codes

Rate limits

List pulls by ZIP

Bulk appends

Common recipes

Geo routing (phone to ZIP)

Inbound call pre-qualification

Full data append (phone to PII++)

Resolve a person in under 15ms

Under 15ms per lookup

Any identifier, auto-detected

Three response modes

The identifier

Response modes

Request body

Response

Request body

Response

Pre-qual filters (all optional)

Request body

Response

Error codes

Append phones from an email or a mailing address

Result fields

Each entry in phones

Error codes

Ready to start enriching?

Each entry in `phones`