Skip to navigation
Identity verification APIAddress

Retrieve the address stability attestation

Returns how well the address of the entity is established: the evidence tier of its captured pin, the latest presence check, how long the person has been at the current address and a stability grade. It answers address status only and never reports where anyone is. Read only, and not billed.

Error codes

errorStatusMeaning
entity_not_found404No live entity has this reference in this organisation and environment.
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.

Path parameters

externalUserIdstringRequired
Your own stable reference for the person or business, as sent when the entity was registered.

Response

Success
tierstring or null

The evidence tier of the captured pin, such as attested or corroborated, or null when no tier is held.

presenceobject or null

The most recent presence check, or null when none has been started.

tenureMonthsdouble or null

Months since the current address was first verified, or null when no address has been verified.

stabilityScoredouble or null0-1
A score from 0 to 1 blending tenure, repeat confirmations and recent moves.
stabilityGradeenum

The score as a grade. unknown means no address has been verified.

Allowed values:
moveCount24minteger
How many times the verified address changed in the last 24 months.
lastConfirmedAtdatetime or null
When the current address was last confirmed.

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
503
Service Unavailable Error