Hosted verification links
Send a person a one-time link. They do the document, selfie and liveness check on a TrustVerify page; you get the result by webhook.
A hosted verification link lets a person verify their identity on a TrustVerify page. You never collect or store their ID images. Create a link from your server, send it to the person (email, SMS, in-app button), and receive the result on your webhook.
How it works#
- Your server calls
POST /api/v1/kyc/linkswith your API key. You get back a one-timeurlon trustverify.co.uk and anid. - The person opens the link on their phone or computer, photographs their ID document, then takes a selfie with a short liveness check (they turn their head when asked).
- The check runs: document read, face match against the document photo, the liveness check, and sanctions and PEP screening of the name.
- The decision is stored on the link and sent to your endpoints subscribed to
verification.completed, signed with your endpoint secret.
Opening the link does not use it up. Sending the photos does, once. A link expires after 72 hours unless you choose another time (15 minutes to 7 days).
Create a link#
curl https://api.trustverify.co.uk/api/v1/kyc/links \
-H "Authorization: Bearer $TRUSTVERIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalReference": "seller_123",
"fullName": "Jane Example",
"returnUrl": "https://yourmarketplace.example/onboarding/done",
"expiresInMinutes": 1440
}'| Field | Notes |
|---|---|
externalReference | Optional. Your id for the person, up to 200 characters. Echoed in the webhook. |
fullName | Optional. The name you expect on the document. If you leave it out, the person types it on the page. A mismatch sends the check to review. |
returnUrl | Optional HTTPS URL. The page shows a Return button to it when the photos are sent. |
expiresInMinutes | Optional. 15 to 10080. Default 4320 (72 hours). |
sandboxOutcome | Test keys only: approve, review or block. Default approve. |
{
"id": "hvl_3f9c0a6b1d2e4f5a6b7c8d9e",
"object": "verification_link",
"url": "https://trustverify.co.uk/verify/…",
"status": "pending",
"environment": "live",
"externalReference": "seller_123",
"expiresAt": "2026-11-15T10:00:00.000Z",
"result": null
}Note
The url is returned once, when the link is created. Store it if you need to resend it. Treat it like a password: anyone who has it can complete the check.
Get the result#
Subscribe an endpoint to verification.completed (see Webhooks). Hosted links send "source": "hosted_link". Verify the X-TrustVerify-Signature header before you act on it.
{
"event": "verification.completed",
"source": "hosted_link",
"type": "kyc",
"linkId": "hvl_3f9c0a6b1d2e4f5a6b7c8d9e",
"checkId": "KYC-1731578400000-ab12cd34e",
"externalReference": "seller_123",
"environment": "live",
"decision": "approve",
"status": "approved",
"score": 88,
"reasonCodes": [],
"completedAt": "2026-11-14T10:05:00.000Z"
}| decision | Meaning | What to do |
|---|---|---|
approve | Every check passed. | Let the person continue. |
review | Something needs a person to look: a name mismatch, a failed or skipped liveness check, an unreadable document. | Hold them until your team has reviewed the check in the dashboard. |
block | The name matched a sanctions list. | Do not onboard. Review the match in the dashboard. |
You can also poll GET /api/v1/kyc/links/{id}. status is pending, submitted (photos received, check running),completed, expired or cancelled. Cancel an unused link with POST /api/v1/kyc/links/{id}/cancel. The full check also appears in your dashboard under Checks.
Test keys#
A test key creates a test link. The page shows a test banner, stores no images and runs no check. The webhook arrives with the outcome you set insandboxOutcome and environment: "test", so you can build the whole flow before you go live.
Live keys#
A live link runs a real check on your account and counts as one identity check in your monthly allowance when the person sends their photos. Live links need a paid plan and your own account verification. If your allowance is used up, the link page tells the person it cannot be used right now, and nothing is charged.