Skip to main content
POST
Enrich people in a batch

Authorizations

Authorization
string
header
required

An API key from the console, starting ob_live_, sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string

Names this operation, so a retry with the same key and body gets the first success again, marked Idempotent-Replayed, instead of running or charging twice. A mailbox's password is not compared: the same mailbox sent again with another password is the same call, and gets the first answer. Kept 24 hours for your organization and this route. A refusal (4xx) frees the key at once, so a corrected retry runs. After a server error (5xx), which may still take effect, the key stays held for 5 minutes from the call's start, and a retry in that time answers 409 idempotency_in_progress; after that, a send or import that may already have gone out answers 409 idempotency_outcome_unknown instead of running again. 1 to 255 visible ASCII characters, such as a UUID.

Required string length: 1 - 255
Pattern: ^[\x21-\x7E]+$

Body

application/json
people
object[]
required

The people to enrich, 1 to 100, each named one way, as POST /v1/people/enrich takes a person.

Required array length: 1 - 100 elements
find
enum<string>
default:email

What to find: a work email (the default), a phone number, or both (email_and_phone).

Available options:
email,
phone,
email_and_phone
providers
enum<string>
default:package

Where to look: package (the default) searches our own data package; waterfall searches the package, then a fixed series of further providers. A value's price depends on who found it.

Available options:
package,
waterfall
maxSpendUsd
number

The most the job may cost, in US dollars. A job that could cost more is refused before anything is held or started.

Required range: 0.01 <= x <= 1000000

Response

The job, started. Read its progress and result with GET /v1/jobs/{jobId}.

id
string
required
type
enum<string>
required

What the job does.

Available options:
email_verification,
people_enrichment,
list_enrichment
status
enum<string>
required

running until the job ends as succeeded, failed or cancelled.

Available options:
running,
succeeded,
failed,
cancelled
units
object[]
required

What the job produced so far, by price item.

createdAt
string<date-time>
required
listId
string

For a list enrichment, the list it runs over. What it finds is saved on the list's rows: read them with GET /v1/lists/{listId}/rows.

find
enum<string>

For an enrichment, what it looks for.

Available options:
email,
phone,
email_and_phone
providers
enum<string>

For an enrichment, where it looks.

Available options:
package,
waterfall
progress
object

How far the job got. Absent until it reports progress.

chargedUsd
string

What the job was charged, in US dollars as an exact six-decimal string. Present once it ended.

results
object[]

For a people enrichment, once it ended: every person's result, in the order the request named them. Shown to keys that can read enrichment.

finishedAt
string<date-time>

When the job ended. Absent while it runs.