SignUp

The SignUp object contains the state of the current sign-up that the user has initiated.

Overview

The SignUp object holds the state of the current sign up and provides helper methods to navigate and complete the sign up flow. Once a sign up is complete, a new user is created.

There are two important steps that need to be done in order for a sign up to be completed:

  • Supply all the required fields. The required fields depend on your instance settings.

  • Verify contact information. Some of the supplied fields need extra verification. These are the email address and phone number.

The above steps can be split into smaller actions (e.g. you don't have to supply all the required fields at once) and can done in any order. This provides great flexibility and supports even the most complicated sign up flows. The SignUp object provides a number of helper methods to achieve the above.

Also, the attributes of the SignUp object can basically be grouped into three categories:

  • Those that contain information regarding the sign-up flow and what is missing in order for the sign-up to complete. For more information on these, check our detailed sign-up flow guide.

  • Those that hold the different values that we supply to the sign-up. Examples of these are username, emailAddress, firstName, etc.

  • Those that contain references to the created resources once the sign-up is complete, i.e. createdSessionId and createdUserId.

Attributes

Name

Description

status

string

The status of the current sign-up. It can take the following values:

  • missing_requirements: There are required fields that are either missing or they are unverified.

  • complete: All the required fields have been supplied and verified, so the sign-up is complete and a new user and a session have been created.

  • abandoned: The sign-up has been inactive for a long period of time, thus it's considered as abandoned and need to start over.

requiredFields

string[]

An array of all the required fields that need to be supplied and verified in order for this sign-up to be marked as complete and converted into a user.

optionalFields

string[]

An array of all the fields that can be supplied to the sign-up, but their absence does not prevent the sign-up from being marked as complete.

missingFields

string[]

An array of all the fields whose values are not supplied yet but they are mandatory in order for a sign-up to be marked as complete.

unverifiedFields

string[]

An array of all the fields whose values have been supplied, but they need additional verification in order for them to be accepted.

Examples of such fields are emailAddress and phoneNumber.

supportedExternalAccounts

string[]

An array of all the external accounts that are supported in the current sign-up, e.g. oauth_google, oauth_facebook, etc.

verifications

SignUpVerificationsResource

An object that contains information about all the verifications that are in-flight.

username

string | null

The username supplied to the current sign-up. This attribute is available only if usernames are enabled. Check the available instance settings for more information.

emailAddress

string | null

The email address supplied to the current sign-up.

This attribute is available only if the selected contact information includes email address. Check the available instance settings for more information.

phoneNumber

string | null

The phone number supplied to the current sign-up. This attribute is available only if the selected contact information includes phone number. Check the available instance settings for more information.

passwordEnabled

boolean

The value of this attribute is true if a password was supplied to the current sign-up.

This attribute is available only if password-based authentication is enabled. Check the available instance settings for more information.

firstName

string | null

The first name supplied to the current sign-up. This attribute is available only if name is enabled in personal information. Check the available instance settings for more information.

lastName

string | null

The last name supplied to the current sign-up. This attribute is available only if name is enabled in personal information. Check the available instance settings for more information.

unsafeMetadata

{[string]: any} | null

Metadata that can be read and set from the frontend. Once the sign up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign up and will automatically be attached to the created User object.

createdSessionId

string | null

The identifier of the newly-created session. This attribute is populated only when the sign-up is complete.

createdUserId

string | null

The identifier of the newly-created user. This attribute is populated only when the sign-up is complete.

Methods

create(params)

create(params: SignUpParams) => Promise<SignUpResource>

This method initiates a new sign up flow. It creates a new SignUp object and de-activates any existing SignUp that the client might already had in progress.

The form of the given params depends on the configuration of the instance. Choices on the instance settings affect which options are available to use.

The create method will return a promise of the new SignUp object. This sign up might be complete if you supply the required fields in one go. However, this is not mandatory. Our sign up process provides great flexibility and allows users to easily create multi-step sign up flows.

Parameters
Returns
Parameters

Name

Description

params

SignUpParams

Returns

Promise<SignUpResource>

This method returns a Promise which resolves with a SignUp object. Check the status attribute to see if the SignUp has been completed or a hint on what needs to happen next.

update(params)

update(params: SignUpParams) => Promise<SignUpResource>

This method is used to update the current sign up.

As with create, the form of the given params depends on the configuration of the instance.

Parameters
Returns
Parameters

Name

Description

params

SignUpParams

Returns

Promise<SignUpResource>

This method returns a Promise which resolves with a SignUp object. Check the status attribute to see if the SignUp has been completed or a hint on what needs to happen next.

prepareVerification(strategy)

prepareVerification(strategy: SignUpVerificationStrategy) => Promise<SignUpResource>

The prepareVerification is used to initiate the verification process for a field that requires it. As mentioned above, there are two fields that need to be verified:

  • emailAddress: The email address can be verified via an email code. This is a one-time code that is sent to the email already provided to the SignUp object. The prepareVerification sends this email.

  • phoneNumber: The phone number can be verified via a phone code. This is a one-time code that is sent via an SMS to the phone already provided to the SignUp object. The prepareVerification sends this SMS.

Parameters
Returns
Parameters

Name

Description

strategy

SignUpVerificationStrategy

The strategy you want to use for the verification process.

Each strategy applies to a different identification type, e.g. email_code can only be used to verify email addresses whereas phone_code can be used only for phone numbers. Select the one that makes for your use case.

Returns

Promise<SignUpResource>

This method returns a Promise which resolves with a SignUp object.

attemptVerification(params)

attemptVerification(params: SignUpVerificationAttemptParams) => Promise<SignUpResource>

Attempts to complete the in-flight verification process that corresponds to the given strategy. In order to use this method, you should first initiate a verification process by calling SignUp.prepareVerification.

Depending on the strategy, the method parameters could differ.

Parameters
Returns
Parameters

Name

Description

params

SignUpVerificationAttemptParams

Returns

Promise<SignUpResource>

This method returns a Promise which resolves with a SignUp object. Check the status attribute to see if the SignUp has been completed or a hint on what needs to happen next.

prepareEmailAddressVerification()

prepareEmailAddressVerification() => Promise<SignUpResource>

Helper method that allows you to initiate a verification process for an email address. It basically sends a one-time code to the email address already supplied to the current sign up.

This is equivalent to calling SignUp.prepareVerification("email_code").

Returns
Returns

Promise<SignUpResource>

This method returns a Promise which resolves with a SignUp object.

attemptEmailAddressVerification(params)

attemptEmailAddressVerification(params: VerificationAttemptParams) => Promise<SignUpResource>

Helper method that attempts to complete the verification process for an email address. It basically verifies that the supplied code is the same as the one-time code that was sent to the email address during the prepare verification phase.

This is equivalent to calling SignUp.attemptVerification({strategy: "email_code", ...params}).

Parameters
Returns
Parameters

Name

Description

params

VerificationAttemptParams

Returns

Promise<SignUpResource>

This method returns a Promise which resolves with a SignUp object. Check the status attribute to see if the SignUp has been completed or a hint on what needs to happen next.

preparePhoneNumberVerification()

preparePhoneNumberVerification() => Promise<SignUpResource>

Helper method that allows you to initiate a verification process for a phone number. It basically sends a one-time code to the phone number already supplied to the current sign up.

This is equivalent to calling SignUp.prepareVerification("phone_code").

Returns
Returns

Promise<SignUpResource>

This method returns a Promise which resolves with a SignUp object.

attemptPhoneNumberVerification(params)

attemptPhoneNumberVerification(params: VerificationAttemptParams) => Promise<SignUpResource>

Helper method that attempts to complete the verification process for a phone number. It basically verifies that the supplied code is the same as the one-time code that was sent to the phone number during the prepare verification phase..

This is equivalent to calling SignUp.attemptVerification({strategy: "phone_code", ...params}).

Parameters
Returns
Parameters

Name

Description

params

VerificationAttemptParams

Returns

Promise<SignUpResource>

This method returns a Promise which resolves with a SignUp object. Check the status attribute to see if the SignUp has been completed or a hint on what needs to happen next.

signUpWithOAuth(strategy, callbacks)

signUpWithOAuth(strategy: OAuthStrategy, callbacks: OAuthCallbacks) => Promise<void>

Signs up users via OAuth, where an external account provider is used to verify the user's identity and provide certain information about the user.

Parameters
Returns
Parameters

Name

Description

strategy

OAuthStrategy

The verification strategy. Select one of the supported OAuth providers.

callbacks

OAuthCallbacks

An object that specifies the URL for the OAuth provider to redirect to, as well as the URL that the user should be redirected to upon successful sign up.

Returns

Promise<void>

This method returns a Promise which doesn't resolve to any value.

Interfaces

SignUpParams

Name

Description

firstName

string | null

The user's first name.

This option is available only if name is selected in personal information.

Please check the instance settings for more information.

lastName

string | null

The user's last name.

This option is available only if name is selected in personal information.

Please check the instance settings for more information.

password

string | null

The user's password.

This option is available only if password-based authentication is selected.

Please check the instance settings for more information.

emailAddress

string | null

The user's email address.

This option is available only if email address is selected in contact information. Keep in mind that the email address requires an extra verification process.

Please check the instance settings for more information.

phoneNumber

string | null

The user's phone number.

This option is available only if phone number is selected in contact information. Keep in mind that the phone number requires an extra verification process.

Please check the instance settings for more information.

username

string | null

The user's username.

This option is available only if usernames are enabled.

Please check the instance settings for more information.

unsafeMetadata

{[string]: any} | null

Metadata that can be read and set from the frontend. Once the sign up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign up and will automatically be attached to the created User object.

SignUpVerificationsResource

Name

Description

emailAddress

SignUpVerificationResource

phoneNumber

SignUpVerificationResource

SignUpVerificationResource

Name

Description

status

string | null

The verification status.

nextAction

string

Specifies the action that you could do next in order to complete this verification.

supportedStrategies

string[]

An array of all strategies supported for this resource.

strategy

string | null

The verification strategy. Possible strategy values are:

  • email_code: User will receive a one-time authentication code via email.

  • phone_code: User will receive a one-time authentication code in their phone, via SMS.

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.

SignUpVerificationAttemptParams

Name

Description

strategy

SignUpVerificationStrategy

code

string

This property is applicable for strategies email_code and phone_code.

This represents the one-time code that was sent to either the email address or the phone number during the SignUp.prepareVerification step.

VerificationAttemptParams

Name

Description

code

string

This property is applicable for strategies email_code and phone_code.

This represents the one-time code that was sent to either the email address or the phone number during the SignUp.prepareVerification step.

OAuthCallbacks

Name

Description

callbackUrl

string

The URL that the OAuth provider should redirect to, on successful authorisation on their part.

callbackUrlComplete

string

The URL that the user will be redirected to, after successful authorisation from the OAuth provider and Clerk sign in

Types

SignUpVerificationStrategy

email_code | phone_code

Value

Description

email_code

Specify email code as the verification strategy.

This applies only to email addresses and is a one-time code sent to that email address.

phone_code

Specify phone code as the verification strategy.

This applies only to phone number and is a one-time code sent to that phone number via SMS.

OAuthStrategy

oauth_facebook | oauth_github | oauth_google | oauth_hubspot | oauth_tiktok

Value

Description

oauth_facebook

Specify Facebook as the verification OAuth provider.

oauth_github

Specify Github as the verification OAuth provider.

oauth_google

Specify Google as the verification OAuth provider.

oauth_hubspot

Specify Hubspot as the verification OAuth provider.

oauth_tiktok

Specify TikTok as the verification OAuth provider.