Skip to main content
Baselayer verifies an identity in one of two ways. Each has its own routes, its own webhooks and its own identifier, and nothing mixes the two. Both end in the same pairwise references: 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 sends OnboardingSession.updated.
  • Track sessions by session_id or reference_id.

Direct

  • Poll this route until state is terminal, or subscribe to Verification.completed and Verification.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 fresh Idempotency-Key:
See the API reference.
  • It answers 202 with a new direct verification.
  • The individual_ref never 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 409 with error code 6202.
  • An individual with no stored verification to re-verify from answers 409 with error code 6203.
POST /issuance/identities/verifications starts a new verification from the details you send. To re-verify an existing individual_ref, use the route above.
Next: Mint a credential with the individual_ref.