# PhoneNumber The `PhoneNumber` object describes a phone number. Phone numbers can be used as a proof of identification for users, or simply as a means of contacting users. Phone numbers must be **verified** to ensure that they can be assigned to their rightful owners. The `PhoneNumber` object holds all the necessary state around the verification process. The verification process consists of two steps: - The verification process always starts with the [prepareVerification()](https://clerk.com/docs/js-frontend/reference/types/phone-number.md#prepare-verification) method, which will send an OTP via an SMS message. - The second and final step involves an attempt to complete the verification by calling the [attemptVerification()](https://clerk.com/docs/js-frontend/reference/types/phone-number.md#attempt-verification) method, passing the OTP as a parameter. Finally, phone numbers can be used as part of [multi-factor authentication](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#multi-factor-authentication). During sign in, users can opt in to an extra verification step where they will receive an SMS message with an OTP. This OTP must be entered to complete the sign in process. > SMS functionality, including SMS OTPs, is restricted to phone numbers from countries that are enabled on your [SMS allowlist](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#sms-allowlist). This can be useful for avoiding extraneous SMS fees from countries from which your app is not expected to attract traffic. **By default, only the US and Canada are enabled.** ## Properties | Name | Type | Description | | ----------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | string | The unique identifier for this phone number. | | phoneNumber | string | The value of this phone number, in E.164 format. | | reservedForSecondFactor | boolean | Set to true if this phone number is reserved for second factor verificationSecond factor verification, also known as two-factor authentication (2FA) or multi-factor authentication (MFA), is the process of verifying a user's identity using an additional factor. For example, if a user signs in with their email and password, and then, is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their phone number, the OTP is the second factorA second factor is an additional factor of authentication that is required to complete the authentication process. For example, if a user signs in with their email and password, and then is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their email in order to verify their identity, the email OTP is the second factor... Set to false otherwise. | | defaultSecondFactor | boolean | Set to true if this phone number is the default second factorSecond factor verification, also known as two-factor authentication (2FA) or multi-factor authentication (MFA), is the process of verifying a user's identity using an additional factor. For example, if a user signs in with their email and password, and then, is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their phone number, the OTP is the second factorA second factor is an additional factor of authentication that is required to complete the authentication process. For example, if a user signs in with their email and password, and then is asked to also provide an OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. sent to their email in order to verify their identity, the email OTP is the second factor... Set to false otherwise. A user must have exactly one default second factor, if multi-factor authentication (MFA) is enabled. | | verification | VerificationResource | An object holding information on the verification of this phone number. | | linkedTo | IdentificationLinkResource[] | An array of objects containing information about any identifications that might be linked to the phone number. | | backupCodes | string[] | undefined | A list of backup codes in case of lost phone number access. | ## Methods ### `create()` Creates a new phone number for the current user. ```typescript function create(): Promise ``` ### `destroy()` Deletes this phone number. ```typescript function destroy(): Promise ``` ### `toString()` Returns the phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164) which includes the country code and the phone number. Can also be accessed via the `PhoneNumber.phoneNumber` attribute. ```typescript function toString(): string ``` ### `prepareVerification()` Kick off the verification process for this phone number. An SMS message with an OTP will be sent to the phone number value. ```typescript function prepareVerification(): Promise ``` ### `attemptVerification()` Attempts to verify this phone number, passing the OTP that was sent as an SMS message. The OTP will be sent when calling the [PhoneNumber.prepareVerification()](https://clerk.com/docs/js-frontend/reference/types/phone-number.md#prepare-verification) method. ```typescript function attemptVerification(params: AttemptPhoneNumberVerificationParams): Promise ``` ### `AttemptPhoneNumberVerificationParams` | Name | Type | Description | | ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | code | string | The OTPA one-time password (OTP) is a code that is used to authenticate a user. The OTP is typically sent to a user's email address or phone number and must be entered within a certain time period to be valid. that was sent to the user's phone number when prepareVerification was called. | ### `makeDefaultSecondFactor()` Marks this phone number as the default second factor for [multi-factor authentication (MFA)](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#multi-factor-authentication). A user can have exactly one default second factor. ```typescript function makeDefaultSecondFactor(): Promise ``` ### `setReservedForSecondFactor()` Marks this phone number as reserved for [multi-factor authentication (MFA)](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=js-frontend#multi-factor-authentication) or not. ```typescript function setReservedForSecondFactor(params: SetReservedForSecondFactorParams): Promise ``` #### `SetReservedForSecondFactorParams` | Name | Type | Description | | -------- | ------- | ------------------------------------------------------------------------------------------------------- | | reserved | boolean | Pass true to mark this phone number as reserved for MFA, or false to disable MFA for this phone number. | --- ## Sitemap [Overview of all docs pages](https://clerk.com/docs/llms.txt)