Onboarding
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.
To create an onboarding, there are three 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 Settings/Onboarding tab). There are separate URLs for onboarding a physical person vs a legal person for each available account country. These public URLs are the same for all of your account holders.
- API and #nocode: 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 create an onboarding by API, use the following mutation:
onboardCompanyAccountHolderfor a legal persononboardIndividualAccountHolderfor a physical person
You will need to set the input
accountCountry to select the country of your account, by default country is FRA (France)An
onboarding is thus returned. If you want the user to finish the onboarding with our #nocode interface, you can redirect them to the onboardingUrlfield.As onboarding are accessible with a link without additional security, we wipe non-finalized onboarding 30 days after their creation.
Onboarding is just the first step to validating an account. Sometimes Swan must also collect and verify supporting documents (company documents and individual documents).
You can set up document collection via the white-label tab, or using the API. If you use the API, we expose to you the required supporting document purposes, so you can upload them. This speeds up the verification process. Learn more about supporting documents.
Whether you're onboarding individuals or companies, documents can be uploaded as soon as their onboarding status is
Ongoing.Once the onboarding is Finalized you can no longer upload documents.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.Agree to Swan's terms of service, and agree to the conditions of partnership with your company.
- 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 nameLegal person's info: residency address, business activity description, legal form, name, registration number, yearly payment volume, ultimate beneficial owners
- 3.
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.
Once the onboarding process is completed:
- 1.The account holder is created with the
Enabledstatus - 2.
- 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.The relationship you have with the account holder for a created account is stored in the
partnershipStatusInfofield of theaccountobject.
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 finalized, to keep track of the account which was created.
This feature is only available for French-registered companies.
If you want Swan to automatically prefill the ultimate beneficiaries owners (UBO) of a company, you can use the
updateCompanyOnboarding mutation. The parameters needed are:registrationNumberfilled with a realregistrationNumbercompanyTypeis 'Company'address.countryis 'FRA'individualUltimateBeneficialOwnersis empty
Request
Response
mutation MyMutation {
updateCompanyOnboarding(
input: {
registrationNumber: "853827103"
companyType: Company
residencyAddress: { country: "FRA" }
onboardingId: "9683e260-a19b-4c05-9ed1-0d7689ddc832"
}
) {
... on UpdateCompanyOnboardingSuccessPayload {
__typename
onboarding {
id
info {
... on OnboardingCompanyAccountHolderInfo {
name
registrationNumber
individualUltimateBeneficialOwners {
firstName
lastName
}
}
}
}
}
}
}
{
"data": {
"updateCompanyOnboarding": {
"__typename": "UpdateCompanyOnboardingSuccessPayload",
"onboarding": {
"id": "9683e260-a19b-4c05-9ed1-0d7689ddc832",
"info": {
"name": null,
"registrationNumber": "853827103",
"individualUltimateBeneficialOwners": [
{
"firstName": "John",
"lastName": "Doe"
},
{
"firstName": "Nicolas",
"lastName": "Dupont"
}
]
}
}
}
}
}
You can add some others parameters in the mutation, but when those 4 conditions are met, we will automatically fetch the UBO.
Last modified 3mo ago