Clerk docs

Phone Numbers

A user can be associated with one or more phone numbers, which allows them to be contacted via SMS.

https://clerk.com/docs/reference/clerkjs/phonenumber

Create a phone number

Create a new phone number

SecuritybearerAuth
Request
Request Body schema: application/json
user_id
string

The ID representing the user

phone_number
string

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

verified
boolean or null

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

primary
boolean or null

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 or null

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.

Responses
200

Success

400

Request was not successful

401

Authentication invalid

403

Authorization invalid

404

Resource not found

422

Invalid request parameters

post/phone_numbers
Request samples
application/json
{
  • "user_id": "string",
  • "phone_number": "string",
  • "verified": true,
  • "primary": true,
  • "reserved_for_second_factor": true
}
Response samples
application/json
{
  • "id": "string",
  • "object": "phone_number",
  • "phone_number": "string",
  • "reserved_for_second_factor": true,
  • "default_second_factor": true,
  • "reserved": true,
  • "verification": {
    },
  • "linked_to": [
    ],
  • "backup_codes": [
    ],
  • "created_at": 0,
  • "updated_at": 0
}

Retrieve a phone number

Returns the details of a phone number

SecuritybearerAuth
Request
path Parameters
phone_number_id
required
string

The ID of the phone number to retrieve

Responses
200

Success

400

Request was not successful

401

Authentication invalid

403

Authorization invalid

404

Resource not found

get/phone_numbers/{phone_number_id}
Response samples
application/json
{
  • "id": "string",
  • "object": "phone_number",
  • "phone_number": "string",
  • "reserved_for_second_factor": true,
  • "default_second_factor": true,
  • "reserved": true,
  • "verification": {
    },
  • "linked_to": [
    ],
  • "backup_codes": [
    ],
  • "created_at": 0,
  • "updated_at": 0
}

Delete a phone number

Delete the phone number with the given ID

SecuritybearerAuth
Request
path Parameters
phone_number_id
required
string

The ID of the phone number to delete

Responses
200

Deleted Object

400

Request was not successful

401

Authentication invalid

403

Authorization invalid

404

Resource not found

delete/phone_numbers/{phone_number_id}
Response samples
application/json
{
  • "object": "string",
  • "id": "string",
  • "slug": "string",
  • "deleted": true
}

Update a phone number

Updates a phone number

SecuritybearerAuth
Request
path Parameters
phone_number_id
required
string

The ID of the phone number to update

Request Body schema: application/json
verified
boolean or null

The phone number will be marked as verified.

primary
boolean or null

Set this phone number as the primary phone number for the user.

reserved_for_second_factor
boolean or null

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.

Responses
200

Success

400

Request was not successful

401

Authentication invalid

403

Authorization invalid

404

Resource not found

patch/phone_numbers/{phone_number_id}
Request samples
application/json
{
  • "verified": true,
  • "primary": true,
  • "reserved_for_second_factor": true
}
Response samples
application/json
{
  • "id": "string",
  • "object": "phone_number",
  • "phone_number": "string",
  • "reserved_for_second_factor": true,
  • "default_second_factor": true,
  • "reserved": true,
  • "verification": {
    },
  • "linked_to": [
    ],
  • "backup_codes": [
    ],
  • "created_at": 0,
  • "updated_at": 0
}
➔ Next to Redirect URLs