Headless phone verification

September 13, 2026API

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

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 }

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. 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.

All changes