Skip to main content

Company account onboarding

Process of creating a new company account holder, and opening a new Swan account for that account holder.

Self-employed users hold company accounts. Refer to the country requirements section for more information about identification for self-employed users.

Process overview​

Company onboarding supports different types of organizations, including:

  • Several types of companies
  • Self-employed workers
  • Associations or not-for-profit organizations

Your main action is to create a company onboarding link. The link leads your user to a multi-step form through which Swan collects essential information to open the account.

When creating an onboarding link for your users, you can pre-fill most of the information for them. When your user goes through the form, they'll confirm that the information you entered is correct. Users can also fill in this information themselves.

Collecting onboarding information​

Company onboarding information can be submitted with the API or through Swan's onboarding form.

MethodDetails
Onboarding formThe onboarding form collects:

  1. User's email address.
  2. Legal information about the organization, including the company name, registration number (optional), VAT number (optional), and address, as well as details about the organization's activity and expected monthly volume.
  3. Information about the company's ultimate beneficial owners (UBO). This step only applies if the user selected company, home owner association, or other, when submitting their preliminary details.
  4. Information about the company's representatives. This includes individuals or legal entities authorized to act on behalf of the company.
  5. Required documents to verify your organization. You might not see this step in your onboarding process.
  6. User signs up for Swan.
You can also customize this form to better meet your needs. Review Swan's open source documentation, then ask your PIM (Product Integration Manager) for more information.
APIThe API collects the same information as the onboarding form. Please review the requirements explained on this page thoroughly, then follow the guide to create a company onboarding link.

Expected monthly volume​

Swan uses the expected monthly volume provided during onboarding to monitor the account. It's essential to select the range that corresponds to the company's actual volume, and to notify Swan if that expected monthly volume changes during the account's lifecycle.

If you use Swan's onboarding form, this information is collected by default. If you design your own form, please offer the following ranges:

  • Less than 10 000€ (LessThan10000)
  • Between 10 000€ and 50 000€ (Between10000And50000)
  • Between 50 000€ and 100 000€ (Between50000And100000)
  • More than 100 000€ (MoreThan100000)

Acquisition channel​

Use the optional acquisitionChannel field to indicate how the account holder was acquired.

ValueDescription
InboundOrganicAccount holders who signed up directly, such as through your website.
InboundReferralAccount holders acquired through referrals from existing users or partners.
OutboundSalesAccount holders acquired through direct sales efforts.
OutboundAccountingFirmAccount holders acquired through accounting firm partnerships.

Choose the value that best reflects your acquisition method for each account holder.

Ultimate beneficial owners (UBOs)​

Providing information for at least one UBO is mandatory for all companies. Swan allows two types of UBOs:

  • Ownership of capital UBO
  • Legal representative UBO

Ownership of capital UBO​

An ownership of capital UBO is anyone holding more than 25% of that company's value, whether directly or indirectly. Providing information for all UBOs owning 25% or more of a company is a legal requirement.

Direct ownership is the most straightforward form of ownership and means the UBO owns shares or stakes directly in the company. They are listed as a shareholder on company records. Indirect ownership means the UBO owns shares or stakes through other entities, such as trusts or parent companies. They may control or have rights to the company without their names being listed directly on company records.

tip

With the API, set type to HasCapital. On the onboarding form, choose Ownership of capital for type of control exercised. Always include how much capital they own and whether they own it directly or indirectly.

A legal representative UBO serves as the company's default UBO if a company doesn't have any UBOs who hold more than 25% of the company. Providing information for one legal representative UBO is required if the company has zero ownership of capital UBOs.

tip

With the API, set type to LegalRepresentative. On the onboarding form, choose Legal representative for type of control exercised. No other additional information is required in the UBO section for legal representative UBOs.

Representatives​

Representatives are individuals or legal entities authorized to act on behalf of the company during the onboarding process and for ongoing account management. This is separate from the legal representative who serves as the account admin and undergoes identification verification.

Swan supports two types of representatives:

  • Individual representatives: natural persons authorized to represent the company.
  • Company representatives: legal entities authorized to represent the company.

Representative data is optional and helps Swan automate verification processes and reporting.

API usage

Use the representatives field in the onboardCompanyAccountHolder and updateCompanyOnboarding mutations. Set type to Individual for natural persons or Company for legal entities.

Retrieving data automatically​

For companies located in 🇫🇷 France, Swan retrieves and prefills available data automatically from the National Business Register (RNE) after you provide the company's registration number. By allowing Swan to retrieve the data, you don't need to ask your users for certain information.

To trigger automatic retrieval, residencyAddress.country must be FRA and you must provide the registrationNumber. These fields are the only mandatory data you need to include when creating French company onboardings.

Representative data​

For data about representatives (UBOs, legal representatives, and company representatives), how Swan applies RNE data depends on what you provide:

  • If you provide data, Swan doesn't override your values with data from the RNE.
  • If you don't provide data, Swan creates the API objects and fills in the available data from the RNE. Note that the RNE information isn't always complete.

Other data​

For all other data, review the following table to understand how Swan applies retrieved data.

EventProviding dataExample
Create an onboardingSwan fills in as many onboarding fields as possible with data from the RNE. Note that the RNE information isn't always complete.

If you provide data manually when creating the onboarding, Swan doesn't override those values, only filling in the other data.		You:
  • Provide the mandatory residencyAddress.country and registrationNumber.
  • Provide the vatNumber, which could be retrieved from the RNE.
Swan:
  • Keeps the vatNumber you provided.
  • Fills in all other fields with the retrieved data.
Update an onboardingSwan overrides any data you provided manually when creating the onboarding with data from the RNE, unless you provide it again.You:
  • Specify the language.
  • Don't provide the vatNumber again.
Swan:
  • Replaces the vatNumber you provided when creating the onboarding with the vatNumber retrieved from the RNE.
  • Saves the language data.
Overriding data

When you create and update onboardings, Swan automatically fills in available data from the RNE. If you need to update an onboarding, and you provided data manually when creating that onboarding, provide the data again if you don't want Swan to override it.

Identification recommendations​

Swan must verify the identity of the legal representative for each company. Swan supports multiple identification processes, and some require a first transfer. For company onboarding, the following levels are recommended based on the account country.

Account countryRecommended level
for account admin		Other supported levels
🇫🇷 France✓ ExpertQES
PVID
🇧🇪 Belgium✓ ExpertQES
PVID
🇩🇪 Germany✓ QESnone
🇮🇹 Italy✓ ExpertQES
PVID
🇳🇱 Netherlands✓ ExpertQES
PVID
🇪🇸 Spain✓ ExpertQES
PVID

Self-employed account holders​

Account countryRecommended level
for self-employed		Other supported levels
🇫🇷 France✓ PVIDnone
🇧🇪 Belgium✓ QESExpert + first transfer
🇩🇪 Germany✓ QES + first transfernone

Country requirements for company accounts​

Requirements vary country to country when opening any type of Swan account. Requirements for company accounts are different than for individual accounts, and there is also a different mutation.

For company accounts, use the onboardCompanyAccountHolder mutation to collect the following information according to your desired account country.

This section covers four types of information:

  • Company and account holder information: Basic company details
  • UBO information: Ultimate beneficial owners (25%+ ownership or legal representative UBOs)
  • Legal representative information: The individual who manages the account and undergoes identification
  • Representative information: Additional individuals or legal entities authorized to act on behalf of the company

Field Requirements Legend

● REQ Required:Must be completed.
◐ CND Conditional:Required only in specific situations.
○ OPT Optional:Isn't required; may have a default value.

Company and account holder information​

API field🇫🇷
France		🇧🇪
Belgium		🇩🇪
Germany		🇮🇹
Italy		🇳🇱
Netherlands		🇪🇸
Spain
accountCountry● REQ
(FRA)		● REQ
(BEL)		● REQ
(DEU)		● REQ
(ITA)		● REQ
(NLD)		● REQ
(ESP)
accountName○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
acquisitionChannel○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
businessActivity● REQ● REQ● REQ● REQ● REQ● REQ
businessActivityDescription● REQ● REQ● REQ● REQ● REQ● REQ
companyType● REQ● REQ● REQ● REQ● REQ● REQ
email● REQ● REQ● REQ● REQ● REQ● REQ
isRegistered● REQ● REQ● REQ● REQ● REQ● REQ
language● REQ● REQ● REQ● REQ● REQ● REQ
monthlyPaymentVolume● REQ● REQ● REQ● REQ● REQ● REQ
name (company name)● REQ● REQ● REQ● REQ● REQ● REQ
oAuthRedirectParameters○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
registrationNumber● REQ● REQ● REQ● REQ● REQ● REQ
residencyAddress.addressLine1● REQ● REQ● REQ● REQ● REQ● REQ
residencyAddress.addressLine2○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
residencyAddress.city● REQ● REQ● REQ● REQ● REQ● REQ
residencyAddress.country● REQ● REQ● REQ● REQ● REQ● REQ
residencyAddress.postalCode● REQ● REQ● REQ● REQ● REQ● REQ
residencyAddress.state○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
taxIdentificationNumber○ OPT○ OPT● REQ ∗● REQ○ OPT◐ CND ∗∗
tradeName○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
typeOfRepresentation● REQ● REQ● REQ● REQ● REQ● REQ
vatNumber○ OPT○ OPT○ OPT● REQ○ OPT○ OPT

∗ If the accountCountry is Germany, the account holder has 90 days to provide their Tax ID Number when opening an account. Otherwise, the account is Suspended. Share Swan's Support Center article if your account holders have concerns.

∗∗ Required if both the accountCountry and residencyAddress.country are Spain.

info

isRegistered must be true and the registrationNumber provided for all onboardings where companyType is Company. This also applies when companyType is SelfEmployed and the account country is France. Swan overrides isRegistered if the provided value is false but it should be true. Learn more about how Swan retrieves data for certain company accounts.

UBO information​

If your company has a legal representative UBO, most of these fields can be left empty. However, for individualUltimateBeneficialOwners.type, please indicate LegalRepresentative.

Abbreviation

UBO stands for a portion of the API field: individualUltimateBeneficialOwners.

Field Requirements Legend

● REQ Required:Must be completed.
◐ CND Conditional:Required only in specific situations.
○ OPT Optional:Isn't required; may have a default value.
API field🇫🇷
France		🇧🇪
Belgium		🇩🇪
Germany		🇮🇹
Italy		🇳🇱
Netherlands		🇪🇸
Spain
UBO.birthCity● REQ● REQ○ OPT● REQ● REQ● REQ
UBO.birthCityPostalCode● REQ● REQ○ OPT● REQ● REQ○ OPT
UBO.birthCountryCode● REQ● REQ● REQ● REQ● REQ● REQ
UBO.birthDate● REQ● REQ○ OPT● REQ● REQ● REQ
UBO.direct● REQ● REQ● REQ● REQ● REQ● REQ
UBO.indirect● REQ● REQ● REQ● REQ● REQ● REQ
UBO.firstName● REQ● REQ● REQ● REQ● REQ● REQ
UBO.lastName● REQ● REQ● REQ● REQ● REQ● REQ
UBO.gender● REQ● REQ● REQ● REQ● REQ● REQ
UBO.residencyAddress.addressLine1○ OPT● REQ● REQ● REQ○ OPT● REQ
UBO.residencyAddress.addressLine2○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
UBO.residencyAddress.city○ OPT● REQ● REQ● REQ○ OPT● REQ
UBO.residencyAddress.country● REQ● REQ● REQ● REQ● REQ● REQ
UBO.residencyAddress.postalCode○ OPT● REQ● REQ● REQ○ OPT● REQ
UBO.residencyAddress.state○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
UBO.taxIdentificationNumber○ OPT○ OPT● REQ ∗● REQ○ OPT○ OPT
UBO.totalCapitalPercentage● REQ● REQ● REQ● REQ● REQ● REQ
UBO.type● REQ● REQ● REQ● REQ● REQ● REQ

∗ If the accountCountry is Germany, the UBO has 90 days to provide their Tax ID Number when opening an account. Otherwise, the account is Suspended. Share Swan's Support Center article if your UBOs have concerns.

Abbreviation

lr stands for a portion of the API field: legalRepresentative.

Field Requirements Legend

● REQ Required:Must be completed.
◐ CND Conditional:Required only in specific situations.
○ OPT Optional:Isn't required; may have a default value.
API field🇫🇷
France		🇧🇪
Belgium		🇩🇪
Germany		🇮🇹
Italy		🇳🇱
Netherlands		🇪🇸
Spain
lrPersonalAddress.addressLine1○ OPT● REQ● REQ● REQ● REQ○ OPT
lrPersonalAddress.addressLine2○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
lrPersonalAddress.city○ OPT● REQ● REQ● REQ● REQ○ OPT
lrPersonalAddress.country○ OPT● REQ● REQ● REQ● REQ○ OPT
lrPersonalAddress.postalCode○ OPT● REQ● REQ● REQ● REQ○ OPT
lrPersonalAddress.state○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT

Representative information​

Representative information is optional for all countries. Swan automatically prefills this data for companies in 🇫🇷 France when available from the RNE.

Prepare for upcoming changes

While these fields are mostly optional now, they'll become mandatory in the future. We recommend implementing them now to ensure your integration stays ahead of these requirements.

API usage: Use representatives with type: Individual for natural person representatives.

Field Requirements Legend

● REQ Required:Must be completed.
◐ CND Conditional:Required only in specific situations.
○ OPT Optional:Isn't required; may have a default value.
API field🇫🇷
France		🇧🇪
Belgium		🇩🇪
Germany		🇮🇹
Italy		🇳🇱
Netherlands		🇪🇸
Spain
representatives.type● REQ
(Individual)		● REQ
(Individual)		● REQ
(Individual)		● REQ
(Individual)		● REQ
(Individual)		● REQ
(Individual)
representatives.roles○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.firstNames○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.firstName○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.lastName○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.preferredFirstName○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.gender○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.birthDate○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.birthCity○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.birthCityPostalCode○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.birthCountryCode○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.nationality○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.residencyAddress.addressLine1○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.residencyAddress.addressLine2○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.residencyAddress.city○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.residencyAddress.country○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.residencyAddress.postalCode○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
representatives.residencyAddress.state○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT

User flow diagrams​

End-user perspective of a company account onboarding

Guides​

Use the following guides to start and complete the company onboarding process.