Users

Provision a user

Idempotent on phone number: calling twice returns the same user rather than a duplicate. Mints nothing that can spend.

post/users

Request

  • Base URL: https://api.layout.link/v1
  • URL: https://api.layout.link/v1/users
  • Auth: HTTP bearer

Headers

Layout-Version'2026-10-01'

The API version you code against. Optional; without it you get 2026-10-01, the current version. Layout answers with the version it used.

Idempotency-Keystring

Optional. Any 1 to 255 visible ASCII characters, unique per real intent. A retry with the same key and the same body gets the stored response for 24 hours, with Idempotent-Replayed: true, and is never run twice. The same key with a different body is 409 idempotency_conflict; while the first request is still running it is 409 in_progress with Retry-After. Only a success is stored: any error releases the key so it can be sent again. A 4xx ran nothing. A 5xx may have run, above all a confirm's 500, so read the resource before sending anything changed.

Request body

firstNamestring required

Shown to the person on the consent screen.

lastNamestring required

Shown to the person on the consent screen.

phonestring required

E.164. The person verifies it themselves.

emailstring email

Optional and unverified. Kept with the provisioning link; never written to the person's own Layout account, never shown to another partner.

labelstring

Your own name for this person, shown in the console.

connectDelivery'developer'

For a number that already has a Layout account: return the consent link instead of Layout texting it.

Example request

{
  "phone": "+15005550142"
}

Response

Created, or the existing user for this phone number.

idstring required
statusstring required
next'verify' | 'connect' | 'awaiting_user_approval' | 'connected' required

The next step for this person. verify: a new number, prove it headlessly. connect: an existing Layout account and you asked to deliver the link; send its owner to connect.connectUrl. awaiting_user_approval: an existing account, and Layout texted the person the approval link. connected: already connected, start building.

handoffUrlstring uri required

Where the person claims the account and proves their phone.

Example response

{
  "id": "usr_4b8e9a01c2d3",
  "status": "provisioned",
  "session": {
    "expiresIn": 900
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.