v13

latestOpenAPI 3.0.3MITraw.githubusercontent.com2026-08-04237161688.6 KB
Phone Numbers

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.

put/users/{user_id}/phone_number

Path parameters

user_idstring required

The ID of the user whose phone number to replace

Request body

phone_numberstring required

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

identification_status'verified' | 'reserved' | 'unverified'

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.

Response

Success

idstring
object'phone_number' required

String representing the object's type. Objects of the same type share the same value.

phone_numberstring required
reserved_for_second_factorboolean
default_second_factorboolean
reservedboolean required
backup_codesstring[] nullable
created_atinteger required

Unix timestamp of creation

updated_atinteger required

Unix timestamp of creation