Finalize an onboarding

You can finalize onboardings in several ways:

• Using the API.
• Your end users can also finalize their own onboardings using the onboarding URLs you create for individuals or companies.
• If you use Swan's Web Banking interface, they can finalize their onboarding themselves with the app.

Prerequisites

To finalize an onboarding using the API:

• You must have a user access token for the user whose onboarding you're finalizing, and the user must have accessed their authentication URL at least one time.
• The onboarding status must be Ongoing (Valid).

If you need to update an onboarding before finalizing it, follow the guides for updating an individual or company onboarding.

Guide

Finalize an onboarding using the API.

1. First, retrieve the ID for the onboarding you're finalizing.
2. Call the finalizeAccountHolderOnboarding mutation.
3. Enter the onboarding ID retrieved in step 1.
4. Add optional messages to the success payload, either for validation or in case of rejection.
5. Confirm you're using the user access token to run the mutation.

Deprecated mutation

The previous finalizeOnboarding mutation is deprecated.

Deprecated mutations will be removed in December 2026.

Use finalizeAccountHolderOnboarding for all new integrations.

Mutation

Open in API Explorer

Notice the request to include the account ID, as well as the onboarding status, in the success payload. The response is an AccountHolderOnboarding union — use inline fragments to select fields for IndividualAccountHolderOnboarding and CompanyAccountHolderOnboarding.

mutation FinalizeOnboarding {
  finalizeAccountHolderOnboarding(input: { onboardingId: "$ONBOARDING_ID" }) {
    ... on FinalizeAccountHolderOnboardingSuccessPayload {
      __typename
      onboarding {
        ... on IndividualAccountHolderOnboarding {
          id
          account {
            id
          }
          statusInfo {
            status
          }
        }
        ... on CompanyAccountHolderOnboarding {
          id
          account {
            id
          }
          statusInfo {
            status
          }
        }
      }
    }
    ... on OnboardingNotFoundRejection {
      __typename
    }
    ... on OnboardingAlreadyFinalizedRejection {
      __typename
    }
    ... on OnboardingNotReadyForFinalizationRejection {
      __typename
    }
  }
}

Payload

Notice the ID for the newly-created account and the onboarding status Finalized. Both union types return the same field structure; the example below shows an individual onboarding.

{
  "data": {
    "finalizeAccountHolderOnboarding": {
      "__typename": "FinalizeAccountHolderOnboardingSuccessPayload",
      "onboarding": {
        "id": "$ONBOARDING_ID",
        "account": {
          "id": "$NEW_ACCOUNT_ID"
        },
        "statusInfo": {
          "status": "Finalized"
        }
      }
    }
  }
}