Clerk API (unofficial showcase)
PATCH/phone_numbers/{phone_number_id}

Update a phone number

Updates verification, primary-phone, or multi-factor authentication reservation settings for a phone number. Supply only the fields you want to change; reserving the number for multi-factor authentication requires it to be verified.

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

1 parameter · 3 body fields
phone_number_idstringrequired
The ID of the phone number to update.

Settings to update for the phone number; supply the fields you want to change.

verifiedbooleanoptional
The phone number will be marked as verified.
primarybooleanoptional
Set this phone number as the primary phone number for the user.
reserved_for_second_factorbooleanoptional
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.

5 status codes
200Returns the updated 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 the phone number is not found.
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; and a 404 when the phone number is not found. The phone_number_id path parameter must identify the phone number to update. reserved_for_second_factor requires the phone number to be verified.