Phone Numbers

Create a phone number

Changed on

Create a new phone number

post/phone_numbers

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/phone_numbers
  • Auth: HTTP bearer

Request body

user_idstring required

The ID representing the user

phone_numberstring required

The new phone number. Must adhere to the E.164 standard for phone number format.

verifiedboolean nullable

When created, the phone number will be marked as verified.

primaryboolean 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_factorboolean 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

Success

idstring
object'phone_number' required

String representing the object's type. Objects of the same type share the same value.

phone_numberstring required
reserved_for_second_factorboolean
default_second_factorboolean
reservedboolean required
backup_codesstring[] nullable
created_atinteger required

Unix timestamp of creation

updated_atinteger required

Unix timestamp of creation

Changes

  • 2025-11-104db0b9e2d5e6Revision changes
    • info

      added the optional property ///// to the response with the status