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:
- 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.
- 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).