---
title: "Register a phone number"
method: POST
path: "/api/v1/auth/register-number"
tags: ["authentication"]
---

# Register a phone number

`POST /api/v1/auth/register-number`

Sends a one-time code by SMS to the phone number that will own the new
account. Call this with the `registrationId` returned by
[Verify a sign-up code](#operation/verifySignup).

The number must be a valid phone number in E.164 form, and it must not
already be registered to another account — **a verified number is bound to
one account permanently.** A Dial number cannot be used to register a Dial
account.

Calling this again with the same number re-sends the code. Calling it with
a different number replaces the pending one, so a mistyped number is
recoverable until it is verified.

## Request body

- object
  - `registrationId` string, required — From the verify-sign-up response.
  - `phoneNumber` string, required — The owner's phone number, E.164 preferred.

## Response `200`

Code sent.

- AuthenticationRegisterNumberResponse200
  - `registrationId` string
  - `phoneNumber` string — The number in canonical E.164 form.
  - `status` 'pending'

## Other responses

- `400` — The request body failed validation.
- `409` — The request conflicts with the current state. During registration this means the registration is unknown or already complete, its email is not verified yet, no phone number has been registered against it, or the phone number is already registered to another account.
- `429` — Too many attempts. Wait before retrying. During registration this also covers the cap on verification codes sent to a single phone number.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/revisions/5f4eb30ac29a/schema)