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.

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.

After getting information about an onboarding, you might want to update that onboarding if it is 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.

Deprecated mutations will be removed in 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.
   • To statusInfo > status, add a rejection as well: OnboardingInvalidStatusInfo with errors, field, and status.
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
    }
  }
}