Skip to main content

Account onboarding

Overview​

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 a 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, individual and company, directly linked to the two types of accounts Swan offers. Each onboarding has a unique onboardingId.

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

TypeExplanation
Individual onboarding
  • Create a new individual account holder.
  • Open a new individual Swan account for that account holder.
Company onboarding
  • Create a new company account holder.
  • Open a new company Swan account for that account holder.
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. A new account holder is created.
  2. The account holder's Swan 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.

Requirements​

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.

Supporting documents​

Collecting supporting documents impacts multiple elements of the onboarding process. Consider these steps, including the statuses of both account holder verification and the supporting document collection.

StepEventAccount holder
verification status		Supporting document
collection status
1
Onboarding created
Not yet created
WaitingForDocument
2
Onboarding finalized
NotStarted
PendingReview
3
Legal representative completes identification
Pending
PendingReview
4
Swan requests supporting documents

💡 Subscribe to the webhook supportingDocumentCollection.updated. You'll be notified when a request is sent to collect documents.
WaitingForInformation
WaitingForDocuments
5
Partner uploads new documents

💡 If needed, get a list of required documents. Then, upload missing documents.
WaitingForInformation
WaitingForDocuments
6
Partner requests a collection review

💡 Partners (you) need to request a supporting document collection review after all supporting documents are uploaded. Request a review with the API or from your Dashboard.
Pending
PendingReview
7
Swan reviews supporting documents
Pending
PendingReview
8
(a) Swan approves the account holder
Verified
Approved
(b) Swan needs more documents to verify the account holder

💡 Get the list of required documents and review the rejection reason. Then, return to step 4.
WaitingForInformation
WaitingForDocuments

Statuses​

StatusExplanation
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

API sequence diagram​

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

Guides​

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