Errors and lifecycle

Response shape

On success the body is the data object. There is no envelope — the HTTP status tells you it succeeded.

Success — 201 from create

{
  "userId": "310d2801-9260-4279-81db-f2e13edf7f47",
  "userType": "INDIVIDUAL",
  "status": "INITIATED",
  "sumsubApplicantId": "6aa198eccff9e09439ab321c"
}

On failure you get a flat object naming the problem: code is the HTTP status, message the specific reason, and name the operation that failed.

One problem

{
  "code": "409",
  "message": "Cannot delete a customer that holds a balance",
  "name": "PartnerOnboardingDelete failed to process"
}

When several things are wrong at once they arrive together, one entry each, and nothing is created.

Several problems

{
  "errors": [
    { "code": "400", "message": "firstName must be at most 100 characters", "name": "PartnerOnboardingCreate failed to process" },
    { "code": "400", "message": "country must be an ISO 3166-1 alpha-3 code", "name": "PartnerOnboardingCreate failed to process" }
  ]
}

Two exceptions to the flat shape. A 503 returns the errors[] form, and a 429 keeps the older envelope — { data, code, message, status, errors }. Parse defensively: check for errors first, then fall back to the flat fields.

Status codes

Code	Meaning
`201`	Customer created or imported
`200`	Success — get, list, update, kyc-link, document upload, delete
`400`	Validation failed. Nothing is written
`401`	Missing or invalid `API-KEY`
`403`	Key lacks `onboarding`, customer belongs to another partner, or the country is restricted
`404`	Customer or owner not found — including one that was deleted
`405`	Wrong HTTP method for the path
`409`	Conflict — see below
`413`	A document exceeds the 2 MB per-file limit
`415`	Non-JSON content type on a JSON endpoint
`429`	Rate limit exceeded
`500`	Downstream failure. The whole operation is rolled back — retry
`503`	Downstream timed out. Retryable

A 503 on create is safe to retry with the same body — Endl reconciles rather than creating a duplicate.

The three conflicts

409 means one of exactly three things:

A KYC link for an already-verified customer

This customer's KYC is already completed; a new verification link is not needed

Changing a locked identity field after completion

This customer's KYC is completed; verified identity fields can no longer be changed

Deleting a customer that holds a balance

Cannot delete a customer that holds a balance — the amount is never disclosed. Clear the balance first.

Verification lifecycle

Status	Meaning
`INITIATED`	Created; documents not yet submitted
`PENDING`	Documents submitted; verification in progress
`COMPLETED`	Approved
`REJECTED`	Rejected

For an individual, uploading the photo ID auto-submits and moves the customer to PENDING. For a business, submission waits until the company documents and every owner’s documents are uploaded.

Identity locks on completion

Once a customer reaches COMPLETED, the fields the provider verified can no longer be changed — firstName, lastName, phone, dateOfBirth, country, nationality, gender, placeOfBirth, tin, taxResidenceCountry and the address. Touching any of them returns 409 and nothing is written. Database-only fields (currency, countryId, currencyId) stay editable.

Validation reference

Case	HTTP	Message
Email missing or malformed	`400`	`email is required` / `email must be a valid email address`
First or last name missing	`400`	`firstName is required`
Name over 100 characters	`400`	`firstName must be at most 100 characters`
Country not ISO alpha-3	`400`	`country must be an ISO 3166-1 alpha-3 code (e.g. ARE)`
Date of birth bad, future, or under 18	`400`	`Date of birth must be a valid date in DD-MM-YYYY format`
Gender outside `M`/`F`	`400`	`gender must be one of M, F`
Bad questionnaire option	`400`	`profileDetails.occupation must be one of the allowed options (got 'X')`
Missing questionnaire item	`400`	`profileDetails.expectedMonthlyVolume is required`
Missing custom field	`400`	`custom field 'whatsappNumber' is required`
Unknown custom field	`400`	`unknown custom field 'foo'`
Duplicate email	`400`	`Duplicate email`
No beneficiaries on a business	`400`	`At least one beneficiary is required`
`shareSize` out of range or summing over 100	`400`	`beneficiaries[0].shareSize must be between 0 and 100`
File is not really an image or PDF	`400`	`Document content is not a valid JPEG, PNG, or PDF`
Bad `idDocType` for an individual	`400`	`idDocType must be one of PASSPORT, ID_CARD, DRIVERS_LICENSE, RESIDENCE_PERMIT, SELFIE`
Malformed share token	`400`	`shareToken is not a valid share token`
Restricted country	`403`	`Onboarding is not permitted for this country`
Wrong HTTP method	`405`	`HTTP method PUT is not supported for this endpoint`
File over 2 MB	`413`	`File exceeds the maximum upload size of 2 MB`
Wrong content type	`415`	`Content type text/plain is not supported; use application/json`
Rate limited	`429`	`Rate limit exceeded, please retry later`
Downstream timeout	`503`	`Service temporarily unavailable, please try again`

A few messages read generically — a reused share token returns plain Bad Request, and a missing customer returns Not found. The status code plus name tell you which operation failed.

Introduction

Endpoints

Errors and lifecycle

Response shape

Status codes

The three conflicts

Verification lifecycle

Identity locks on completion

Validation reference

​Response shape

​Status codes

​The three conflicts

​Verification lifecycle

​Identity locks on completion

​Validation reference

Response shape

Status codes

The three conflicts

Verification lifecycle

Identity locks on completion

Validation reference