Clerk API (unofficial showcase)
PUT/users/{user_id}/phone_number

Replace a user's phone number

Replaces all of the user's phone numbers with a single primary phone number. By default the new phone number is created verified, with the admin verification strategy. When identification_status is reserved it is created reserved instead: unverified but usable for sign-in and locked so no other user can claim it. When it is unverified the phone number is neither usable for sign-in nor locked. The new phone number is never reserved for second factor. Any existing phone numbers are deleted; replacing a phone number that is reserved for second factor disables the user's MFA.

Warning: identification_status: unverified can lock the user out of their account. An unverified phone number cannot be used to sign in, so if the user has no other verified or reserved identifier, deleting their existing phone numbers leaves them unable to authenticate — and unable to verify the new number, since that requires signing in. Recovery then requires another admin API call.

1 parameter · 2 body fields
user_idstringrequired
The ID of the user whose phone number to replace
phone_numberstringrequired
The new phone number. Must adhere to the E.164 standard for phone number format.
identification_statusstringoptional
Controls the status of the replacement phone number. Defaults to `verified`. Set to `reserved` to create it reserved (unverified but usable for sign-in and locked so no other user can claim it), or to `unverified` to create it neither usable for sign-in nor locked. **Warning:** `unverified` can lock the user out of their account. An unverified phone number cannot be used to sign in, so if the user has no other verified or reserved identifier, they will be unable to authenticate and unable to verify this number. Prefer `reserved` unless you specifically need the number left unclaimed — for example so that another user can also hold it until one of them verifies it.
Allowed:verifiedreservedunverifiedDefault:verified

6 status codes
200Success
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
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters.