---
title: "Text the person a verification code"
method: POST
path: "/users/{userId}/verify/start"
tags: ["Users"]
---

# Text the person a verification code

`POST /users/{userId}/verify/start`

## Request

- Base URL: `https://api.layout.link/v1`
- URL: `https://api.layout.link/v1/users/{userId}/verify/start`
- Auth: HTTP bearer

Sends a six-digit code to the number you provisioned, good for three minutes from this send and for five tries. The person reads it back to you. A new send replaces the last one. A person already connected to this application gets a fresh code too, so a returning person on a new device can be recognised; the code only proves they hold the phone and never signs them in to Layout.

## Path parameters

- `userId` string, required

## Headers

- `Layout-Version` '2026-10-01'
- `Idempotency-Key` string

## Response `200`

Code sent.

- VerifyStarted
  - `ok` true, required
  - `id` string, required
  - `phoneHint` string: The masked number the code went to.
  - `expiresInSec` integer
  - `sandbox` true: Sandbox texts nobody. The code is always 000000.

## Other responses

- `400`: `unsupported_version`: the Layout-Version header names no version this API answers.
- `401`: Secret not recognised, malformed, or rotated.
- `403`: Application not permitted. Usually production on an unapproved application.
- `404`: No such user for this application.
- `409`: `already_claimed`: this person claimed their own Layout account without connecting this application; get a consent link from POST /users/{userId}/connect. `phone_changed`: the person's Layout account no longer holds the number you provisioned; you stay connected under this id, and headless verify is unavailable until their account holds this number again. `texts_blocked`: the number replied STOP to Layout, so no code can be texted; the person replies START to the number Layout texts from, then you start again. `idempotency_conflict`: the Idempotency-Key was already used with a different request. `in_progress`: the first request with that key is still running; retry after `Retry-After`.
- `422`: This user has no usable phone number on file.
- `429`: A verification ceiling: a cooldown on this number, your developer account's hourly or daily text allowance, or Layout's hourly limit across every developer. The allowance and Layout's ceilings carry `error.limit`; an hourly one has `period: "hour"`.
- `500`: Layout failed to answer. Retry with backoff.
- `502`: The code could not be sent. Nothing was spent; retry.
- `503`: Layout or a dependency could not be reached. Retry with backoff.

---

[API](https://skmtc.dev/layout/apis/layout-partner-api.md) · [All operations](https://skmtc.dev/layout/apis/layout-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layout/apis/layout-partner-api/revisions/7ff4ba01bf56?raw)