Customers Onboarding

Overview

To issue cards or open accounts, you must first register and verify your customers. Altery provides two primary onboarding paths depending on your existing integration with SumSub:

1. Standard API: You collect the customer's initial registration data, and the customer provides supporting documents through SumSub.
2. SumSub Import: If you already use SumSub for KYC, you can share an existing applicant with Altery.

Prerequisites

Before beginning the onboarding process, ensure you have an active API key with permissions to manage corporate customers.

[!IMPORTANT] A customer is only eligible for card issuance once their lifecycle status is Active and their verificationStatus is Verified.

Registration Paths

Both onboarding paths use the same endpoint:

Endpoint POST /v1/corporate-customers

The request body depends on the onboarding path you use.

Path 1: Standard API (Direct Collection)

Use this path if you are collecting data through your own UI or a custom flow.

Example Request

{
  "externalId": "acb123",
  "agreements": [
    { "type": 3, "acceptedAt": "2025-10-10T13:01:02.003Z" }
  ],
  "personal": {
    "phone": "+442071234567",
    "firstName": "John",
    "lastName": "Smith",
    "dateOfBirth": "1999-11-11",
    "citizenshipCountry": "GBR",
    "residenceCountry": "GBR"
  },
  "address": {
    "postcode": "12345",
    "state": "RegState",
    "town": "RegTown",
    "street": "RegStreet",
    "subStreet": "RegSubStreet",
    "apartment": "11"
  },
  "questionnaire": {
    "purposeOfOpeningAccount": "23",
    "sourcesOfFunds": ["14"],
    "monthlyTurnover": "110",
    "taxResidences": [
        { "countryIsoCodeAlpha3": "GBR", "taxIdNumber": "1234567890" }
    ]
  }
}    

Required request fields:

Handling UserDataRequired Status

If the customer's verificationStatus is UserDataRequired, it means additional information or document verification (like a liveness check) is needed. In this state, Altery provides direct links to the SumSub verification flow.

When you poll the customer status via GET /v1/corporate-customers/{customerId}, look for the realTimeUserInput block in the response:

{
  "status": "Created",
  "verificationStatus": "UserDataRequired",
  "realTimeUserInput": {
    "sumSubExternalWebSdkLink": "https://in.sumsub.com/websdk/p/...",
    "sumSubSdkAccessToken": "_act-sbx-jwt-..."
  },
  ...
}

Path 2: SumSub Import via Share Token (Corporate Card Program)

Use this path if the customer has already completed KYC in your own SumSub instance.

Step 1: Generate a Share Token

Refer to SumSub's Share Token Documentation. Ensure the forClientId is set to recary.

Step 2: Create Customer via Altery API POST /v1/corporate-customers

{
  "workflow": "AuthorizedUser",
  "externalId": "User-03",
  "sumSubImport": {
    "token": "_act-sbx-jwt-eyJh****GYiLCJ1cmwiOiJodHRwczovL2FwaS5zdW1zdWIuY29tIn0."
  },
  "personal": {
    "phone": "+442411008041",
    "firstName": "Simon-aa",
    "lastName": "KRAUSEsmith",
    "dateOfBirth": "2000-01-01",
    "residenceCountry": "GBR"
  }
}

[!TIP] Ensure your SumSub applicant level includes at least:

• Government-issued ID document
• Biometric verification confirmation (liveness check)
• Validation check: ID document and liveness detection
• Face match check: the face in the selfie/liveness check must match the face on the identity document

Required request fields:

personal object for SumSub Import

The personal object is required for the SumSub Import path and must contain the customer details used to create the Altery customer record.

Do not send agreements, address, or questionnaire for the SumSub Import path.

Monitoring Verification Progress

Customer verification is an asynchronous process. You can monitor the progress through webhooks (recommended) or on-demand API calls.

1. Webhooks (Real-Time)

Subscribe to the following events in the Real-Time Integration overview:

• CustomerStatusChanged: Updates on lifecycle and verification states.
• CustomerIdDocumentAdded: Confirmation of document uploads.
• CustomerVerificationProcessed: Final KYC outcome.

2. API Polling (On-Demand)

GET /v1/corporate-customers/{customerId}

Expected Response States:

• status: Created -> Active
• verificationStatus: UserDataRequired -> InVerification -> Verified (or Rejected)

For detail on state transitions, see Status Models.

Rate limits

Below limits are applied on IP address:

Expected HTTP response when the limit is reached:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"errorCode":429,"errorMsgs":["Too many requests. Please try again later."]}