Get information about an onboarding

Use the accountHolderOnboardings query to get information about your onboardings, allowing you to monitor progress or share information with your end user. These operations apply to both individual and company onboardings.

Queries are highly customizable, so use the accountHolderOnboardings query to retrieve any information that will help you follow along with your users. You can also use it to retrieve onboarding IDs. Onboarding IDs are also listed on your Dashboard: look up onboardings from the Dashboard.

After getting information about an onboarding, you can update it if it's still ongoing. Refer to the guides to update an individual or company onboarding.

Prerequisites

To monitor onboarding progress, you must have at least one existing onboarding, either individual or company. The onboarding can have any status.

Deprecated queries

onboardings is deprecated. Use accountHolderOnboardings for all new integrations.

Creating onboardings with the deprecated mutations stops on 30 September 2026; the deprecated mutations and queries are removed on 31 December 2026.

For single-onboarding lookups, use accountHolderOnboarding (replaces onboarding).

Guide

1. Call the accountHolderOnboardings query.
2. Add all the query options you'd like to monitor.
   • For this exercise, add: createdAt, accountAdmin { email }, onboardingUrl, statusInfo > status, id, and totalCount.
   • Retrieving the email with the id lets you know which user an onboarding belongs to.
   • To statusInfo, also add the OnboardingInvalidStatusInfo variant with its errors list (field and errors) to see which fields block finalization.
3. You can only get information for up to 100 onboardings at a time. Add pagination to tailor your response to the information you need.

Query

Open in API Explorer

The response returns an AccountHolderOnboarding union. Use inline fragments to access type-specific fields for IndividualAccountHolderOnboarding and CompanyAccountHolderOnboarding.

query MonitorOnboarding {
  accountHolderOnboardings(first: 10) {
    edges {
      node {
        ... on IndividualAccountHolderOnboarding {
          id
          createdAt
          onboardingUrl
          statusInfo {
            status
            ... on OnboardingInvalidStatusInfo {
              __typename
              errors {
                field
                errors
              }
              status
            }
          }
          accountAdmin {
            email
          }
        }
        ... on CompanyAccountHolderOnboarding {
          id
          createdAt
          onboardingUrl
          statusInfo {
            status
            ... on OnboardingInvalidStatusInfo {
              __typename
              errors {
                field
                errors
              }
              status
            }
          }
          accountAdmin {
            email
          }
          company {
            name
          }
        }
      }
    }
    totalCount
  }
}

Payload

Review the sample payload with two onboardings: one Invalid company onboarding and one Valid individual onboarding.

{
  "data": {
    "accountHolderOnboardings": {
      "edges": [
        {
          "node": {
            "id": "$ONBOARDING_ID",
            "createdAt": "2023-06-20T14:10:39.286Z",
            "onboardingUrl": "https://api.banking.swan.io/projects/$PROJECT_ID/onboardings/$ONBOARDING_ID?lang=es",
            "statusInfo": {
              "status": "Invalid",
              "__typename": "OnboardingInvalidStatusInfo",
              "errors": [
                {
                  "field": "company.relatedIndividuals[0].birthInfo.birthDate",
                  "errors": [
                    "Missing"
                  ]
                }
              ]
            },
            "accountAdmin": {
              "email": "alberto.moreno@mimarca.io"
            },
            "company": {
              "name": "MiMarca"
            }
          }
        },
        {
          "node": {
            "id": "$ONBOARDING_ID",
            "createdAt": "2023-06-20T14:00:20.207Z",
            "onboardingUrl": "https://api.banking.swan.io/projects/$PROJECT_ID/onboardings/$ONBOARDING_ID?lang=en",
            "statusInfo": {
              "status": "Valid"
            },
            "accountAdmin": {
              "email": "sofia.ramos@mybrand.io"
            }
          }
        }
      ],
      "totalCount": 2
    }
  }
}