Skip to main content
POST
Import Prospects

Authorizations

X-API-Key
string
header
required

API Key for authentication

Body

application/json
mode
enum<string>
required

FILTERS requests count matches of query starting at startOffset, not a page of guaranteed unimported people; SELECTED uses distinct preview providerIds. Selected IDs not returned by the provider are skipped, so delivery is not guaranteed.

Available options:
FILTERS,
SELECTED
schemaVersion
string
required

The version the search schema currently reports, e.g. people.v1. Any other value is refused.

Minimum string length: 1
Example:

"people.v1"

destination
Existing list · object
required

Where the prospects land. Exactly one of listId and listName is set; the other is omitted or null.

idempotencyKey
string<uuid>
required

A UUID v4 the caller generates for this purchase; reuse it only to retry the same purchase.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
maxCreditsSpend
integer
required

The most credits this import may charge: count × 1 for FILTERS, the number of distinct providerIds × 1 for SELECTED; 1 credit per retrieved prospect. The start is refused when the cost could exceed it.

Required range: 0 <= x <= 2147483647
Example:

50

query
object
required if mode = FILTERS

FILTERS only: the people-search query, the flat list of conditions {"filters":[…]} in the grammar Get Lead Finder Search Schema publishes — the same query the preview took. Omit for SELECTED: it does not select or exclude people, although a supplied query still must pass the gateway’s input validation. A key the grammar does not accept is refused, naming it; no key is dropped silently.

Example:
count
integer
required if mode = FILTERS

FILTERS: required number of matches to request from startOffset in the live query results. Omit for SELECTED: selection uses distinct providerIds, not count. If supplied, count still must pass the input type and bounds. A count above the Prospect Capacity left or above what the balance covers, or a window with startOffset + count above the search schema's limits.resultCeiling, is refused before anything starts; an import is never trimmed to fit. The import stops when matches run out and charges only what it retrieved. Previously imported people may appear in the window and are retrieved and charged again; live ordering can shift, so a later offset does not guarantee new people.

Required range: 1 <= x <= 2147483647
Example:

50

startOffset
integer

Zero-based start of the FILTERS purchase window in the live query results. Omitted means zero at the backend. startOffset + count must not exceed the search schema's limits.resultCeiling (10000). SELECTED permits only omitted or zero. Live ordering can change between purchases; skipped rows are not bought and the offset does not guarantee new people.

Required range: 0 <= x <= 2147483647
Examples:

0

100

providerIds
string[]
required if mode = SELECTED

SELECTED: providerId values from preview, 1 to 100; a repeated id counts once. Omit for FILTERS: they do not limit, exclude, or add query matches. If supplied, the array still must pass input validation.

Required array length: 1 - 100 elements
Minimum string length: 1

Response

status
string
required

Response status

Allowed value: "success"
data
object
required
message
string
required

Success message

Example:

"Operation completed successfully"