SignUp

Search…
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.
web3Wallet
string | null
The Web3 wallet public address supplied to the current sign-up. In Ethereum, the address is made up of 0x + 40 hexadecimal characters.
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
Name
Description
params
​SignUpParams​
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
Name
Description
params
​SignUpParams​
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
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.
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
Name
Description
params
​SignUpVerificationAttemptParams​
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
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
Name
Description
params
​VerificationAttemptParams​
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.
createMagicLinkFlow()
createMagicLinkFlow() => CreateMagicLinkFlowParams<StartMagicLinkFlowParams, SignUpResource>
Sets up a sign up with magic link flow. Calling createMagicLinkFlow() will return two functions. 
The first function is async and starts the magic link flow, preparing a magic link verification. It sends the magic link email and starts polling for verification results. The signature is startMagicLinkFlow({ redirectUrl: string }) => Promise<SignUpResource>.
The second function can be used to stop polling at any time, allowing for full control of the flow and cleanup. The signature is cancelMagicLinkFlow() => void.
Returns
​CreateMagicLinkFlowReturn<StartMagicLinkFlowParams, SignUpResource>
This method returns two functions. One to start the magic link flow and the other to cancel waiting for the results.
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
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
Name
Description
params
​VerificationAttemptParams​
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.
prepareWeb3WalletVerification()
prepareWeb3WalletVerification() => Promise<SignUpResource>
Helper method that allows you to initiate a verification process for a web3 wallet public address. It sends the public address to the server and expects a nonce that will need to be signed.
This is equivalent to calling SignUp.prepareVerification("web3_metamask_signature").
attemptWeb3WalletVerification()
attemptPhoneNumberVerification() => Promise<SignUpResource>
Helper method that attempts to complete the verification process for a web3 wallet public address. 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: "web3_metamask_signature", signature: "..." }).
authenticateWithRedirect(params)
authenticateWithRedirect(params: AuthenticateWithRedirectParams) => 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
Name
Description
params
​AuthenticateWithRedirectParams​
An object that specifies the verification strategy (one of the supported OAuth providers), the callback URL the OAuth provider should redirect to, as well as the URL that the user should be redirected to upon successful sign in.
Promise<void>
This method returns a Promise which doesn't resolve to any value.
authenticateWithMetamask(params)
authenticateWithMetamask(params: AuthenticateWithMetamaskParams) => void
Starts a sign up flow that uses the Metamask browser extension to authenticate the user using their public wallet address.
Parameters
Returns
Name
Description
redirectUrl
string
Full URL or path to navigate after successful sign up.
This method has no return value.
Interfaces
AuthenticateWithRedirectParams
Property
Description
strategy
string
The OAuth provider that will be used for singing in. Must be one of the supported OAuthStrategy values.
redirectUrl
string
The URL that the OAuth provider should redirect to, on successful authorization on their part.
redirectUrlComplete
string
The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in
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.
web3Wallet
string | null
The user's Web3 wallet public address. In Ethereum, the address is made up of 0x + 40 hexadecimal characters
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.
invitationToken
string | null
It represents a token that was generated as part of an invitation creation. Using this token, you can auto-verify the email address that this invitation was sent to without any additional steps.
For more information about how invitations work, refer to our Invitations guide.
SignUpVerificationsResource
Name
Description
emailAddress
​SignUpVerificationResource​
phoneNumber
​SignUpVerificationResource​
web3Wallet
​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.
StartMagicLinkFlowParams
Name
Description
redirectUrl
string
The URL to be redirected to after the magic link verification is prepared. 
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.
Types
CreateMagicLinkFlowReturn<StartMagicLinkParams, SignUpResource>
{ startMagicLinkFlow: (params: StartMagicLinkFlowParams) => Promise<SignUpResource>, cancelMagicLinkFlow: () => void }
startMagicLinkFlow
Function that starts the magic link flow. It prepares a magic link verification and polls for the verification result. Accepts StartMagicLinkFlowParams. Returns a Promise which resolves to a SignUpResource. You can check the SignUpResource#verifications for the verification result.
cancelMagicLinkFlow
Function to cleanup the magic link flow. Stops waiting for verification results.
SignUpVerificationStrategy
email_code | phone_code
Value
Description
email_link
Specify email code as the verification strategy.
This applies only to email addresses and is a one-time code sent to that email address.
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.
web3_metamask_signature
The verification will attempt to be completed using the user's web3 wallet public address.
OAuthStrategy
oauth_facebook | oauth_github | oauth_google | oauth_hubspot | oauth_tiktok | oauth_gitlab | oauth_discord | oauth_twitter | oauth_twitch | oauth_linkedin | oauth_dropbox | oauth_bitbucket | oauth_microsoft | oauth_notion
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.
oauth_gitlab
Specify GitLab as the verification OAuth provider.
oauth_discord
Specify Discord as the verification OAuth provider.
oauth_twitter
Specify Twitter as the verification OAuth provider.
oauth_twitch
Specify Twitch as the verification OAuth provider.
oauth_linkedin
Specify LinkedIn as the verification OAuth provider.
oauth_dropbox
Specify Dropbox as the verification OAuth provider.
oauth_bitbucket
Specify Bitbucket as the verification OAuth provider.
oauth_microsoft
Specify Microsoft as the verification OAuth provider.
oauth_notion
Specify Notion as the verification OAuth provider.
SignIn
User
Last modified 1mo ago