---
title: "Replace a user's phone number"
method: PUT
path: "/users/{user_id}/phone_number"
tags: ["Phone Numbers"]
---

# Replace a user's phone number

`PUT /users/{user_id}/phone_number`

Replaces all of the user's phone numbers with a single primary phone number.
By default the new phone number is created verified, with the admin verification strategy.
When `identification_status` is `reserved` it is created reserved instead: unverified but usable
for sign-in and locked so no other user can claim it. When it is `unverified` the phone number is
neither usable for sign-in nor locked. The new phone number is never reserved for
second factor. Any existing phone numbers are deleted; replacing a phone number that is reserved
for second factor disables the user's MFA.

**Warning:** `identification_status: unverified` can lock the user out of their account. An
unverified phone number cannot be used to sign in, so if the user has no other verified or
reserved identifier, deleting their existing phone numbers leaves them unable to authenticate —
and unable to verify the new number, since that requires signing in. Recovery then requires
another admin API call.

## Path parameters

- `user_id` string, required

## Request body

- object
  - `phone_number` string, required — The new phone number. Must adhere to the E.164 standard for phone number format.
  - `identification_status` 'verified' | 'reserved' | 'unverified' — Controls the status of the replacement phone number. Defaults to `verified`. Set to `reserved` to create it reserved (unverified but usable for sign-in and locked so no other user can claim it), or to `unverified` to create it neither usable for sign-in nor locked. **Warning:** `unverified` can lock the user out of their account. An unverified phone number cannot be used to sign in, so if the user has no other verified or reserved identifier, they will be unable to authenticate and unable to verify this number. Prefer `reserved` unless you specifically need the number left unclaimed — for example so that another user can also hold it until one of them verifies it.

## 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)