Hosted flow

The hosted flow is a page we run and maintain that walks the user through every step of your flow. It handles camera permissions, capture quality, retries, localisation, right-to-left layouts and accessibility, so you write no front-end code at all.

The shape of the integration

Your backend creates a verification and receives hosted_verify_url. You send the user there. When they finish, they are returned to your return_url and TrustWix sends you the result by webhook.

const res = await fetch("https://api.trustwix.com/v1/verifications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRUSTWIX_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `kyc-${user.id}`,
  },
  body: JSON.stringify({
    flow: "flw_id_and_liveness",
    applicant: { reference_id: user.id },
    locale: user.locale,
    return_url: "https://your-app.example/kyc/done",
  }),
});

const verification = await res.json();
await db.users.update(user.id, { verificationId: verification.id });
// Redirect the user, or email them the link.
return Response.redirect(verification.hosted_verify_url);

The return URL is not the result

When the user lands back on return_url they have finished submitting, which is not the same as having been decided. Checks may still be running. Show a neutral "we are reviewing this" state and let the webhook drive the real transition.

Session lifetime

hosted_verify_url is valid until expires_at. If the user abandons the session and comes back after it expires, create a new verification rather than trying to revive the old one. The expired one stays in your history with status of expired.

Cross-device handoff

A user who starts on a desktop without a usable camera can continue on their phone. The hosted flow offers this itself and carries the same session across, so you do not need to create a second verification or coordinate anything. The verification id, and therefore your webhook handling, is unchanged.

Sending the link yourself

You do not have to redirect. hosted_verify_url is a normal URL, so you can email or message it, which suits back-office onboarding where the person being verified is not the person sitting at the screen. Pass applicant.email if you want TrustWix to be able to contact them about the session.

The address an email step verifies

Send applicant.email on the create call whenever you already hold one. A flow that carries an email step then verifies that address: the code goes out as soon as the applicant reaches the step, and they are not offered a box to type a different one. What you get back is a confirmation of the address registered on your side.

Leave it out and the step asks the applicant for an address and confirms whichever one they give, which is rarely the one their account uses. The choice is made per verification, not per flow, so the same flow can serve both a signed-in customer you already know and a first-time applicant you do not.