# Headless phone verification

September 13, 2026 · API

You already gave us the person's number when you provisioned them, so there is no reason to make them type it again. Two new endpoints let them prove it from inside your product.

## The two calls

```bash
curl -X POST https://api.layout.link/v1/users/usr_4b8e/verify/start \
  -H "Authorization: Bearer $LAYOUT_SECRET"

200 OK
{ "ok": true, "id": "usr_4b8e", "phoneHint": "+1 (916) •••-0142", "expiresInSec": 180 }
```

```bash
curl -X POST https://api.layout.link/v1/users/usr_4b8e/verify \
  -H "Authorization: Bearer $LAYOUT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "code": "246810" }'

200 OK
{ "verified": true, "status": "active", "claimed": true }
```

- `start` texts a six-digit code, good for three minutes. The response carries only a masked hint of the number you already gave us.
- `verify` takes the code the person read back. A wrong code is a `401` and costs an attempt, so ask them for the current one and try again.
- Once the person is claimed, calling `verify` again answers `verified: true` without a fresh code. If the number belonged to an existing account, `claimed` is `false` and a repeat call needs a current code.
- An id that does not belong to your application, in this environment, is a `404`.

## What a good code does

Exactly what the person signing in themselves would have done. If the number is new to Layout, the account becomes theirs, `claimed` is `true`, and you are connected to them from then on.

If the number already belongs to someone's own Layout account, headless verify does not attach you to it. That only happens when the owner approves you; see [Connections that last](https://developer.layout.link/changelog/connections-that-last). Either way you never receive a session or anything about an account that already existed.

## Why it matters

Verification used to mean sending the person to a Layout page. Now it can be one field in your own onboarding, and the code still goes to their real handset, so possession of the phone is still proven.

## Breaking changes

None. The hosted link still works for anyone you would rather send there. See [Verify their phone](https://developer.layout.link/reference/provisioning#verify-their-phone).