Skip to navigation
Identity verification APIAddress Triage

Grade a book of addresses

Submits up to 25,000 customer addresses for grading and returns straight away; the rows are graded in the background. Each row is graded corroborated, confirmable_in_app, needs_presence or unresolvable against the evidence already held for the customer. Poll the job to read the result.

The call is not idempotent: every request creates a new job, and in production a new charge.

Billing. In production the whole book is charged per row when the job is accepted, and the request is refused up front if the balance cannot cover it. Sandbox jobs are free. With preview: true only the first 250 rows are graded, nothing is charged in any environment, and quote states what the rest would cost.

Error codes

errorStatusMeaning
invalid_request400The body failed validation. details carries the field-level breakdown.
empty_book400The book has no usable rows.
insufficient_credits402The balance cannot cover the run. required, balance and currency are returned, and nothing was charged.
pricing_not_configured500No price is configured for address triage. Nothing was charged.
geocoder_unavailable503Address triage is temporarily unavailable. Nothing was charged.
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.
rowslist of objectsRequired
The rows of the book to grade.
countrystringOptional=2 characters

The default country for rows that carry none. When omitted, the country of your organisation is used, as an ISO 3166-1 alpha-2 code.

previewbooleanOptional
Set to true to grade only the first 250 rows free of charge and receive a quote for the rest.

Response

The job was accepted and is being graded.
jobIdstring
The identifier of the triage job.
statusenum

Always PROCESSING when the job is accepted.

Allowed values:
totalinteger
How many rows will be graded.
previewboolean
True when only a free sample is being graded.
quoteobject or null

For a sample, what grading the remaining rows would cost; otherwise null.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error