An assistant is helping your team onboard a new business user, and someone pastes a passport photo into the chat to speed things up. That puts an identity document in a transcript that no verification flow controls. The decision is how to start verification so the person submits documents and liveness only on a hosted page, while your application reads back three things: a hosted URL, a task state and an authoritative completion status. This article covers the inputs, a hypothetical scenario, the exact synthetic fixture output, failure handling and an acceptance checklist. It separates what the product contract states from the application design we propose.
The problem: documents in the wrong channel
When identity onboarding runs through an AI assistant, the easiest path is often the worst one: asking the user to upload an ID card or selfie directly into the conversation. Chat transcripts are stored, shared and reviewed in ways a verification flow does not control. The alternative is a hosted journey. Your service, or the assistant acting for it, asks for a verification link; the person opens it and completes the identity and liveness steps there. The assistant never sees a document or a face. Your decision is not which camera widget to build, but which few values your application sends and which values it trusts when it reads the result back. Getting that boundary right early keeps sensitive images out of logs, prompts and support tickets.
What the product contract states
According to the reviewed product contract, the hosted identity task takes three inputs: a subject authorization reference, a stable request UUID and an explicit trial or paid mode. No document or face belongs in the assistant chat. The output is a hosted URL, a task state and an authoritative completion status. The listed tools are production_capabilities, start_identity_onboarding, get_production_verification and refresh_production_verification. Two statements matter most. First, the person, not the assistant, completes identity and liveness steps. Second, Approved does not grant application permissions; your own rules decide what an approved person may do. The contract also records limits: acceptance of a new person passing the full hosted journey remains pending, and online purchases require payment-channel acceptance. Merchant execution requires current capabilities, authorization and an accepted quote. Documentation is not evidence of a live check.
A hypothetical scenario and the expected fixture output
Hypothetical: a small SaaS team adds a seller. Its onboarding service records the seller's authorization reference, generates one request UUID and stores it before any call, and selects trial mode explicitly. It then asks to start the hosted journey. In the supplied synthetic contract example, no live provider request is performed, and the expected fixture output is exactly: status pending, hosted_url null, verified false, automatic_business_approval false. Read each field literally. status pending means the task exists but no result is final. hosted_url null means there is no link to show the person yet, so the interface must not render a broken button or invent one. verified false is not a rejection; it only says verification has not completed. automatic_business_approval false confirms that even a later approval will not switch on seller access by itself. This is a synthetic contract illustration, not live acceptance, and the fixture's permission to run is not business permission.
Proposed application design
The following is our proposed design, not implemented product behavior. Persist the request UUID with the subject reference before starting, so a retry reuses the same request instead of creating a second journey. Store the task state as pending with a local deadline. Show the hosted URL to the person only when the task returns a non-null value, and send it through your own interface, never by asking for images in chat. When the person finishes, read the authoritative completion status with get_production_verification rather than trusting a browser redirect or a message from the assistant. Keep a separate business decision step: an authoritative Approved becomes one input to your seller policy, which checks tenant, user and the action requested. Log the UUID, state and status, never document content.
Failure handling
Plan for each non-happy path explicitly. If hosted_url stays null, keep the task pending and tell the person the link is not ready; do not create a new request with a fresh UUID. If a callback never arrives, the local recovery pattern from the earlier examples expires the pending task at its deadline; it does not poll a provider, so a refresh against the original task is a deliberate, authorized step. Fixture events accept only synthetic callbacks, not real signatures, so a passing fixture says nothing about signature verification in production. If the status is Declined or incomplete, record it and route to human review instead of retrying silently. If someone posts a document in chat anyway, do not forward it; point them to the hosted link. If mode is missing, refuse to start rather than guessing trial or paid.
Acceptance checklist
Before calling this integration ready for a pilot, confirm: the request carries a subject authorization reference, a stored request UUID and an explicit mode; no document or face image appears in any prompt, transcript or log; the fixture returns status pending, hosted_url null, verified false and automatic_business_approval false; the interface handles a null hosted_url without a dead link; retries reuse the same UUID; completion is read from the authoritative status, not from a redirect; Approved passes through your own permission rules and never grants access directly; recovery expires locally with no provider polling; and the team record notes that full new-person approval acceptance is still pending and that purchases depend on payment-channel acceptance. A passing checklist shows your handling is sound, not that a live check has occurred.
Disclosure: this tutorial was drafted with AI and checked against executable local examples and an independent factual review. Sample values are test inputs, not verified people or accounts. Application policy remains the caller’s responsibility.
Top comments (0)