Account Holder


Money can't be stored at Swan without belonging to "someone". This "someone" is the account holder.
Account holder is the term Swan uses to designate the owner of one or several accounts at Swan. Money stored in an account belongs to the account holder.
An account holder can be one of your customers, whether an actual human being ("natural person") or a legal entity such as a company or an association ("legal person"). Even you can be an account holder.
Account holders, created on-demand, are able to use their accounts immediately, with some restrictions. Until identity verification has been completed, the account holder is limited to €150 of outgoing payments over a 30 day period and will not be assigned an IBAN.

Verification process

To fight money laundering and terrorist financing, banking regulations require that financial establishments such as Swan keep track of and verify their clients. In banking jargon, we talk about KYC (Know Your Customer). To handle KYC, Swan has set up a fluid and pleasant white-label identity verification for account holders.
A person can open an account for themselves as a "natural person," or they can open an account on behalf of a "legal person," like their company. In either case, Swan makes sure that the person opening the account actually is who they say they are.
To do this, Swan provides a streamlined and ultra-strong verification process through web responsive onboarding interfaces that can easily be integrated into your product.
Verification steps
Here's how it works: the person opening the account takes a selfie, presents at least one identification document, and Swan compares the two. The combination of identity documentation and biometric face recognition makes for an ultra-strong KYC.
If the account is being opened for a legal person, they will likely be asked to provide additional documents related to the legal person's identity.
Swan is proud to make your job easier with this ultra-strong KYC, but if it's a blocking point for you and you feel it is absolutely vital to collect your account holders' data and identification yourself, don't hesitate to contact us: [email protected].
Once an account holder is verified, their account's paymentLevel goes from Limited to Unlimited. The €150 limit on outgoing payments over a period of 30 days is lifted, and they can obtain an IBAN.
To help you keep track of the verification process of an account holder at Swan, we provide the verificationStatus field with the following values:
  • NotStarted: when the verification process has not yet begun
  • WaitingForInformation : when Swan is waiting on information from the account holder
  • Pending : when Swan has begun reviewing the information provided by the account holder
  • Verified: when Swan has successfully completed the verification process
Check the statuses you may want to track throughout the verification process here.


Onboarding refers to the process of opening a new account for your client, who thus becomes the account holder.
To open an account, you must redirect your client to an onboarding URL provided by Swan.

Create an onboarding

To obtain an onboarding URL, there are two options:
  • #nocode: Select "Activate public links" in your dashboard. You'll see the URLs available below and can redirect your customers to them (see the white-label #nocode tab). There are separate URLs for onboarding a physical person vs a legal person. These public URLs are the same for all of your account holders.
  • by API: streamline your customer's onboarding by preloading the Swan form with data you already know about them. To do this, you can call the API and obtain a dedicated onboarding URL for each account holder.
Onboarding steps
Be careful: if you want to be sure no one other than your clients is able to open an account, you will want to restrict access to onboarding. You will have to "Deactivate public links" in the white-label #nocode tab on the dashboard.
To obtain an onboarding URL by API, use the following mutation:
  • onboardCompanyAccountHolder for a legal person
  • onboardIndividualAccountHolder for a physical person
An onboarding is thus returned, with the onboardingUrlfield containing the URL for onboarding your customer.

Complete an onboarding

There are two ways to complete an onboarding: #nocode or through the API.
For the #nocode way, just redirect your customer to the onboarding URL. Here are the steps they will have to follow at Swan:
  1. 1.
    Agree to Swan's terms of service, and agree to the conditions of partnership with your company.
  2. 2.
    Enter identification data. All this information can be prefilled if you had it transmitted during onboarding creation by API.
    • For a physical person: email, residency address, employment status, monthly income
    • For a legal person:
      Legal representative's info: email, first name, last name
      Legal person's info: residency address, business activity description, legal form, name, registration number, yearly payment volume, ultimate beneficial owners
  3. 3.
    Connect to Swan using their smartphone. Learn more about the user login process.
To complete an onboarding through an API you can use the following mutations: updateCompanyOnboarding or updateIndividualOnboarding to fill the onboarding fields and finalizeOnboarding to finish the onboarding.
To ensure that an onboarding is valid for finalization, you have to check its validation status using the statusInfo object of the onboarding success payload. If the status is Invalid, you will have to use OnboardingInvalidStatusInfo to get the list of the missing required fields to provide. If the status is Valid, your onboarding is ready to be finalized. If the status is, Finalized it means that this onboarding has already been finalized and can’t be finalized again.
The update onboarding mutations have an incremental behavior, it means that any field filled with data in the input will be updated. If you don’t input a value for a field that already has a value, then the value will remain the same.
You can’t update only one item of the individualUltimateBeneficialOwners fields, you have to provide the new full list to update it.
The update mutations must be used with a project access token, whereas finalizeOnboarding mutation is used with a user access token (so we can know which user created the account). This means that you must log in your user first and get their access token before calling finalizeOnboarding. Learn more about the user login process.
You can test this sequence as many times as you'd like from your dashboard using the public URL in the Sandbox environment.
Create as many Sandbox users as you want, to simulate as many cases as possible. Learn more.
Once the onboarding process is completed:
  1. 1.
    The account holder is created with the Enabled status
  2. 2.
    The account holder's account is created. Learn more.
  3. 3.
    The person having performed the onboarding becomes the legal representative, and has the first membership with access to full rights on this account. Learn more.
  4. 4.
    The relationship you have with the account holder for a created account is stored in the partnershipStatusInfofield of the account object.```
The onboarding list is available in the onboardings query. It allows you to keep track of your customer's onboarding process, and once the onboarding is done, to keep track of the account holder that was created.

Verification steps

Here are the different statuses you may want to track throughout the verification process.

1 - Onboarding

2 - Identity verification

3 - Document collection

4 - Compliance review

5 - Verified

Last modified 1d ago