Copy page

Getting Started

Introduction

ContactBased Data APIs

ContactBased helps you turn intent signals into exportable records and enrichable contacts.

The API has four main surfaces:

• Organization — list available feeds and read your records / feed creation limits.
• Intent feeds — preview or search feeds your organization can access.
• Feed exports — preview, count, create, page through, and download CSV exports.
• Enrichment — enrich exported contact_ids with enabled person, email, phone, location, professional, automotive, interest, donor, household, purchase, and financial bundles.

Open the API Reference for full schemas and the interactive playground.

Authentication

All public endpoints use API key authentication. Send your key in the X-API-Key header.

Code
curl -X GET https://intentapi.contactbased.com/organization/feeds \
  -H "X-API-Key: YOUR_API_KEY"

Invalid or inactive keys return 401.

Feeds

A feed is the saved audience definition you search or export against. Feeds can be based on domains, topics, or free text. Free-text feeds are resolved to matching domains when they are created or updated, so search and export queries run against a stable domain set.

Use GET /organization/feeds to list feeds available to your organization.

Endpoint	Purpose
GET /organization/feeds	Paginated list of accessible feeds. Supports search, page, and page_size.
GET /organization/credits	Org-wide records credit pool.
GET /organization/feed-limit	Self-serve feed creation limit.
POST /intent/feeds/builder	Preview a free-text feed query or save it as a new feed.
POST /intent/feeds/search	Return feed totals for a rolling window. Can also create an export with auto_export.

Lookback windows use lookback_days, ending today and inclusive. Feed and organization permissions decide the maximum allowed window.

Export Flow

The current export flow is asynchronous and bucket-backed. Creating an export stores metadata immediately with status: "building", then ContactBased materializes page CSVs and a full CSV in object storage. Poll the export summary or read pages until status becomes "ready".

Recommended flow:

1. Preview a configuration with POST /intent/feeds/exports/preview.
2. Optionally lazy-load exact counts with POST /intent/feeds/exports/count.
3. Create the export with POST /intent/feeds/exports.
4. Poll metadata from POST /intent/feeds/exports/list or your saved export_id.
5. Read pages with POST /intent/feeds/exports/page, or request a full-file URL with POST /intent/feeds/exports/download-url once ready.

Code
# 1. Preview rows and counts for the last 30 days.
curl -X POST https://intentapi.contactbased.com/intent/feeds/exports/preview \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "feed_id": "<feed-uuid>",
    "lookback_days": 30,
    "preview_rows": 100,
    "skip_count": false
  }'

# 2. Create the export.
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": "...", "status": "building", "total_rows": 23847, "total_pages": 3, ... }

# 3. Fetch a page after the export is ready.
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": 1 }'

# 4. Get a one-hour full CSV download URL.
curl -X POST https://intentapi.contactbased.com/intent/feeds/exports/download-url \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{ "export_id": "..." }'

Export Options

Option	Meaning
page_size	Rows per page, fixed at creation. Current range is 1,000 to 50,000.
max_rows	Optional ceiling on the export size.
require_contact_id	Only return rows with a stable contact_id. Required automatically by consumer filters and enrichment bundles.
consumer_filters	Demographic / lifestyle filters applied to contact-linked rows. Filters make the export person-distinct.
enrichment_bundles	Adds enabled enrichment bundle payloads as JSON columns on export rows.

Export summaries include status, build_progress, and build_error. status is one of building, ready, or failed.

Creating an export reserves records from your organization credit pool. Reading pages and downloading the finished CSV do not consume more records.

Filters

Consumer filters let you narrow exports to contact-linked people with specific demographic, household, financial, or lifestyle attributes.

Endpoint	Purpose
POST /intent/feeds/filters/fields	List supported filter fields, operators, labels, and categories.
POST /intent/feeds/filters/values	Fetch distinct values for a filter field to power autocomplete controls.

When consumer_filters is present, exports require contact IDs and return at most one row per matching contact_id.

Enrichment

Export rows may contain a public contact_id. Use that ID with /enrich to request additional bundles.

contact_id values are formatted as id_ followed by 16 lowercase hex characters, for example id_3f2a8d1b9c0e5f47.

Endpoint	Bundle
GET /enrich/bundles	Lists enrichment bundle keys enabled for your organization.
POST /enrich/individual-core	Core person and address fields.
POST /enrich/emails	Email addresses and hash fields. Email records expose last_seen, the most recent of source register/update dates.
POST /enrich/phones	Phone numbers and phone metadata.
POST /enrich/location	Address and geographic location details.
POST /enrich/professional	Professional and LinkedIn-style signals.
POST /enrich/auto	Automotive ownership and vehicle summaries.
POST /enrich/interests	Interest signals.
POST /enrich/donor	Charitable giving signals.
POST /enrich/household	Household and property signals.
POST /enrich/purchases	Purchase and shopping behavior signals.
POST /enrich/financial	Credit, income, and asset indicators.

Enrichment requests are bulk-first:

Code
curl -X POST https://intentapi.contactbased.com/enrich/emails \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "contact_ids": ["id_3f2a8d1b9c0e5f47"]
  }'

Responses preserve input order and include found / not-found counts. Unknown contacts do not fail the whole batch.

Next Steps

• Start with GET /organization/feeds to discover available feed IDs.
• Use POST /intent/feeds/exports/preview before creating large exports.
• Use POST /intent/feeds/exports/download-url when you need the full finished CSV.
• Use /enrich/bundles before requesting enrichment bundles, especially when appending bundles to exports.