---
title: "Submit the code the person read back"
method: POST
path: "/users/{userId}/verify"
tags: ["Users"]
---

# Submit the code the person read back

`POST /users/{userId}/verify`

## Request

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

Checks the code against the last one Layout texted for this person and answers their per-application `id`. Returns no session. For a person already connected, a right code answers the same `id` as before and changes nothing; call verify/start first to text them one. Sent with no code, a person already verified answers `verified: true` without a check, so only an answer to a request that carried a code proves the person holds the phone. Read `authorized` before building.

## Path parameters

- `userId` string, required

## Headers

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

## Request body

- VerifyRequest
  - `code` string, required: The six-digit code the person read back.

## Response `200`

Verified.

- Verified
  - `id` string, required
  - `verified` true, required: The code was right. It says nothing about whether this application may build; read `authorized`.
  - `authorized` boolean, required: True when this application may now build for this person. False when the number belongs to an existing Layout account, which only its owner can connect.
  - `next` 'connect': Present when `authorized` is false: get a consent link from POST /users/{userId}/connect.
  - `status` 'active' | 'provisioned'
  - `claimed` boolean: True when a new Layout account was claimed onto this person.

## Other responses

- `400`: `invalid_request`: a six-digit code is required. `code_expired`: no code was texted for this person in the last three minutes, or the last one took five wrong tries; text a new one with verify/start. `unsupported_version`: the Layout-Version header names no version this API answers.
- `401`: `bad_code`: the code is not the one Layout texted; ask the person for the current one. Each try counts toward the five a text allows. `unauthorized`: the secret was not recognised.
- `403`: Application not permitted. Usually production on an unapproved application.
- `404`: No such user for this application.
- `409`: `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, or, in sandbox, no reserved test number.
- `429`: Too many attempts for this number.
- `500`: Layout failed to answer. Retry with backoff.
- `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)