Skip to content
Check Twice

Check a link

Find out who made a Check Twice link, checked against their photo ID.

Last updated: 

POST /v1/links/check

Someone makes a link in the Check Twice app after proving who they are with their photo ID and a quick photo, then gives it to you. Check it from your server with an API key and you get back who made it.

Keys

Sign up on check-twice.com to create a workspace, then create API keys in your workspace. Send one with every request:

HTTP
Authorization: Bearer ctk_…

You see a key once, when it’s made. Keep it on your server, in an environment variable, never in a browser or an app: the API refuses requests from web pages on other sites. If a key is ever exposed, delete it and make another.

Request

Terminal
curl https://api.check-twice.com/v1/links/check \  -H "Authorization: Bearer $CHECK_TWICE_KEY" \  -H "Content-Type: application/json" \  -d '{"link": "https://www.check-twice.com/l#5wH2kQ…"}'
  • link: the link as you got it. The whole link, its token alone or the app’s checktwice://link?token=… all work.
  • require: optional, what the link must show and how recently they must have proved it’s them. See Ask for details and Ask for recent proof.

Every check counts as an open of the link. Its maker sees when it was opened and whether by a person or a system, but never who.

Response

JSON
{  "name": "Olivia B.",  "document_kind": "passport",  "chip_verified": true,  "on_check_twice_since": "2026-09-28T10:02:17Z",  "last_live_at": "2026-10-10T08:26:05Z",  "notes": "Confirming I’m the one buying your car.",  "face_photo_url": null,  "number": null,  "number_since": null,  "person": "Vb3kPq9xT2mWc7Ld4Hs8aE",  "impersonation_warning": false,  "for_you": false,  "yours": false,  "by_agent": false,  "approved_at": "2026-10-10T16:23:41Z",  "created_at": "2026-10-10T16:23:41Z"}
  • name: their first name and the first letter of their last name, from their photo ID, or their full name if they chose to show it.
  • document_kind: the ID they used, passport, identity_card or driving_licence.
  • chip_verified: true if the ID’s chip was read and its issuer’s signature checked, false if it was checked from photos of it.
  • on_check_twice_since: when they proved who they are with their ID.
  • last_live_at: when they last took a quick photo to prove it’s them.
  • notes: what the link is for, in their words, or null. Check Twice checked who made it, never what it says.
  • face_photo_url: the URL of their face photo, if they chose to show it on this link. See Face photo.
  • number and number_since: the phone number they chose to show, with its country code, and since when it has been theirs.
  • person: a code for who made the link. Their links always give you the same one, and anyone else checking gets a different one.
  • impersonation_warning: true if they’ve warned that someone is pretending to be them.
  • for_you and yours: whether it was made for your phone number, and whether you made it.
  • by_agent and approved_at: whether their AI agent asked for it, and when they approved it on their phone.
  • created_at: when it was made.

Use what a check returns only to verify who made the link. Never store, copy or share it.

Face photo

Get the photo from face_photo_url with the same key within five minutes of the check. It’s a JPEG.

Terminal
curl https://api.check-twice.com/v1/links/photos/qX8wR2… \  -H "Authorization: Bearer $CHECK_TWICE_KEY" \  -o face.jpg

Ask for details

Add require to accept a link only if it shows what you need:

JSON
{  "link": "https://www.check-twice.com/l#5wH2kQ…",  "require": {    "full_name": true,    "face_photo": true,    "chip_verified": true  }}
  • full_name: their full name, not just their first name and the first letter of their last name.
  • face_photo: their face photo.
  • chip_verified: an ID whose chip was read and its issuer’s signature checked.

Ask for recent proof

Add proved_within_seconds to require to accept someone only if they took a quick photo within that many seconds, like 3600 for an hour or 86400 for a day:

JSON
{  "link": "https://www.check-twice.com/l#5wH2kQ…",  "require": {    "proved_within_seconds": 86400  }}

It can sit in the same require as the details you ask for.

When a link falls short

A link that doesn’t meet everything in require is refused, and unmet lists what it didn’t:

JSON
{  "error": "requirements_not_met",  "unmet": ["face_photo", "proved_within_seconds"]}

Errors

An error comes back with its code, such as {"error": "link_not_valid"}.

  • 401 unauthorised: the key is missing, wrong or no longer works.
  • 403 link_for_someone_else: the link was made for someone else’s phone number.
  • 404 link_not_valid: the link was deleted or never existed. Ask them for a new one.
  • 422 requirements_not_met: the link doesn’t meet everything in require. See When a link falls short.
  • 429 rate_limited: you’ve reached the day’s limit. Retry-After says how many seconds until you can check again.

Limits

Checking links is free. Each Check Twice account can open or check 500 links a day, in the app and with its keys together.

Testing

Make a link in the Check Twice app and check it with your own key. Its yours is true, and your checks don’t count as opens.