Migrate to the current onboarding API

Swan's current onboarding API replaces the previous one with cleaner naming, structured inputs, typed responses, and improved data collection.

This guide walks you through migrating your integration.

Deprecation timeline

Previous onboarding mutations and queries are deprecated and will be removed at the end of September 2026.

Migrate to the current API before this date to avoid disruption.

What's changing

The current API introduces changes across naming, input structure, data requirements, response types, and registry data handling.

Review the full comparison on the account onboarding enhancements page, which covers:

• Mutation and query renames (for example, onboardIndividualAccountHolder becomes createIndividualAccountHolderOnboarding).
• Nested input structure with accountInfo, accountAdmin, and company objects instead of flat inputs.
• Typed response types (IndividualAccountHolderOnboarding, CompanyAccountHolderOnboarding) instead of the generic Onboarding type.
• New required fields for enhanced risk assessment and compliance.
• Explicit registry data retrieval with companyInfoRegistryData instead of automatic population.

Field mapping

For a complete field-by-field comparison between the previous and current APIs, refer to the field reference pages:

• Individual onboarding fields
• Company onboarding fields

These pages include API mapping tables that show each previous field alongside its current equivalent. The mapping tables will be available until the previous mutations are retired at the end of September 2026.

Coexistence

The previous and current onboarding APIs can run in parallel in the same project. You don't need to migrate all at once.

• New onboardings can use either the previous or current mutations.
• In-progress onboardings created with the previous API can continue to be updated and finalized using the previous mutations.
• You can create new onboardings with the current API while still managing existing onboardings through the previous API.

Migration steps

Follow these steps to migrate your integration. Test thoroughly in Sandbox before switching in Live.

Step 1: Update mutation names

Replace each deprecated mutation and query with its current equivalent.

Previous mutation or query	Current mutation or query
onboardIndividualAccountHolder	createIndividualAccountHolderOnboarding
unauthenticatedOnboardPublicIndividualAccountHolder	createPublicIndividualAccountHolderOnboarding
updateIndividualOnboarding	updateIndividualAccountHolderOnboarding
unauthenticatedUpdateIndividualOnboarding	updatePublicIndividualAccountHolderOnboarding
onboardCompanyAccountHolder	createCompanyAccountHolderOnboarding
unauthenticatedOnboardPublicCompanyAccountHolder	createPublicCompanyAccountHolderOnboarding
updateCompanyOnboarding	updateCompanyAccountHolderOnboarding
unauthenticatedUpdateCompanyOnboarding	updatePublicCompanyAccountHolderOnboarding
finalizeOnboarding	finalizeAccountHolderOnboarding
onboarding (query)	accountHolderOnboarding
onboardingInfo (public query)	publicAccountHolderOnboarding
onboardings (list query)	accountHolderOnboardings

Step 2: Update input structure

The current API uses a nested input structure instead of flat inputs.

For individual onboardings, group fields into two objects:

• accountInfo: account-level details such as country and name.
• accountAdmin: the individual's personal information such as email, employmentStatus, and monthlyIncome.

For company onboardings, group fields into three objects:

• accountInfo: account-level details such as country and name.
• accountAdmin: personal information for the person opening the account.
• company: company details including registrationNumber, name, legalForm, and relatedIndividuals.

Refer to the individual and company creation guides for complete mutation examples.

Step 3: Handle new required fields

The current API collects additional data for risk assessment and compliance. Some fields that were optional or didn't exist in the previous API are now required.

Check the field reference pages for the complete list of requirements by country:

• Individual onboarding fields
• Company onboarding fields

Step 4: Update response handling

The current API returns typed responses instead of the generic Onboarding type.

• Individual mutations return IndividualAccountHolderOnboarding.
• Company mutations return CompanyAccountHolderOnboarding.
• The finalizeAccountHolderOnboarding mutation returns a FinalizeAccountHolderOnboardingPayload. On success, the payload contains a FinalizeAccountHolderOnboardingSuccessPayload with an onboarding field of type AccountHolderOnboarding (union).

Update your response parsing to handle the new type names and field structure.

Step 5: Update registry data handling (French company onboardings)

This step applies only if you onboard French companies. If you don't, skip to Step 6.

Previously, Swan auto-populated empty onboarding fields with data from the French National Business Register (RNE). The current API doesn't.

Instead, call the companyInfoRegistryData query with the company's registrationNumber and residencyAddressCountry, then pass the results to the create or update mutation.

Step 6: Test in Sandbox

Validate your updated integration in Sandbox before going live. Refer to the testing checklist for key scenarios.

Step 7: Switch in Live

After successful Sandbox testing, deploy your changes to your Live environment.

In-progress onboardings

The migration doesn't affect in-progress onboardings created with the previous API.

• Continue to update and finalize them using the previous mutations.
• They don't need to be recreated with the current API.
• Once finalized, any future onboardings should use the current API.

After the previous mutations are removed at the end of September 2026, you'll no longer be able to update or finalize onboardings through them. Make sure your integration is fully migrated by then.

Deprecation timeline

Date	Event
March 2026	Current onboarding API available in beta.
April 2026	Documentation updated. Previous mutations marked as deprecated across all guide pages.
End of September 2026	Previous mutations and queries removed.

Testing checklist

Before going live with the current API, validate the following scenarios in Sandbox:

1. Create an individual onboarding with all required fields for your target countries.
2. Create a company onboarding with relatedIndividuals (at least one legal representative and one UBO).
3. Update an existing onboarding to confirm nested input structure works correctly.
4. Finalize an onboarding and confirm the typed response (IndividualAccountHolderOnboarding or CompanyAccountHolderOnboarding).
5. For French companies: call companyInfoRegistryData and use the results to pre-fill the create mutation.
6. Test public onboarding mutations if you use public onboarding links.
7. Confirm that webhook payloads for Onboarding.Created and Onboarding.Updated still match your expectations.
8. Verify error handling for new rejection types (OnboardingNotFoundRejection, OnboardingAlreadyFinalizedRejection, OnboardingNotReadyForFinalizationRejection).