Clerk API (unofficial showcase)
POST/phone_numbers

Create a phone number

Creates a phone number for a user. Provide user_id and an E.164-formatted phone_number; set verified to true before reserving the number for multi-factor authentication. A 200 response returns the created phone number and its verification, linkage, and reservation details.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

5 body fields

Phone number details to associate with a user.

user_idstringrequired
The ID representing the user
phone_numberstringrequired
The new phone number. Must adhere to the E.164 standard for phone number format.
verifiedbooleanoptional
When created, the phone number will be marked as verified.
primarybooleanoptional
Create this phone number as the primary phone number for the user. Default: false, unless it is the first phone number.
reserved_for_second_factorbooleanoptional
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.

6 status codes
200Returns the created phone number object, including its verification details, linked resources, reservation flags, timestamps, and any backup codes.
idstringoptional
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:phone_number
phone_numberstringrequired
reserved_for_second_factorbooleanoptional
default_second_factorbooleanoptional
reservedbooleanrequired
verificationobjectrequired
linked_toarray<object>required
backup_codesarray<string>optional
created_atintegerrequired
Unix timestamp of creation
updated_atintegerrequired
Unix timestamp of creation
400Returned when the request is unsuccessful.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Returned when authentication is invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Returned when authorization is invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Returned when a referenced resource is not found.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Returned when request parameters are invalid.
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned when the request is unsuccessful; a 401 when authentication is invalid; a 403 when authorization is invalid; a 404 when a referenced resource is not found; and a 422 when request parameters are invalid. user_id and phone_number are required, and phone_number must use E.164 format. reserved_for_second_factor requires the phone number to be verified.