OZozav
Verifications

Start a verification session for a customer

Starts one or more verification checks (hosted session when the check requires end-user interaction). Check kinds are the canonical OZAV capability taxonomy.

Verification records persist and can be listed with GET /verifications. Hosted session_url issuance is gated by your organization's capabilities and may be absent.

Without hosted capture (it is off at OZAV), asking a hosted check for an individual does not return an error: the verification answers in_progress, the hosted checks stay at review (never pass), there is no session_url, and pending_documents lists the documents to send with POST /customers/{customer_id}/documents (identity_document, selfie, proof_of_address). The field appears only on this response.

Sandbox: a test key (ozav_sk_test_) never receives a session_url and never starts a real identity check - a sandbox verification has no real end-user to redirect. Create the verification, then drive it to its end state with POST /verifications/{id}/simulate.

Reliance: for a customer created with verification_mode: reliance (your organization has the kyc_reliance product), your organization already identified the end user, so OZAV does not start a hosted identity, liveness or business verification session. Asking for any hosted check (kyc_document, liveness, face_match, age_estimation, kyb, ubo) answers 409 VERIFICATION_NOT_REQUIRED_UNDER_RELIANCE, in sandbox and live alike, and nothing is created or charged. Send the customer data and the identity document images with POST /customers/{customer_id}/documents instead; OZAV screens the customer and decides on its own. Checks OZAV runs itself (aml_name_screening, economic_capacity) can still be requested here.

post/verifications

Request

  • Base URL
    https://developers.ozav.io/v2
  • Auth
    • API key in header X-API-Key
    • or HTTP bearer

Request body

customer_idstring required

The ozav_cus_ id of the customer to verify.

capabilitiesCapabilityKind[] required

The checks to run, from the canonical capability taxonomy (see CapabilityKind).

redirect_urlstring uri

Where to return the end-user after a hosted verification session, when one is used.

Response

Verification session.

idstring required

Opaque verification identifier, prefixed ozav_vrf_.

object'verification' required

Resource type discriminator; always the literal verification.

customer_idstring required

The ozav_cus_ id of the customer being verified.

session_urlstring uri

Hosted verification session URL - redirect the end-user here to complete identity capture (government ID, selfie, liveness; KYB/UBO for a business customer).

In sandbox this field never appears. A test key never starts a hosted session, because a real session bills a third party per attempt. Exercise the outcome with POST /verifications/{verification_id}/simulate instead - that is the sandbox affordance, and it lets you drive approved or rejected yourself.

With a live key, two things must both be true, and the second is not something you control:

  1. Your capabilities include at least one that hosted capture covers: kyc_document, liveness, face_match, age_estimation, kyb, ubo. Asking only for list/data checks (aml_name_screening, economic_capacity, ...) never starts a session, because there is nothing for the end-user to do.
  2. Hosted capture is switched on at OZAV. This is a single platform-wide setting, not something enabled per organization - there is nothing to request for your account. While it is off, no live key starts a session.

When either condition is missing - or the key is a test key - the verification is still created and is a valid record with no session_url. That is not an error and retrying will not produce one. For an individual on a live key with hosted capture off, it is in_progress with the hosted checks at review and pending_documents saying what to upload instead; otherwise it stays pending with checks at not_started.

The field is never fabricated: if the session cannot be created, the request fails with a 503 and nothing is persisted, rather than returning a record with a broken link. The code says whether retrying helps: VERIFICATION_SESSION_UNAVAILABLE (retry shortly), VERIFICATION_TEMPORARILY_UNAVAILABLE (on OZAV's side, not caused by your data - retry later with the same data), VERIFICATION_PROVIDER_REJECTED or VERIFICATION_PROVIDER_NOT_CONFIGURED (contact OZAV support with the request_id).

status'pending' | 'in_progress' | 'completed' | 'expired' required

Overall state of the verification session:

  • pending - created; checks have not started.
  • in_progress - one or more checks are running.
  • completed - every check reached an outcome.
  • expired - the session expired before completing.
checksobject

Per-capability check results, keyed by CapabilityKind.

created_atstring date-time

When the verification session was created (RFC 3339 / ISO 8601, UTC).

Changes

No recorded changes to this operation across all 1 revision of this API.