---
title: "Create a phone number"
method: POST
path: "/phone_numbers"
tags: ["Phone Numbers"]
---

# Create a phone number

`POST /phone_numbers`

Create a new phone number

## Request body

- object
  - `user_id` string, required — The ID representing the user
  - `phone_number` string, required — The new phone number. Must adhere to the E.164 standard for phone number format.
  - `verified` boolean, nullable — When created, the phone number will be marked as verified.
  - `primary` boolean, nullable — Create this phone number as the primary phone number for the user. Default: false, unless it is the first phone number.
  - `reserved_for_second_factor` boolean, nullable — Create this phone number as reserved for multi-factor authentication. The phone number must also be verified. If there are no other reserved second factors, the phone number will be set as the default second factor.

## Response `200`

Success

- PhoneNumber
  - `id` string
  - `object` 'phone_number', required — String representing the object's type. Objects of the same type share the same value.
  - `phone_number` string, required
  - `reserved_for_second_factor` boolean
  - `default_second_factor` boolean
  - `reserved` boolean, required
  - `verification` union, required
    - object
      - `object` 'verification_otp'
      - `status` 'unverified' | 'verified' | 'failed' | 'expired', required
      - `strategy` 'phone_code' | 'email_code' | 'reset_password_email_code', required
      - `attempts` integer, nullable, required
      - `expire_at` integer, nullable, required
      - `channel` string, nullable — The delivery channel of the code (phone codes only).
      - `verified_at_client` string, nullable
    - object
      - `object` 'verification_admin'
      - `status` 'verified', required
      - `strategy` 'admin', required
      - `attempts` integer, nullable, required
      - `expire_at` integer, nullable, required
      - `verified_at_client` string, nullable
  - `linked_to` IdentificationLink[], required
    - `type` string, required
    - `id` string, required
  - `backup_codes` string[], nullable
  - `created_at` integer, required — Unix timestamp of creation
  - `updated_at` integer, required — Unix timestamp of creation

## Other responses

- `400` — Request was not successful
- `401` — Authentication invalid
- `403` — Authorization invalid
- `404` — Resource not found
- `422` — Invalid request parameters

---

[API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/versions/cf036e7951d3/schema)