Skip to navigation
Identity verification APIEntity Actions

Request a step-up re-verification

Creates a hosted re-verification link for an existing individual, typically after an alert or a flagged event. Deliver the url to your user yourself. When they complete it, the verification updates the same entity.

Only one challenge can be live per entity. A repeat call while one is pending returns that challenge with existing: true and status 200, so the call is safe to retry.

Side effects: a newly created challenge fires the entity.step_up_requested webhook, and its outcome fires entity.step_up_completed. The call is recorded in your audit log without the link. The re-verification is billed like any verification when the user completes it in production.

Error codes

errorStatusMeaning
invalid_request400The body failed validation. details carries the field-level breakdown.
entity_not_found404No live entity has this reference in this organisation and environment.
entity_not_individual422Step-up re-verification is available for individuals only.
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.

Request

This endpoint expects an object.
reasonstringOptional1-60 characters

Short context recorded on the challenge and sent on its webhook. Defaults to api.

Response

A live challenge already existed and is returned.
stepUpIdstring
The identifier of the challenge.
urlstringformat: "uri"

The hosted re-verification link to deliver to your user. Treat it as a credential.

statusenum

Always pending on this response. The outcome arrives on the entity.step_up_completed webhook.

Allowed values:
expiresAtdatetime
When the link stops working, three days after it was created.
existingboolean
True when a live challenge already existed and was returned instead of creating a second.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error