Company onboarding fields

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 are required when the user signs up. We recommend collecting and sending this information before the end of the onboarding flow.

If you provide accountAdmin information through the API and include the onboarding ID in the OAuth redirect parameters, Swan pre-fills this information during the user sign-up 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 individuals

Related field: company.relatedIndividuals

The relatedIndividuals array is required for all countries. At least one LegalRepresentative and one UltimateBeneficialOwner are required to finalize a company onboarding. A single individual can fulfill both roles by setting type to LegalRepresentativeAndUltimateBeneficialOwner.

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 both represents the company legally and holds ownership or control.

Individual personal information

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.

Individual address

Related field: company.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.

Individual birth information

Related field: company.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 relatedIndividuals[i].type is LegalRepresentative or LegalRepresentativeAndUltimateBeneficialOwner.

Individual tax information

Related field: company.relatedIndividuals[i].taxIdentificationNumber

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

⁸ taxIdentificationNumber is required if relatedIndividuals[i].type is UltimateBeneficialOwner or LegalRepresentativeAndUltimateBeneficialOwner and at least one of the following is true:

• accountInfo.country is Germany or Italy.
• company.regulatoryClassification is NonFinancialPassive and relatedIndividuals[i].address.country is different from accountInfo.country.

Individual US tax information

Related field: company.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

Related field: company.relatedIndividuals[i].legalRepresentative

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

Ownership and control

Related field: company.relatedIndividuals[i].ultimateBeneficialOwner

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)

Related field: company.relatedIndividuals[i].ultimateBeneficialOwner.identityDocumentInfo

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 companies

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	Description
redirectUrl	URL to redirect to after the OAuth flow.
state	Opaque value passed through the OAuth flow.

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.

API mapping

Use this table to map fields from the deprecated API to the new API.

Account

Deprecated field	New field
accountCountry	accountInfo.country
accountName	accountInfo.name

Account administrator

Deprecated field	New field
legalRepresentativePersonalAddress.addressLine1	accountAdmin.address.addressLine1
legalRepresentativePersonalAddress.addressLine2	accountAdmin.address.addressLine2
legalRepresentativePersonalAddress.city	accountAdmin.address.city
legalRepresentativePersonalAddress.country	accountAdmin.address.country
legalRepresentativePersonalAddress.postalCode	accountAdmin.address.postalCode
legalRepresentativePersonalAddress.state	accountAdmin.address.state
-	accountAdmin.birthInfo.birthDate
-	accountAdmin.birthInfo.city
-	accountAdmin.birthInfo.country
-	accountAdmin.birthInfo.postalCode
email	accountAdmin.email
-	accountAdmin.firstName
-	accountAdmin.lastName
-	accountAdmin.nationality
language	accountAdmin.preferredLanguage
-	accountAdmin.taxIdentificationNumber
typeOfRepresentation	accountAdmin.typeOfRepresentation
-	accountAdmin.unitedStatesTaxInfo.isUnitedStatesPerson
-	accountAdmin.unitedStatesTaxInfo.unitedStatesTaxIdentificationNumber
-	accountAdmin.userDeviceInfo.geoloc.lat
-	accountAdmin.userDeviceInfo.geoloc.lng
-	accountAdmin.userDeviceInfo.ip
-	accountAdmin.userDeviceInfo.userAgent

Company

Deprecated field	New field
residencyAddress.addressLine1	company.address.addressLine1
residencyAddress.addressLine2	company.address.addressLine2
residencyAddress.city	company.address.city
residencyAddress.country	company.address.country
residencyAddress.postalCode	company.address.postalCode
residencyAddress.state	company.address.state
acquisitionChannel	company.acquisitionChannel
businessActivityDescription	company.businessActivityDescription
-	company.businessActivity
-	company.businessActivityCode
companyType	company.companyType
-	company.forecastYearlyIncome
-	company.headcount
-	company.legalFormCode
monthlyPaymentVolume	company.monthlyPaymentVolume
name	company.name
-	company.registrationDate
registrationNumber	company.registrationNumber
-	company.regulatoryClassification
-	company.signupDate
taxIdentificationNumber	company.taxIdentificationNumber
tradeName	company.tradeName
vatNumber	company.vatNumber
-	company.websites

Related individuals (replaces representatives and UBOs)

The new company.relatedIndividuals array replaces both representatives and individualUltimateBeneficialOwners from the deprecated API.

Deprecated field	New field
representatives[i].firstName	company.relatedIndividuals[i].firstName
representatives[i].lastName	company.relatedIndividuals[i].lastName
representatives[i].gender	company.relatedIndividuals[i].sex
representatives[i].nationality	company.relatedIndividuals[i].nationality
representatives[i].type	company.relatedIndividuals[i].type
representatives[i].roles	company.relatedIndividuals[i].legalRepresentative.roles
representatives[i].preferredFirstName	company.relatedIndividuals[i].preferredFirstName
-	company.relatedIndividuals[i].email
representatives[i].residencyAddress.*	company.relatedIndividuals[i].address.*
representatives[i].birthDate	company.relatedIndividuals[i].birthInfo.birthDate
representatives[i].birthCity	company.relatedIndividuals[i].birthInfo.city
representatives[i].birthCountryCode	company.relatedIndividuals[i].birthInfo.country
representatives[i].birthCityPostalCode	company.relatedIndividuals[i].birthInfo.postalCode
individualUltimateBeneficialOwners[i].direct	company.relatedIndividuals[i].ultimateBeneficialOwner.ownership.type
individualUltimateBeneficialOwners[i].indirect	(see ownership.type)
individualUltimateBeneficialOwners[i].totalCapitalPercentage	company.relatedIndividuals[i].ultimateBeneficialOwner.ownership.totalPercentage
-	company.relatedIndividuals[i].ultimateBeneficialOwner.qualificationType
-	company.relatedIndividuals[i].ultimateBeneficialOwner.controlTypes
individualUltimateBeneficialOwners[i].identityDocumentDetails.*	company.relatedIndividuals[i].ultimateBeneficialOwner.identityDocumentInfo.*

Related companies

The company.relatedCompanies array replaces entries in the deprecated representatives array where type was Company. The data is restructured as a dedicated top-level field with renamed fields.