# Check a link

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

`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

```bash
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](#ask-for-details) and [Ask for recent proof](#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](#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.

```bash
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](#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.