Create an individual onboarding link

There are two methods you can use to create individual onboarding links.

• Run an API mutation to create a unique onboarding link for each future individual account holder. Use this method for hybrid onboarding too, where you create the onboarding by API and the account holder completes it in Swan's no-code interface.
• Use a public link from your Dashboard to share one onboarding link with all of your users.

Public links toggle and the onboarding URL

With the current onboarding API, the onboardingUrl is only returned in the create or update mutation response when the Public links toggle is enabled. If you create onboardings with the API and let your users complete them through Swan's onboarding form, enable this toggle before going live. You can find it under Settings > Onboarding in the Onboarding links section.

Public onboarding links

Use public links with caution. Those with fraudulent intent can use these public links to complete multiple onboardings, and if this happens undetected, they'll have multiple accounts in your project.

Unique links using the API

Create a unique individual onboarding link for each user with the API.

1. Call the createIndividualAccountHolderOnboarding mutation.
2. Enter information for all required API fields for the account country, as noted in country requirements for individual accounts.
3. Include optional fields as needed for your use case (such as accountInfo.name or oAuthRedirectParameters).
4. Add optional messages to the success payload, either for validation or in case of rejection.

Deprecated mutation

The previous onboardIndividualAccountHolder mutation is deprecated.

Onboarding API v1 is deprecated. After 30 September 2026, you can't create new v1 onboardings.

Deprecated v1 queries and mutations stay available until 31 December 2026, so you can finish any v1 onboarding started before 30 September 2026.

Use createIndividualAccountHolderOnboarding for all new integrations.

Mutation

Open in API Explorer

mutation CreateIndividualOnboarding {
  createIndividualAccountHolderOnboarding(
    input: {
      accountInfo: {
        country: FRA
      }
      accountAdmin: {
        email: "malika.ngomao@mybrand.io"
        employmentStatus: Employee
        preferredLanguage: fr
        monthlyIncome: Between3000And4500
        address: {
          addressLine1: "123 avenue de Paris"
          city: "Paris"
          country: "FRA"
          postalCode: "75000"
        }
        unitedStatesTaxInfo: {
          isUnitedStatesPerson: false
        }
      }
    }
  ) {
    ... on CreateIndividualAccountHolderOnboardingSuccessPayload {
      __typename
      onboarding {
        id
        statusInfo {
          status
          ... on OnboardingInvalidStatusInfo {
            errors {
              field
              errors
            }
          }
        }
      }
    }
  }
}

Payload

The success payload returns the onboarding id and current status. For this France example, the onboarding comes back Valid, so it's ready to finalize.

The example also includes the OnboardingInvalidStatusInfo fragment. If a required field is missing, the response lists each one under errors, so you can see exactly what to fix before finalizing.

{
  "data": {
    "createIndividualAccountHolderOnboarding": {
      "__typename": "CreateIndividualAccountHolderOnboardingSuccessPayload",
      "onboarding": {
        "id": "4df0a6af-b67f-48a3-a8bb-27193b6946a1",
        "statusInfo": {
          "status": "Valid"
        }
      }
    }
  }
}

Public link using the Dashboard

1. On your Swan Dashboard, go to Settings > Onboarding.
2. In the Onboarding links section, toggle Public links to on.
3. Notice the links that appear for individuals and companies for each account country.