Skip to main content
build list
The assistant tool is build_list. Start an asynchronous export of person or company IDs for a feature-ID expression. max_records is required and must be from 1 to 10,000. The indexed export prepares up to 10,000 IDs; Datalayer returns at most max_records. The call reserves 1 credit per 100 requested IDs, rounded up, before the lookup. Settlement charges 1 credit per 100 IDs actually returned, rounded up, and releases the rest. An empty or failed export releases the reservation. max_credits from 0 to 100 rejects the call before the lookup when the reservation would exceed it. The response contains export_id and no record IDs. Poll get_list_results with that ID. The job token is not returned. The same Idempotency-Key replays this start. An identical export with a new key reserves again. Full profile enrichment is a separate charge at the existing profile price. dry_run estimates the reservation and does not require an active allowance. A real export does.

Authorizations

Authorization
string
header
required

Send Authorization: Bearer dl_live_<64 lowercase hexadecimal characters>. Signed-in users can create account-scoped, revocable keys in the Datalayer dashboard. A key does not grant credits. Dashboard session cookies are not API credentials.

Headers

Idempotency-Key
string

Recommended for every paid operation. Account-scoped and bound to normalized operation/input. Retry exactly the same key after transport loss: a committed credit result is replayed from persisted normalized bytes without a data lookup or another debit. Changed input, key expiry or paid-anchor expiry returns 409. In-flight requests return request_in_progress. Network delivery and D1 commit are not atomic. If omitted a request ID is created.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]{1,128}$

Body

application/json
entity
enum<string>
required
Available options:
person,
company
query
string
required
max_records
integer
required
Required range: 1 <= x <= 10000
max_credits
integer

Advanced: highest number of credits this list may reserve, from 0 to 100. The call is refused before any lookup when the reservation would be higher.

Required range: 0 <= x <= 100
dry_run
boolean

Advanced: return the maximum credit estimate without looking up data.

Response

A settled result or a maximum estimate with no data lookup.

data
object
required
meta
object
required