Individual (KYC)

Onboarding a person takes four calls: create them, then upload a photo ID, a selfie and a proof of address. Everything else is optional.

Create the customer

POST /api/v0/customer with identity fields, the questionnaire and custom fields. The whole payload is validated first — one bad field and nothing is created.

Required fields

{
  "userType": "INDIVIDUAL",
  "email": "jane.doe@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "dateOfBirth": "01-01-1990",
  "country": "ARE",
  "addressLine1": "Office 1201, Marina Plaza",
  "city": "Dubai",
  "state": "Dubai",
  "questionnaire": {
    "sections": {
      "profileDetails": {
        "items": {
          "occupation": { "value": "15-1132" },
          "annualSalary": { "value": "50000_100000" },
          "accountPurpose": { "value": "payroll" },
          "expectedMonthlyVolume": { "value": "0_10000" }
        }
      },
      "birthNationalityTaxI": {
        "items": {
          "countryOfBirth": { "value": "ARE" },
          "cityOfBirth": { "value": "Dubai" },
          "nationalities": { "values": ["ARE"] },
          "taxRegistrationsOuts": { "value": "no" }
        }
      }
    }
  },
  "customFields": {
    "nationalIdNumber": "784-1990-1234567-1",
    "whatsappNumber": "+971500000000"
  }
}

Returns 201 with the userId. Save it — every later call uses it.

{
  "userId": "cus_PWEhqXkPKpWXiFd96jGq",
  "userType": "INDIVIDUAL",
  "status": "INITIATED"
}

Upload the photo ID

POST /api/v0/customer/{userId}/documents as multipart/form-data.

curl -X POST https://api-sandbox.endl.io/api/v0/customer/$USER_ID/documents \
  -H "Api-Version: 2026-09.1" \
  -H "API-KEY: $ENDL_API_KEY" \
  -F "document=@passport.jpg;type=image/jpeg" \
  -F "idDocType=PASSPORT" \
  -F "country=ARE"

Nothing is submitted yet. The response stays SUBMITTED, and missing lists the steps still outstanding:

{ "accepted": true, "status": "SUBMITTED", "missing": ["SELFIE", "PROOF_OF_RESIDENCE"] }

Upload the selfie

Same endpoint, idDocType=SELFIE.

curl -X POST https://api-sandbox.endl.io/api/v0/customer/$USER_ID/documents \
  -H "Api-Version: 2026-09.1" \
  -H "API-KEY: $ENDL_API_KEY" \
  -F "document=@selfie.png;type=image/png" \
  -F "idDocType=SELFIE" \
  -F "country=ARE"

{ "accepted": true, "status": "SUBMITTED", "missing": ["PROOF_OF_RESIDENCE"] }

Upload the proof of address

Same endpoint, idDocType=UTILITY_BILL — a utility bill or bank statement. It is checked against the residential address you sent on create.

curl -X POST https://api-sandbox.endl.io/api/v0/customer/$USER_ID/documents \
  -H "Api-Version: 2026-09.1" \
  -H "API-KEY: $ENDL_API_KEY" \
  -F "document=@utility-bill.pdf;type=application/pdf" \
  -F "idDocType=UTILITY_BILL" \
  -F "country=ARE"

This is the last required step, so the customer is submitted for review automatically — status moves to PENDING and missing is omitted:

{ "accepted": true, "status": "PENDING" }

Submission waits for all three document steps — identity (passport, ID card, driving licence or residence permit), selfie, and proof of address. The customer is submitted once the last of them is uploaded.

Identity fields

Field	Required	Notes
`userType`	Yes	`INDIVIDUAL`. Missing → `ERRCUS_1000`. Optional only on an import.
`email`	Yes	Unique across all Endl users, not only your customers. Checked case-insensitively and stored lower-cased. A duplicate is `400 ERRCUS_1600`. Immutable after creation.
`firstName` / `lastName`	Yes	Maximum 100 characters each.
`dateOfBirth`	Yes	`DD-MM-YYYY`, with no leading or trailing spaces. A real past date, and at least 18 years ago. A value with surrounding spaces currently fails with a `500` instead of a `400`.
`country`	Yes	ISO 3166-1 alpha-3 — `ARE`, `GBR`, `USA`.
`questionnaire`	Yes	See the questionnaire reference.
`customFields`	Yes	`nationalIdNumber` and `whatsappNumber` are required.
`addressLine1`, `city`, `state`	Yes	The residential address — the proof-of-address document is checked against it.
`postalCode`	Yes, except `ARE` and `HKG`	Countries with no postal-code system don’t need it. Format-checked for `USA`, `DEU`, `IND` and `GBR`; for other countries any value is accepted.
`phone`	No	E.164 format — a leading `+` then 8–15 digits, e.g. `+971500000000`. Unique across all customers.
`nationality`	No	ISO alpha-3. Defaults to `country`.
`gender`	No	`M` or `F`.
`tin`, `taxResidenceCountry`, `placeOfBirth`	No	Extra identity fields.
`addressLine2`	No	Second line of the address.
`externalReferenceId`	No	Your own reference. Accepted but neither stored nor returned. Keep your own mapping to the returned `userId`.

Document types

idDocType is validated — a value outside this list returns 400. PASSPORT · ID_CARD · DRIVERS · RESIDENCE_PERMIT · SELFIE · UTILITY_BILL UTILITY_BILL is the proof of address — a utility bill or bank statement. An invalid value is 400 ERRCUS_1406: idDocType must be one of PASSPORT, ID_CARD, DRIVERS, RESIDENCE_PERMIT, SELFIE, UTILITY_BILL.

DRIVERS_LICENSE is now DRIVERS — the value the verification provider expects. DRIVERS_LICENSE is still accepted as an alias so existing integrations keep working, but it is stored and returned as DRIVERS, for example in documents[].docType.

side is not validated. FRONT and BACK are meaningful only for two-sided documents (ID_CARD, DRIVERS). For a passport or selfie it is ignored, and any value — even nonsense — is accepted and passed through.

Files must be JPEG, PNG or PDF, at most 5 MB. Content is sniffed, not trusted by extension: a text file renamed .jpg returns 400.

Hosted verification instead of uploads

If you would rather not handle documents yourself, generate a KYC link and send the customer to it.

{
  "url": "https://in.sumsub.com/websdk/p/sbx_example",
  "userId": "cus_PWEhqXkPKpWXiFd96jGq",
  "ttlSeconds": 3600,
  "expiresAt": "2026-09-09T18:36:03.123456Z"
}

The link expires — ttlSeconds is one hour. Requesting one for an already verified customer returns 409 ERRCUS_1603.

Importing an already-verified customer

Pass a shareToken instead of the identity payload. Only email is required alongside it; identity comes from the token. country is validated (ERRCUS_1013), checked against country restrictions (ERRCUS_1605) and stored. firstName and lastName are stored and returned by GET. All other identity fields are ignored and listed in warnings. Note: warnings currently still lists firstName, lastName and country as well. The 201 status on an import is the copied review outcome — COMPLETED, REJECTED or PENDING — not INITIATED.

Request

{ "shareToken": "_act-sbx-jwt-…", "email": "jane.imported@example.com" }

Share tokens are single-use per partner. Reusing one returns 400. Use a fresh token each time.

Deleting

Delete is a soft delete. The customer stops appearing in listings and a later GET returns 404. The email is released, so the same person can be onboarded again. A customer holding a balance cannot be deleted — that returns 409 ERRCUS_1606, and the amount is never disclosed.

Introduction

Endpoints

Identity fields

Document types

Hosted verification instead of uploads

Importing an already-verified customer

Deleting

​Identity fields

​Document types

​Hosted verification instead of uploads

​Importing an already-verified customer

​Deleting

Identity fields

Document types

Hosted verification instead of uploads

Importing an already-verified customer

Deleting