How an invite link works
Every applicant reaches their verification through an invite link. The link is single-use, scanner-safe, and bound to one verification.
What the link contains
Section titled “What the link contains”The applicant URL has two parts:
https://verify.<region>.<apex>/v/<short-code>?o=<otl-token><short-code>identifies the verification. Safe to log. Shown in QR codes.?o=<otl-token>authorizes the applicant. Treat the whole link as a secret and send it only to the applicant. Only the first human click consumes it.
The short code is created with the verification and never changes. The token in an emailed link is single-use, and every new link sent replaces it. The applicant can move to their phone through the QR code on the desktop step, or through a phone handoff from your app. The phone then gets its own short-lived single-use link. Continuing on another device never invalidates a link you emailed that the applicant has not opened yet.
Why links are single-use
Section titled “Why links are single-use”Resumable links let anyone with the URL re-open the verification. Two problems: email scanners that follow links land on the applicant’s verification, and a forwarded link can be opened by the wrong person. A single-use link cuts both off.
Scanner-safe consumption
Section titled “Scanner-safe consumption”The flow:
- The applicant clicks the link. Their browser hits
/v/<code>?o=<otl>on the verify app. - The resolver 302-redirects to a “Start verification” interstitial at
/start/<code>?o=<otl>. This redirect does not consume the token. - The interstitial validates the token via a read-only validation call and renders one button.
- Clicking the button POSTs a JSON consume request. Only this POST mints the journey cookie and marks the token consumed.
- Subsequent clicks on the original URL find a valid journey cookie and continue into the verification, with no re-consume.
GET-only crawlers never burn the link. A real applicant click is required, and replays are rejected. The validation gate first finds which link the token belongs to: the emailed link, or a phone handoff link. A phone handoff link comes from the QR code or your app. The gate then checks that link: already used, then expired, then OK. A token that belongs to neither is a mismatch. Every outcome other than OK lands on the same /expired page. The exception is a device that is already in this verification while its journey link is valid: it continues.
What the applicant sees
Section titled “What the applicant sees”For the full walk-through, see What the applicant sees. The invite-link hop:
- The interstitial shows your organization name and a “Start verification” button.
- Tapping the button transitions into the journey shell.
- If the applicant closes the tab and reopens the link while the journey link is valid, the journey cookie authorizes them without a re-consume. If they reload the journey page after the journey link has lapsed, the verify app renews the link in place without sending an email. This works until the verification’s deadline, as long as the workflow lets applicants request a fresh link. Reopening the original link after it has lapsed opens
/expiredinstead, where they can confirm their email to get a fresh link.
When a link is rejected
Section titled “When a link is rejected”The verify app routes every failure to the branded /expired page. A device already in that verification with a valid journey link continues instead. There are no distinct messages, no oracle for scanners. The failure classes:
- Consumed. The token has already been spent. The platform logs
kyc.applicant_link.replay_rejected. - Expired. An emailed token, or the token in a link returned by
regenerate_link, is valid for 72 hours from issue by default, and never longer than the journey link. A phone handoff link lasts at most 15 minutes. See How long links last. - Mismatch. The
?o=value does not match the verification. - Missing token. The applicant landed on
/v/<code>without?o=. - Unknown code. The short code does not resolve in this region. See Data residency.
How long links last
Section titled “How long links last”Two lifetimes apply. Both are workflow template settings under settings.lifecycle, set in the workflow template editor’s Applicant links card or through the workflow templates API:
- Invite token (
oneTimeTokenExpiresInHours, default 72 hours, from 1 to 384): how long the single-use?o=token in an invite, or in a link returned byregenerate_link, stays usable. It never outlasts the journey link below. - Journey link (
applicantLinkExpiresInHours, default 168 hours, which is 7 days). It sets how long the applicant can keep working through the journey cookie after a link is issued or reissued. A value above 384, which is 16 days, counts as 384. When the applicant reloads the journey page on the same device, the verify app renews a lapsed journey link in place, without an email. This works until the verification’s deadline, as long as the workflow lets applicants request a fresh link.
Every new link renews both lifetimes, up to the verification’s own deadline. This applies whether you send it, a reminder sends it, or the applicant requests it from /expired. Sending a new link never moves that deadline. Only Request new identity verification on the applicant’s detail page can set a later one, because it starts a new identity verification run. For a verification from a reservation in a connected system, the deadline is never set later than the reservation’s due time. A change to the reservation can move it earlier. Once a verification has been canceled, or has reached its deadline before it finished, no link opens it. A new one cannot be sent then, so start a new verification for the applicant. For a verification from a reservation in a connected system, the console shows that reservation’s next step instead. A finished verification (Completed or Awaiting review) that ran identity verification can be reopened with Request new identity verification. This issues the applicant a new link. The workflow template’s link lifetime and return window set that deadline. See Set how long links last for how far it can reach.
Request new identity verification works until 180 days after the verification was created. After that, start a new verification for the applicant. For a verification from a reservation in a connected system, the console shows that reservation’s next step instead.
Issue a new link
Section titled “Issue a new link”If the applicant’s detail page says the link was already used or has expired, click Generate new link there. The endpoint mints a fresh token on the same verification record, invalidates the previous one, and audits the action. The previous link no longer opens the verification. While the page shows the link to copy, it has no Generate new link.
Your integration can get a new link through the API instead, with no email on file. See Get a new link by API.
The applicant can also self-service from /expired. They confirm their email and receive a fresh link without operator involvement, even when their original link has expired. This works while the verification is still open, meaning it is not finished or canceled and has not passed its deadline. If the workflow turns self-service links off, the applicant asks you for a new link instead.
No link goes out in these cases:
- The verification is finished.
- The verification has passed its deadline.
- The verification is paused because your account balance cannot pay for its next check.
- The applicant joined through a shared link.
- The link is not known.
- The email does not match, or no email is on file.
- The workflow does not let applicants request a fresh link.
On a link they clicked, the page shows the same message in every one of these cases, so it never reveals which case applied. Two other messages exist. After too many requests, the page asks the applicant to wait a few minutes. If a request does not go through, the page asks the applicant to try again.
If no new link reaches the applicant, for example because no email is on file, the page tells them to ask the organization that sent the link. While the verification is open, open the applicant’s detail page. Copy the link it shows. If the page says the link was already used or has expired, click Generate new link. You can also use the API as described below.
Get a new link by API
Section titled “Get a new link by API”To give an applicant a new link without an email, call POST /v1/sessions/{id}/regenerate_link. The key needs the sessions:write scope. No email is sent, and none needs to be on file. You deliver the link to the applicant over your own channel.
curl -X POST https://api-dev.us.autohost-dev.uk/v1/sessions/vs_01H.../regenerate_link \ -H "Authorization: Bearer ah_sk_us_live_<your-key>" \ -H "Content-Type: application/json"A successful call answers 200:
{ "data": { "ok": true, "action": "regenerate_link", "session_id": "vs_01H...", "applicant_url": "https://verify.<region>.<apex>/v/<short-code>?x=<token>", "applicant_link_expires_at": "2026-11-16T12:00:00.000Z", "one_time_token_expires_at": "2026-11-12T12:00:00.000Z" }}applicant_urlis the new single-use link. It opens the verification once.one_time_token_expires_atis when an unusedapplicant_urlstops opening the verification. It is never later thanapplicant_link_expires_at.applicant_link_expires_atis when the applicant’s journey link expires. The call renews it for the workflow’s journey link lifetime from now, but never past the verification’s deadline (expires_at).
Each call issues a new link. The link issued before it stops working. An applicant who is already in the verification keeps working and stays signed in. The call keeps the client_token, so the embedded SDK keeps working too.
A link also stops working when any newer link is issued for the verification. That can be a later regenerate_link call, a resend, a reset, an invite or reminder that sends a new link, Generate new link, or a link the applicant requests. So make the call close to when the applicant will act, and deliver the URL from the latest response. The Idempotency-Key header is not honored here: a retry issues another new link, never an earlier one.
The new link is usable for the workflow’s invite token lifetime (oneTimeTokenExpiresInHours), and never longer than the journey link. To give applicants more time, raise it in the workflow template, and raise the journey link with it. A lifetime change applies to verifications started after the change: each verification keeps the lifetimes it was created with. See How long links last.
This call never moves expires_at, the verification’s deadline. A call after the deadline is refused with 409.
Send an empty body or {}. Any field, such as revoke_previous_link, is refused with 422 validation_error. POST /v1/sessions/{id}/resend ignores a field it does not know. A body that is not JSON, or not a JSON object, is refused with 422 validation_error too. A request without Content-Type: application/json is refused with 415 unsupported_media_type, even with an empty body.
When no working link can be issued, the call is refused with 409 and nothing changes. The message names the next step where there is one:
group_link_no_reinvite: the applicant joined through a shared link. Ask them to open the shared link again.session_already_completed, withdetails.status, in three cases:- The verification belongs to a reservation from a connected system and can no longer be finished, for example because the reservation’s due time has passed. Open the applicant’s detail page in the console for the reservation’s next step.
- The verification is paused on funds (
payment_required). Add funds in Billing, and it resumes automatically. See Payment required for the one paused verification that does not resume. - The verification can no longer be finished: it is past its deadline, or past the window that a new link can reach. Create a new verification for the applicant. For a verification from a reservation, follow the reservation’s next step instead.
session_finished: the verification is finished (completed,awaiting_revieworprocessing), so there is nothing to deliver. Or it isexpiredorcancelled: create a new verification for the applicant, or for a verification from a reservation, follow the reservation’s next step.
For terminology, see the Glossary.