Add and verify a user's phone number
Account onboarding
Clerk · Class
PhoneNumber
PhoneNumber represents a user's phone number and its verification state. Its API supports adding numbers, completing SMS OTP verification, formatting them as E.164 values, and using them for multi-factor authentication.
How it works
PhoneNumber represents one of a user's phone numbers and tracks its verification state. Create or access the number, start verification to send an SMS OTP, then submit that OTP to finish verification; the number can also support multi-factor authentication.
Syntax
PhoneNumberKey points
- PhoneNumber is the object used to represent a user's phone number.
- A number may serve either identity verification or ordinary communication.
- The object retains the state needed while verification progresses.
- A verified phone number can be used as an MFA factor.
- Starting verification sends a one-time password by SMS.
- toString() provides a normalized E.164 string containing the country code.
Common mistakes
- Do not treat a phone number as trusted until its verification flow has completed.
- Call prepareVerification() before attempting verification; skipping this first step breaks the documented two-step flow.
- The completion call requires the OTP received by SMS.
Example: Verify a phone number
const phoneNumber = user.phoneNumbers[0];
await phoneNumber.prepareVerification();
await phoneNumber.attemptVerification({ code: otp });
console.log(phoneNumber.toString());Starts SMS verification, submits the received OTP, then formats the verified number for display.
When to use it
Use a verified number as proof of ownership
Identity assurance
Use SMS verification as a multi-factor authentication step
Account security
Store and display a user's contact number
Communication
Interview questions
QHow is a phone number verified?
PhoneNumber models a user's phone number and its verification state. Verification begins with prepareVerification(), which sends an SMS OTP, and ends with attemptVerification() using that OTP.
Follow-up: How can it participate in MFA? It can be used as an additional verification factor during sign-in.
QWhy does Clerk require phone-number verification?
The object can be used as proof of identity or as a contact method. Verification establishes that the number belongs to the rightful owner.
Follow-up: What must an implementation avoid? It should not rely on an unverified number for identity assurance.
QHow is a phone number added and represented?
The documented API includes create() for adding a phone number to the current user. After creation, the number's verification flow can be initiated and completed.
Follow-up: What other representation is available? toString() returns the number in E.164 format, including country code and number.
Related
UserVerificationIdentificationLinkMulti-factor authentication