Audience:

DevelopersOperators

Company onboarding fields

Per-country required, optional, and conditional field requirements for company onboarding, with available options and API mapping tables.

Use this reference to determine which fields are required, optional, or conditional for each country when creating a company onboarding. For GraphQL types and validation constraints, refer to CreateCompanyAccountHolderOnboardingInput in the API reference.

Supporting documents

All requested supporting documents must be submitted to complete onboarding.

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.

Account information

Related field: accountInfo

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`country`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`name`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT

Available options

country: FRA, DEU, ESP, NLD, ITA, BEL.

Account administrator

Related field: accountAdmin

Account admin fields and sign-up

Although many accountAdmin fields are optional during onboarding, they're required when the user signs up. Swan recommends collecting and sending this information before the end of the onboarding flow.

Administrator personal information

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`email`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`firstName`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`lastName`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`nationality`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`preferredLanguage`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`taxIdentificationNumber`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`typeOfRepresentation`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ

Available options

preferredLanguage: de, en, es, fi, fr, it, nl, pt.
typeOfRepresentation: LegalRepresentative, PowerOfAttorney.

Administrator address

Related field: accountAdmin.address

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`addressLine1`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`addressLine2`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`city`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`country`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`postalCode`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`state`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT

Administrator birth information

Related field: accountAdmin.birthInfo

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`birthDate`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`city`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`country`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`postalCode`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT

Administrator US tax information

Related field: accountAdmin.unitedStatesTaxInfo

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`isUnitedStatesPerson`	◐ CND ¹	◐ CND ¹	◐ CND ¹	◐ CND ¹	◐ CND ¹	◐ CND ¹
`unitedStatesTaxIdentificationNumber`	◐ CND ²	◐ CND ²	◐ CND ²	◐ CND ²	◐ CND ²	◐ CND ²

¹ isUnitedStatesPerson is required if the companyType is SelfEmployed.

² unitedStatesTaxIdentificationNumber is required if accountAdmin.unitedStatesTaxInfo.isUnitedStatesPerson is true.

User device information

Related field: accountAdmin.userDeviceInfo

These fields are hidden from end users. Provide them through your backend integration only.

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`geoloc.lat`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`geoloc.lng`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`ip`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`userAgent`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT

Company

Related field: company

Registration and business activity

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`name`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`registrationNumber`	◐ CND ³	◐ CND ³	◐ CND ³	◐ CND ³	◐ CND ³	◐ CND ³
`registrationDate`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`legalFormCode`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`businessActivity`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`businessActivityDescription`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`monthlyPaymentVolume`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`regulatoryClassification`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`forecastYearlyIncome`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`headcount`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`tradeName`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`websites`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`signupDate`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`acquisitionChannel`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT

acquisitionChannel is hidden from end users. Provide it through your backend integration only.

³ registrationNumber is required if company.address.country is not Germany.

Available options

businessActivity

AccommodationAndFoodService, AdministrativeAndSupportServiceActivities, AgricultureForestryAndFishing, ArtsSportsAndRecreation, Construction, Education, ElectricityGasSteamAndAirConditioningSupply, ExtraterritorialOrganisationsAndBodies, FinancialAndInsuranceActivities, HouseholdEmployerAndOwnUseActivities, HumanHealthAndSocialWork, Manufacturing, MiningAndQuarrying, OtherServiceActivities, ProfessionalScientificAndTechnicalActivities, PublicAdministrationAndDefenceSocialSecurity, PublishingBroadcastingAndContentProductionAndDistribution, RealEstateActivities, TelecommunicationItAndInformationServices, TransportationAndStorage, WaterSupplySewerageWasteManagementAndRemediation, WholesaleAndRetailTrade.

monthlyPaymentVolume

LessThan10000, Between10000And50000, Between50000And100000, MoreThan100000.

regulatoryClassification

NonFinancialActive, NonFinancialPassive, FinancialInstitution.

forecastYearlyIncome

From0To500000, From500001To1000000, From1000001To5000000, MoreThan5000000.

headcount

Between1And10, Between11And50, Between51And250, MoreThan250.

acquisitionChannel

InboundOrganic, InboundReferral, OutboundSales, OutboundAccountingFirm.

Legal forms

Use the legalForms query to retrieve all legal forms for a given country, translated based on the Accept-Language header. Each legal form includes a code you can use as the legalFormCode value. If the requested language is unavailable, the query falls back to the country's default language.

Company tax information

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`taxIdentificationNumber`	◐ CND ⁴	◐ CND ⁴	◐ CND ⁴	◐ CND ⁴	◐ CND ⁴	◐ CND ⁴
`vatNumber`	○ OPT	○ OPT	○ OPT	● REQ	○ OPT	○ OPT

⁴ company.taxIdentificationNumber is required if any of the following conditions are true:

accountInfo.country is Germany, Italy, or Spain.
company.address.country is different from accountInfo.country.

Company address

Related field: company.address

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`addressLine1`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`addressLine2`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`city`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`country`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`postalCode`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`state`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT

Related field: company.relatedIndividuals

The relatedIndividuals array is required for all countries. At least one legal representative and one ultimate beneficial owner (UBO) are required to finalize a company onboarding. The same individual can fulfill both roles depending on the type.

Each individual must have a type that determines which additional fields are required:

LegalRepresentative: the individual represents the company legally.
UltimateBeneficialOwner: the individual holds ownership or control over the company.
LegalRepresentativeAndUltimateBeneficialOwner: the individual serves both roles.

Core fields

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`type`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`firstName`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`lastName`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`sex`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`nationality`	◐ CND ⁵	◐ CND ⁵	◐ CND ⁵	◐ CND ⁵	◐ CND ⁵	◐ CND ⁵
`email`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`preferredFirstName`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT

⁵ nationality is required if type is LegalRepresentative or LegalRepresentativeAndUltimateBeneficialOwner.

Available options

type: UltimateBeneficialOwner, LegalRepresentative, LegalRepresentativeAndUltimateBeneficialOwner.
sex: Male, Female, Unknown.

Address

Related field: relatedIndividuals[i].address

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`addressLine1`	◐ CND ⁶	● REQ	○ OPT	● REQ	◐ CND ⁶	● REQ
`addressLine2`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT
`city`	◐ CND ⁶	● REQ	○ OPT	● REQ	◐ CND ⁶	● REQ
`country`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`postalCode`	◐ CND ⁶	● REQ	○ OPT	● REQ	◐ CND ⁶	● REQ
`state`	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT	○ OPT

⁶ In France and the Netherlands, addressLine1, city, and postalCode are required if type is LegalRepresentative or LegalRepresentativeAndUltimateBeneficialOwner.

Birth information

Related field: relatedIndividuals[i].birthInfo

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`birthDate`	● REQ	● REQ	◐ CND ⁷	● REQ	● REQ	● REQ
`city`	● REQ	● REQ	◐ CND ⁷	● REQ	● REQ	● REQ
`country`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`postalCode`	● REQ	● REQ	◐ CND ⁷	● REQ	● REQ	◐ CND ⁷

⁷ In Germany (for birthDate, city, postalCode) and Spain (for postalCode only), these fields are required if type is LegalRepresentative or LegalRepresentativeAndUltimateBeneficialOwner.

Tax information

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`taxIdentificationNumber`	◐ CND ⁸	◐ CND ⁸	● REQ	● REQ	◐ CND ⁸	◐ CND ⁸

⁸ taxIdentificationNumber is required if all of the following are true:

type is UltimateBeneficialOwner or LegalRepresentativeAndUltimateBeneficialOwner.
One of the following:
- company.regulatoryClassification is NonFinancialPassive and relatedIndividuals[i].address.country is different from accountInfo.country.
- accountInfo.country is Germany or Italy.

United States tax information

Related field: relatedIndividuals[i].unitedStatesTaxInfo

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`isUnitedStatesPerson`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`unitedStatesTaxIdentificationNumber`	◐ CND ⁹	◐ CND ⁹	◐ CND ⁹	◐ CND ⁹	◐ CND ⁹	◐ CND ⁹

⁹ unitedStatesTaxIdentificationNumber is required if relatedIndividuals[i].unitedStatesTaxInfo.isUnitedStatesPerson is true.

Legal representative fields

The legalRepresentative object is required if type is LegalRepresentative or LegalRepresentativeAndUltimateBeneficialOwner.

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`legalRepresentative.roles`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ

UBO fields

The ultimateBeneficialOwner object is required if type is UltimateBeneficialOwner or LegalRepresentativeAndUltimateBeneficialOwner.

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`ultimateBeneficialOwner.qualificationType`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`ultimateBeneficialOwner.ownership.type`	◐ CND ¹⁰	◐ CND ¹⁰	◐ CND ¹⁰	◐ CND ¹⁰	◐ CND ¹⁰	◐ CND ¹⁰
`ultimateBeneficialOwner.ownership.totalPercentage`	◐ CND ¹⁰	◐ CND ¹⁰	◐ CND ¹⁰	◐ CND ¹⁰	◐ CND ¹⁰	◐ CND ¹⁰
`ultimateBeneficialOwner.controlTypes`	◐ CND ¹¹	◐ CND ¹¹	◐ CND ¹¹	◐ CND ¹¹	◐ CND ¹¹	◐ CND ¹¹

¹⁰ ownership.type and ownership.totalPercentage are required if qualificationType is Ownership.

¹¹ controlTypes is required if qualificationType is Control.

Available options

qualificationType: Ownership, Control, LegalRepresentative.
ownership.type: Direct, Indirect, DirectAndIndirect.
controlTypes: VotingRights, ControlViaTrustOrSimilar, RightToAppointOrRemoveBoard, ShareholderAgreementOrContract, StrategicOrManagerialInfluence.

Identity document information (Italy only)

These fields are only required for Italian accounts (accountInfo.country = ITA).

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`ultimateBeneficialOwner.identityDocumentInfo.type`	○ OPT	○ OPT	○ OPT	● REQ	○ OPT	○ OPT
`ultimateBeneficialOwner.identityDocumentInfo.number`	○ OPT	○ OPT	○ OPT	● REQ	○ OPT	○ OPT
`ultimateBeneficialOwner.identityDocumentInfo.expiryDate`	○ OPT	○ OPT	○ OPT	● REQ	○ OPT	○ OPT
`ultimateBeneficialOwner.identityDocumentInfo.issueDate`	○ OPT	○ OPT	○ OPT	● REQ	○ OPT	○ OPT
`ultimateBeneficialOwner.identityDocumentInfo.issuingAuthority`	○ OPT	○ OPT	○ OPT	● REQ	○ OPT	○ OPT

Related field: company.relatedCompanies

Use this array when a company (not an individual) serves as a legal representative for the account holder company.

Field	🇫🇷 France	🇧🇪 Belgium	🇩🇪 Germany	🇮🇹 Italy	🇳🇱 Netherlands	🇪🇸 Spain
`entityName`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`registrationCountry`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`registrationNumber`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ
`roles`	● REQ	● REQ	● REQ	● REQ	● REQ	● REQ

OAuth redirect parameters

Related field: oAuthRedirectParameters

These fields are hidden from end users. Provide them through your backend integration only.

Field	Requirement	Description
`redirectUrl`	○ OPT	URL to redirect to after the OAuth flow. If empty or not set, the user is redirected to the white label Web Banking.
`state`	○ OPT	Opaque value passed through the OAuth flow to prevent XSRF attacks. If not set, Swan fills it with the onboarding ID.

No-code Web Banking

If you use Swan's no-code Web Banking, the following fields are collected during the onboarding and sign-up flows.

accountAdmin.firstName, lastName, nationality.
accountAdmin.address: addressLine1, city, country, postalCode.
accountAdmin.birthInfo: birthDate, city, country, postalCode.
company.relatedCompanies: entityName, registrationCountry, registrationNumber, roles.

Guide

Company onboarding

Reference

Field Requirements Legend

Account information​

Account administrator​

Administrator personal information​

Administrator address​

Administrator birth information​

Administrator US tax information​

User device information​

Company​

Registration and business activity​

Company tax information​

Company address​

Related individuals​

Core fields​

Address​

Birth information​

Tax information​

United States tax information​

Legal representative fields​

UBO fields​

Identity document information (Italy only)​

Related companies​

OAuth redirect parameters​

No-code Web Banking​

Account information

Account administrator

Administrator personal information

Administrator address

Administrator birth information

Administrator US tax information

User device information

Company

Registration and business activity

Company tax information

Company address

Related individuals

Core fields

Address

Birth information

Tax information

United States tax information

Legal representative fields

UBO fields

Identity document information (Italy only)

Related companies

OAuth redirect parameters

No-code Web Banking