PhoneNumber

The PhoneNumber object describes a User's phone number.

Overview

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, so that we can make sure they can be assigned to their rightful owners. The PhoneNumber object holds all the necessary state around the verification process.

The verification process always starts with the PhoneNumber.prepareVerification() method, which will send a one-time verification code via an SMS message. The second and final step involves an attempt to complete the verification by calling the PhoneNumber.attemptVerification() method, passing the one-time code as a parameter.

Finally, phone numbers are used as part of multi-factor authentication. Users receive an SMS message with a one-time code that they need to provide as an extra verification step.

Attributes

Name	Type	Description
id	string	A unique identifier for this phone number.
phoneNumber	string	The value of this phone number, in E.164 format.
reservedForSecondFactor	boolean	Value will be `true` if this phone number is reserved for multi-factor authentication (2FA), `false` otherwise.
defaultSecondFactor	boolean	Value will be `true` if this phone number is the default second factor, `false` otherwise. A user must have exactly one default second factor, if multi-factor authentication (2FA) is enabled.
verification	VerificationResource	An object holding information on the verification of this phone number.
linkedTo	IdentificationLinkResource	An object containing information about any other identification that might be linked to this phone number.

Methods

create()

create() => Promise<PhoneNumberResource>

Creates a new phone number for the current user.

Parameters
This method accepts no parameters.

Returns

Type	Description
Promise<PhoneNumberResource>	This method returns a `Promise` which resolves with a `PhoneNumber` object.

prepareVerification()

prepareVerification() => Promise<PhoneNumberResource>

Kick off the verification process for this phone number. An SMS message with a one-time code will be sent to the phone number value.

Parameters
This method accepts no parameters.

Returns

Type	Description
Promise<PhoneNumberResource>	This method returns a `Promise` which resolves with a `PhoneNumber` object.

attemptVerification(code)

attemptVerification(params: AttemptPhoneNumberVerificationParams) => Promise<PhoneNumberResource>

Attempts to verify this phone number, passing the one-time code that was sent as an SMS message. The code will be sent when calling the PhoneNumber.prepareVerification() method.

Parameters

Name	Description
params	An object of type `AttemptPhoneNumberVerificationParams`

Returns

Type	Description
Promise<PhoneNumberResource>	This method returns a `Promise` which resolves with a `PhoneNumber` object.

destroy()

destroy() => Promise<void>

Delete this phone number.

Parameters

This method accepts no parameters.

Returns

Type	Description
Promise<void>	This method returns a Promise which doesn't resolve to any value.

setReservedForSecondFactor(reserved)

setReservedForSecondFactor(reserved: boolean) => Promise<PhoneNumberResource>

Marks this phone number as reserved for mutli-factor authentication (2FA) or not.

Parameters

Name	Type	Description
reserved	boolean	Pass true to mark this phone number as reserved for 2FA, or false to disable 2FA for this phone number.

Returns

Type	Description
Promise<PhoneNumberResource>	This method returns a `Promise` which resolves with a `PhoneNumber` object.

makeDefaultSecondFactor()

makeDefaultSecondFactor() => Promise<PhoneNumberResource>

Marks this phone number as the default second factor for mutli-factor authentication (2FA). A user can have exactly one default second factor.

Parameters

This method accepts no parameters.

Returns

Type	Description
Promise<void>	This method returns a Promise which doesn't resolve to any value.

toString()

toString() => string | null

Returns the phone number value in E.164 format.

The value is taken from the PhoneNumber.phoneNumber attribute.

Parameters

This method accepts no parameters.

Returns

Type	Description
string \| null	This method returns the string value of this phone number.

Interfaces

AttemptPhoneNumberVerificationParams

Name	Type	Description
code	string	The one-time code that was sent to the user's phone number when `prepareVerification` was called.

IdentificationLinkResource

Name	Type	Description
id	string	A unique identifier for the identification.
type	string	The identification type.

VerificationResource

Name	Type	Description
status	string \| null	The verification status. Possible values are: unverified: The verification process has not been completed. verified: The verification process has completed successfully. transferable: The verification can be transferred as part of an external account verification process. failed: The verification process has been completed, but failed. expired: The verification is invalid because it wasn't completed in the allowed time.
strategy	string \| null	The verification strategy. Possible strategy values are: email_code: User will receive a one-time authentication code via email. At least one email address should be on file for the user. The email_address_id parameter can also be specified to select one of the user's known email addresses. phone_code: User will receive a one-time authentication code in their phone, via SMS. At least one phone number should be on file for the user. The phone_number_id parameter can also be specified to select which of the user's known phone numbers the SMS will go to. password: The user needs to provide their password in order to be authenticated. oauth_google: The user will be authenticated with their Google account (Google SSO). oauth_facebook: The user will be authenticated with their Facebook account (Facebook SSO). oauth_hubspot: The user will be authenticated with their Hubspot account (Hubspot SSO). oauth_github: The user will be authenticated with their Github account (Github SSO). oauth_tiktok: The user will be authenticated with their TikTok account (TikTok SSO).
attempts	number \| null	The number of attempts to complete the verification so far. Usually, a verification allows for maximum 3 attempts to be completed.
expireAt	Date \| null	The timestamp when the verification will expire and cease to be valid.
error	ClerkAPIError \| null	Any error that occurred during the verification process from the Clerk API.
externalVerificationRedirectURL	URL \| null	If this is a verification that is based on an external account (usually oauth_*), this is the URL that the user will be redirected to after the verification is completed.