Skip to main content
POST
Run a planned people search

Authorizations

Authorization
string
header
required

Account API key passed in the Authorization header

Path Parameters

JobID
string
required

The planned job's ID

Example:

"b3c6f5e2-1234-4abc-9def-0123456789ab"

Body

application/json
list_name
string

Also save the people into Tamtam contacts lists, 10,000 per list: a new list with this name, then '_2', '_3' and so on. The lists fill as the job runs. Omit to save no list; the people are readable from the results endpoint either way.

Example:

"HR leaders FR"

max_results
integer<int64>

Stop once this many people are saved. Omit to save every match, up to 100,000.

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

100000

Response

Accepted

contacts_list_ids
string[] | null
required

The contacts lists the job has filled so far, in order, 10,000 people each. Empty when no list was asked for.

created_at
string<date-time>
required

When the job was created

job_id
string
required

The job's ID, to poll it, read its results or stop it

Example:

"b3c6f5e2-1234-4abc-9def-0123456789ab"

max_results
integer<int64>
required

The cap the job stops at. 0 while planning.

Example:

100000

plan
object[] | null
required

The searches the job was split into, in the order they run. Empty while planning.

saved_count
integer<int64>
required

How many distinct people the job has saved so far

Example:

12500

searches
integer<int64>
required

How many searches the job was split into. 1 for a search the source serves whole.

Example:

24

searches_failed
integer<int64>
required

How many of those failed after repeated retries. What they saved before failing is kept.

Example:

0

searches_finished
integer<int64>
required

How many of those have run to their end

Example:

10

status
enum<string>
required

planning while the search is split into searches the source can serve whole. planned once the plan is ready: a job started with the plan endpoint waits there until you run it, one started to run goes straight on. running while pages are collected. completed when every search ran to its end or max_results was reached. stopped when you stopped it. out_of_credits when the account ran out of credits. failed when it could not go on, see error. Whatever ends a job, what it saved is kept.

Available options:
planning,
planned,
running,
completed,
stopped,
out_of_credits,
failed
Example:

"running"

unreachable_count
integer<int64>
required

People the search matches that no split could bring within reach of the source, and that the job will therefore not collect. See the operation description.

Example:

0

error
string

Why a failed job stopped: planning_failed, search_failed or start_failed

Example:

"planning_failed"

finished_at
string<date-time>

When the job ended, whatever the reason

provider
string

The source the job was pinned to, when one was asked for

Example:

"endor"