Onboard a client

Create an individual or business client with the BaaS API, submit the required verification information, and wait for approval before opening an account.

Before you start

All API paths below are relative to the base URL supplied privately for your integration.

Obtain an access token with POST /auth/token, sending your username and secretKey. Send Authorization: Bearer <accessToken> on the requests below. Keep credentials on your server; do not embed them in browser or mobile applications.

1. Retrieve the current onboarding schema

Call GET /baas/Clients/fields?type=individual or GET /baas/Clients/fields?type=business using your integration's token.

The response is an OpenAPI 3.0 Schema Object for your brand. Read properties, required, enum, nested objects, array items, and array limits recursively. Use the actual field names returned by this endpoint rather than copying a payload from another integration.

For document arrays, also read x-document-requirements. Each group specifies its allowed document types and minimum/maximum counts. Read x-document-upload-policy for the maximum file size and allowed MIME types. These requirements may change when your onboarding configuration changes.

For client generation, GET /baas/openapi.json returns the authenticated brand's full API definition, including its configured client-creation schemas. The public API reference is shared across integrations and cannot contain one fixed onboarding payload for every brand.

2. Upload any required files

For each required file, call POST /baas/Documents?type=individual or POST /baas/Documents?type=business with multipart/form-data and a file part. Use the same client type as the creation schema.

The response is { "id": "<file UUID>" }. Place that UUID in the corresponding file-reference field of the onboarding payload. Upload separate files separately. Follow the schema's document classification, groups, sides, and related-person structure; do not substitute a local path or base64 content for a UUID.

This endpoint uploads onboarding documents. Transfer-document endpoints serve a different purpose.

3. Create the applicant

Submit POST /baas/Clients with a JSON object containing:

type: individual or business;

a stable externalId from your system;

all fields required by the current schema, including any uploaded file references and related-person data.

Send the fields directly in the request body, without a data wrapper. The brand is determined by your access token.

Store the returned id together with your externalId. A successful response means the creation request was accepted; it does not mean verification is complete or that an account may already be opened.

4. Complete verification and wait for approval

Complete the KYC/KYB steps agreed for your integration. For integrations requiring manual approval, send the returned ID to our team and ask us to review and approve the applicant.

Poll GET /baas/Clients/{id}/state. The response contains the id and state; JSON state values include pending, active, creatingFailed, blocked, and closed. Do not open an account while the client is pending or after a failed or blocked result.

If webhook delivery has been configured for your integration, you can also handle onboardingCompleted and onboardingFailed events. Register your callback using POST /baas/Webhooks/subscription and coordinate webhook signing-secret setup with our team. Polling remains available without webhooks.

5. Open accounts after activation

Only when the client is active, call POST /baas/Accounts with externalId, clientId, currency, and paymentMethod.

Currency/payment-method pairs must be enabled for your brand. A payment method appearing in the shared API enum does not mean your integration can use it. An unavailable pair returns 422 ACCOUNT_CREATION_UNAVAILABLE.

Account creation and transaction permissions are configured separately. Confirm the required incoming/outgoing payments, internal/self transfers, and currency exchange with our team before testing them.

Retries and configuration changes

Keep the same externalId when retrying the same applicant. For a document-bearing submission, preserve the accepted input and file references rather than changing the payload under the same identifier.

If creation returns 409 KYC_CONFIGURATION_CHANGED, reload the current creation schema, adjust the unaccepted request to match it, and retry with the same external ID. Inspect other conflict responses before retrying; do not treat every 409 as success.

Before you start#

1. Retrieve the current onboarding schema#

2. Upload any required files#

3. Create the applicant#

4. Complete verification and wait for approval#

5. Open accounts after activation#