Copy page

Getting Started

Introduction

ContactBased Data APIs

ContactBased exposes three groups of endpoints:

• Intent feeds — search the feeds your organization can access for high-intent domains and contacts.
• Feed exports — create and read paginated exports of those searches, sized for downloads from a few thousand rows up into the millions.
• Contact enrichment — resolve a public contact_id (id_<16 hex>) into PII, email, and phone records.

Open the API Reference for the full OpenAPI document and to try requests interactively.

Authentication

Every endpoint uses API key authentication. Send your key in the X-API-Key header.

Code
curl -X POST https://intentapi.contactbased.com/intent/feeds/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"feed_id": "<feed-uuid>", "lookback_days": 30}'

Keys are managed from the ContactBased dashboard. Invalid or inactive keys return 401.

---

Intent feeds (/intent/feeds)

Endpoints for working with a feed your organization owns. Lookback windows and PII / business-info options are governed by the feed's configuration on your organization — requests outside those limits are rejected with 403.

Method & path	Role
POST /intent/feeds/preview	Read-only snapshot of a feed for the requested window. Returns totals and (optionally) per-day counts. Does not create a saved search.
POST /intent/feeds/search	Run a search against a feed and save the result. Returns a job_id you can later export from any number of times.
GET /intent/feeds/jobs?feed_id=…	List previously-run searches for a feed. Use the returned job_ids to re-export saved snapshots.

Lookback is expressed as lookback_days (1 – feed cap). The window ends today and is inclusive — lookback_days=30 covers the last 30 days.

Sizing exports. The search response includes records_with_contact_id and records_without_contact_id. If you intend to filter the export to rows with a stable contact identifier (require_contact_id=true), use records_with_contact_id to plan around the resulting row count.

---

Feed exports (/intent/feeds/exports)

A paginated export captures the matched rows of a search and lets you read them back one page at a time. Pages are stable for the life of the export, so the same (export_id, page) always returns the same rows — re-runs against an export do not consume additional export quota.

Method & path	Role
POST /intent/feeds/exports	Create an export. Provide feed_id + lookback_days to export a fresh window, or job_id to export a saved search. Returns an ExportSummary (including export_id, total_rows, total_pages, page_size).
POST /intent/feeds/exports/page	Read one page of an export. Body is { export_id, page }; pages are 1-indexed and must satisfy page <= total_pages.
POST /intent/feeds/exports/get	Look up a single export by id. Returns the same ExportSummary shape as create / list.
POST /intent/feeds/exports/list	List exports your organization has created. feed_id and job_id are optional filters; omit both to list every export.

Typical flow

Code
# 1. Create an export of the last 30 days for a feed.
curl -X POST https://intentapi.contactbased.com/intent/feeds/exports \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "feed_id": "<feed-uuid>",
    "lookback_days": 30,
    "page_size": 10000,
    "require_contact_id": true
  }'
# → { "export_id": "…", "total_rows": 23847, "total_pages": 3, "page_size": 10000, … }

# 2. Page through the rows.
for page in 1 2 3; do
  curl -X POST https://intentapi.contactbased.com/intent/feeds/exports/page \
    -H "Content-Type: application/json" \
    -H "X-API-Key: $API_KEY" \
    -d "{\"export_id\": \"…\", \"page\": $page}"
done

Options

• get_pii — include PII fields (name, address, demographics) on every row. Requires the feed to be configured for PII export on your organization.
• include_business_info — include business-info fields (e.g. linkedin_url). Requires the feed to be configured for business-info export.
• require_contact_id — only export rows that resolved to a stable contact_id. Use the resulting contact_id values with the enrichment APIs to fetch PII, emails, and phones on demand.
• max_rows — optional ceiling on total_rows. Useful when you want to cap the size of an export regardless of how many records the search matched.

Quota

Creating an export reserves quota equal to its total_rows. Reading pages of an existing export — or creating a new export against a search that's already been exported once — does not consume additional quota. List your organization's feeds to see remaining quota:

Field	Meaning
export_row_limit	Quota cap. null when the feed is uncapped.
export_rows_used	Quota consumed so far.
export_rows_remaining	What's left.

---

Organization feeds (/organization)

Method & path	Role
GET /organization/feeds	List the feeds your organization can access. Each entry includes the feed id, description, configured options (PII / business-info), the lookback_days cap, and the export quota fields above.

Call this once at startup (or as part of your dashboard load) so you can drive UI and validate inputs before hitting /intent/feeds.

---

Contact enrichment (/enrich)

Enrichment is keyed by the public contact_id returned on export rows.

• Format: id_ followed by 16 lowercase hex characters (19 characters total). Example: id_3f2a8d1b9c0e5f47. Legacy cb_ tokens are still accepted on input.

Method & path	Role
GET /enrich/contacts/{contact_id}	Full envelope with pii, emails, phones (each may be null). Optional include query narrows sections. 404 when no data exists for any requested section.
POST /enrich/contacts/batch	Up to 1000 contact_ids per request. results aligns by index with the input. Unknown ids return empty envelopes (found_sections == 0) rather than failing the batch. 413 for oversized payloads.
GET …/pii	Demographic and postal fields only. 404 if no PII record exists.
GET …/emails	Email observations per address (with hashes). 404 when no email record exists; 200 with [] when the record exists but has no addresses.
GET …/phones	Phone observations. 404 / 200 [] semantics analogous to emails.

Common status codes: 400 (bad contact_id or include), 401, 404, 422 validation, 502 (retry with backoff).

---

Next steps

• Browse the API Reference for full schemas and an interactive playground.
• Start with POST /intent/feeds/preview to validate a feed and window, then move to POST /intent/feeds/exports once you're ready to pull rows.