individual_ref and, when a business is involved, business_ref.
Choose a verification path
Technical differences
Get the result
Hosted
- Wait for
OnboardingSession.completed, then read the results route. The webhook is a summary; the results are the source of truth. - Before the session completes, the results route answers
409. - A failed session sends
OnboardingSession.failed. A reviewer decision sendsOnboardingSession.updated. - Track sessions by
session_idorreference_id.
Direct
- Poll this route until
stateis terminal, or subscribe toVerification.completedandVerification.failed. Their payload is the verification exactly as this route returns it. - A reviewer decision sends
Verification.updated. - List your direct verifications with
GET /issuance/identities/verifications.
Use each identifier with its own routes: a
session_id on the session routes, a verification_id on the verification routes.States
A direct verification moves through these states:PENDING → EXECUTING → WAITING → COMPLETED
It may also end in FAILED or EXPIRED. A verification stopped internally reports FAILED.
Compatibility noteThe hosted session schema still lists
CANCELLED for compatibility, but a session stopped internally reads FAILED on GET /onboarding/sessions/{session_id} and in its webhooks too. You can treat both resources’ terminal states the same way.Verify someone again
Hosted
Start a new session.Direct
To re-verify an individual you verified directly, call this route with no body and a freshIdempotency-Key:
- It answers
202with a new direct verification. - The
individual_refnever changes. - A retry with the same key returns the same verification.
- A key already used for a different request answers
422. - A new key while a verification is still running answers
409with error code6202. - An individual with no stored verification to re-verify from answers
409with error code6203.
POST /issuance/identities/verifications starts a new verification from the details you send. To re-verify an existing individual_ref, use the route above.individual_ref.