Skip to navigation
Identity verification APIEntities

Import entities in bulk

Accepts between 1 and 1,000 entities and returns straight away. The whole submission is stored before the response is sent, and each item is then registered in the background, so nothing is lost if processing is interrupted. Poll the job to follow progress.

Each item is the idempotent upsert of a single registration, so sending the same book again updates the same entities. The request itself is not deduplicated: every call creates a new job. The whole array is validated first, and one invalid item rejects the request.

Side effects: entity.imported fires for each entity the job creates, and each entity is enrolled in screening as on a single registration. The submission is recorded in your audit log without the individual references.

Error codes

errorStatusMeaning
invalid_request400The body failed validation, or the array is empty or longer than 1,000 items.
secret_key_required403A publishable key was used. This API accepts secret keys only.
environment_mismatch403The key belongs to an environment this host does not serve.
rate_limited429The request rate limit for this key was reached. Retry after a short wait.
rate_limit_store_unavailable503Rate limiting is temporarily unavailable. Retry shortly.

A missing or unknown key returns 401 with a plain sentence in error rather than a code.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Request

This endpoint expects an object.
entitieslist of objectsRequired
The entities to register. Each item has the same shape and behaviour as a single registration.

Response

The import was accepted and is being processed.
jobIdstring
The identifier of the import job.
statusenum

Always PROCESSING when the job is accepted.

Allowed values:
totalinteger
How many entities the job holds.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
503
Service Unavailable Error