Copy page

Getting Started

Introduction

BuyerFeeds Data APIs

BuyerFeeds 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 feeds, read feed stats, or export 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.buyerfeeds.com/intent/feeds \
  -H "X-API-Key: YOUR_API_KEY"

Invalid or inactive keys return 401.

Feeds

A feed is the saved audience definition you read stats 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 stats and export queries run against a stable domain set.

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

Endpoint	Purpose
GET /intent/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/stats	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 export flow is asynchronous and staging-first. Creating an export stores metadata immediately with status: "building". A background workflow snapshots an exact, ordered row set in ClickHouse; API pages read that immutable snapshot. A separate workflow renders the same rows into a compressed full.csv.gz download in object storage.

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. Request a full-file URL with POST /intent/feeds/exports/download-url; if CSV rendering is still running, poll until the endpoint returns a URL.

Code
# 1. Preview rows and counts for the last 30 days.
curl -X POST https://intentapi.buyerfeeds.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.buyerfeeds.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
  }'

# Exact counts are settled by the worker, so creation starts at zero.
# -> { "export_id": "...", "status": "building", "total_rows": 0, "total_pages": 0, ... }

# 3. Fetch a page after the export is ready.
curl -X POST https://intentapi.buyerfeeds.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.buyerfeeds.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. Terminal retention states can also report expired or source_expired; a rebuildable expired export is automatically queued for rebuilding.

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.buyerfeeds.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 /intent/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.