---
title: "Update a phone number"
method: PATCH
path: "/phone_numbers/{phone_number_id}"
tags: ["Phone Numbers"]
---

# Update a phone number

`PATCH /phone_numbers/{phone_number_id}`

Updates a phone number

## Path parameters

- `phone_number_id` string, required

## Request body

- object
  - `verified` boolean, nullable — The phone number will be marked as verified.
  - `primary` boolean, nullable — Set this phone number as the primary phone number for the user.
  - `reserved_for_second_factor` boolean, nullable — Set 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

---

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