Skip to main content

Account onboarding

Account onboarding is, at its core, the process to create account holders.

One end result of onboarding is also creating the first account for the new account holder. Account holders complete an new onboarding to open another account.

Cross reference

During onboarding, users also complete an account holder verification process and authenticate (log in) for the first time. The might also sign up for Swan if they haven't already.

Types of onboarding

There are two types of onboarding, directly linked to the two types of accounts Swan offers. Each onboarding has a unique onboardingId.

  • Individual onboarding is the process of creating a new individual account holder, and opening a new Swan account for that account holder.
  • Company onboarding is the process of creating a new company account holder, and opening a new Swan account for that account holder.

The individual and company onboarding processes are similar. However, they're split in the documentation to prevent mixing up small but important details.

Swan Banking Frontend

If you'd like to customize the onboarding experience for your users (while respecting local regulations), check out the open source Swan Banking Frontend.

Purpose of onboarding

Completing the onboarding process serves several purposes.

  1. Account holder is created.
  2. Account holder's account is created.
  3. The person who performed the onboarding process becomes the legal representative of the account. They're also the account's first member with full permissions.
  4. Your relationship with the account holder is stored in the partnershipStatusInfofield of the account object.

Consider a few details about Swan onboarding links.

  1. You can generate unique links using the API, or use public links from your Dashboard. Learn how to generate onboarding links in the guides for individuals and companies.
  2. Unique onboarding links are single-use. If you get an HTTP 500 Internal Server Error when submitting the onboarding form, it's because an onboarding was already finalized using that link. You need to generate a new link.
  3. The true purpose of the state parameter is to prevent Cross-Site Request Forgery (CSRF) and related attacks. Consider using it to your advantage. It includes your user's onboarding ID by default, so you can save this onboarding ID when generating the link.
Public onboarding links

Use public links with caution. Those with fraudulent intent can use these public links to complete multiple onboardings, and if this happens undetected, they'll have multiple accounts in your project.

Onboarding statuses

Ongoing (Invalid)
  • This is the first status assigned to an onboarding when using the frontend.
  • If using the API, this is the first status if not all required information is included with your mutation.
  • Status might change to Invalid if required information is removed or if some information is incorrect.
Next step: Submit or update required information to advance to Ongoing (Valid) (both you and the end user can submit or update information)
Ongoing (Valid)
  • This is the first status assigned to an onboarding if using the API and you included all required information with your mutation.
  • Status changes to Valid when missing required information is submitted or if incorrect information is updated.
Next step: User completes form, clicks "Finalize," and provides consent to complete the onboarding process
FinalizedOnboarding completed

Country requirements

Onboarding is a highly localized experience. Everything from what to include in your API request to how to ask users to verify their identity to whether Swan requires certain ID numbers or documents depends on the account country.

Account onboarding country requirements are described in the individual and company onboarding sections. Please follow the requirements for your target countries closely.

API sequence diagram

Review this sequence diagram that depicts the onboarding flow with the API.


The following guides are common to the individual and company onboarding processes.