Clerk

Clerk Phone Numbers API

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

Documentation GitHub OpenAPI

Business capability

Operations 11

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /phone_numbers Add a phone number to a user from the backend · Create a Phone Number #

Ask an LLM

“How do I attach a phone number to a user from my server?”

“Can I create a phone number that is already verified and primary for a user?”

Tell an agent

Add phone number {phone_number} to user {user_id} via the backend.

Create verified phone {phone_number} for user {user_id} and reserve it for second factor ({reserved_for_second_factor}).

GET /phone_numbers/{phone_number_id} Retrieve a phone number from the backend · Retrieve a Phone Number #

Ask an LLM

“How do I look up a phone number record by ID on the server?”

“Is a given phone number ID verified, according to the backend API?”

Tell an agent

Retrieve phone number {phone_number_id} with the backend API.

Look up phone record {phone_number_id} server-side.

DELETE /phone_numbers/{phone_number_id} Delete a user's phone number from the backend · Delete a Phone Number #

Ask an LLM

“How do I remove a phone number from any user using my secret key?”

“Can an admin delete a user's phone number server-side?”

Tell an agent destructive · confirm first

Delete phone number {phone_number_id} using the backend API.

As an admin, remove phone record {phone_number_id} from its user.

PATCH /phone_numbers/{phone_number_id} Update a phone number from the backend · Update a Phone Number #

Ask an LLM

“How do I mark a user's phone number as verified or primary from my server?”

“Can the backend change whether a phone number is reserved for second factor?”

Tell an agent

Mark phone number {phone_number_id} as verified ({verified}) via the backend.

Set backend phone number {phone_number_id} as primary ({primary}).

GET /v1/me/phone_numbers List the signed-in user's phone numbers · Get Phone Numbers #

Ask an LLM

“What phone numbers are on my own account?”

“How does the frontend list the current user's phone numbers?”

Tell an agent

List my phone numbers.

Show the phone numbers on my account for session {_clerk_session_id}.

POST /v1/me/phone_numbers Add a phone number to my account · Create Phone Number #

Ask an LLM

“How do I add a new phone number to my own profile?”

“Does a phone number I add myself need to be verified by SMS afterwards?”

Tell an agent

Add {phone_number} to my account.

Add {phone_number} to my profile for two-factor use ({reserved_for_second_factor}).

POST /v1/me/phone_numbers/{phone_number_id}/attempt_verification Verify my phone number with the SMS code · Attempt Phone Number Verification #

Ask an LLM

“How do I confirm my phone number with the code I got by text?”

“What do I send to finish phone number verification?”

Tell an agent

Verify my phone number {phone_number_id} with code {code}.

Finish verifying my phone {phone_number_id} using the texted code {code}.

POST /v1/me/phone_numbers/{phone_number_id}/prepare_verification Text a verification code to my phone · Prepare Phone Number Verification #

Ask an LLM

“How do I get an SMS verification code sent to a phone number I just added?”

“Can I resend the phone verification text?”

Tell an agent

Send a verification SMS to my phone number {phone_number_id} using strategy {strategy}.

Resend the SMS code for my phone {phone_number_id} with strategy {strategy}.

GET /v1/me/phone_numbers/{phone_number_id} Get one of my phone numbers · Retrieve Phone Number #

Ask an LLM

“How do I see the details of one phone number on my account?”

“Is my phone number marked as my default second factor?”

Tell an agent

Show my phone number {phone_number_id}.

Get the properties of my phone {phone_number_id}.

PATCH /v1/me/phone_numbers/{phone_number_id} Change settings on my phone number · Update Phone Number #

Ask an LLM

“How do I make one of my phone numbers my default second factor?”

“Can I stop using my phone number for two-step verification?”

Tell an agent

Make my phone number {phone_number_id} my default second factor ({default_second_factor}).

Set my phone {phone_number_id} reserved for second factor to {reserved_for_second_factor}.

DELETE /v1/me/phone_numbers/{phone_number_id} Remove a phone number from my account · Delete Phone Number #

Ask an LLM

“How do I delete a phone number from my own profile?”

“Can I remove an old phone number I no longer use from my account?”

Tell an agent destructive · confirm first

Remove phone number {phone_number_id} from my account.

Delete my old phone number {phone_number_id}.

Clerk Phone Numbers API

Operations 11

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification