Business (KYB)

A business is one company plus one entry per beneficial owner (UBO). Each owner gets an applicant id in the create response, which you use to upload that owner’s documents. Beneficiaries are matched by email (case-insensitive): entries that share an email are merged into one owner with one applicantId — send each person once.

Create the business

POST /api/v0/customer with userType: "BUSINESS", a company block, one entry per beneficiary, and the company questionnaire.Returns 201 with the company applicant id and one applicantId per owner:

{
  "userId": "cus_8Hq2LmZ9sT4vRb1NdKpX",
  "userType": "BUSINESS",
  "status": "INITIATED",
  "companyApplicantId": "6a9998a19369a8e431904f89",
  "beneficiaries": [
    { "applicantId": "6a9998a144ccd5000e5f2481", "email": "owner1@acme.example", "shareSize": 60.0, "status": "PENDING" },
    { "applicantId": "6a9998a1bbbb2222cccc3333", "email": "owner2@acme.example", "shareSize": 40.0, "status": "PENDING" }
  ]
}

Save each applicantId — that is the uboRef for that owner’s uploads.

Upload company documents

POST /api/v0/customer/{userId}/documents with idDocType=COMPANY_DOC, using idDocSubType to say which document it is.

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=@incorporation.pdf;type=application/pdf" \
  -F "idDocType=COMPANY_DOC" \
  -F "idDocSubType=INCORPORATION_CERT" \
  -F "country=DEU"

A company must clear two groups — send one upload per group, and upload both before the owners’ last document (see the last step).

Upload each owner's documents

POST /api/v0/customer/{userId}/ubo/{uboRef}/documents, where uboRef is that owner’s applicantId.

curl -X POST https://api-sandbox.endl.io/api/v0/customer/$USER_ID/ubo/$UBO_REF/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=DEU"

Repeat for SELFIE and UTILITY_BILL. A uboRef that is not a beneficiary of this company returns 404 ERRCUS_1608, on field uboRef.

Everything submits together

Endl submits the business after its first company document, once every owner’s documents are complete. Upload both company groups before the owners’ last document, so the company isn’t submitted with one group missing.A business keeps its current status (normally INITIATED) until the company and every owner are in, then PENDING. A business never returns SUBMITTED.A business read has no documents array. Track progress through the overall status and each owner’s beneficiaries[].status — PENDING until that owner’s documents are uploaded, then UPLOADED. That is a document-upload status, not a verification result; use the top-level status for that.

Company fields

Field	Required	Notes
`companyName`	Yes
`registrationNumber`	Yes
`country`	Yes	ISO alpha-3.
`email`	Yes	Unique — this is the account key. A duplicate is `400 ERRCUS_1600`.
`type`	Yes	One of `LLC`, `CORPORATION`, `PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `TRUST`, `NON_PROFIT` (case-insensitive). Missing → `ERRCUS_1103`; anything else → `ERRCUS_1104`.
`phone`	Yes	E.164 format — `+` then 8–15 digits, e.g. `+971500000000`. Unique across all customers, individual or business — one already in use is `400 ERRCUS_1601`.
`website`	Yes	An `http(s)://…` URL.
`taxId`	Yes
`incorporatedOn`	Yes	`DD-MM-YYYY`, not in the future.
`address`	Yes	`{ street, town, state, postCode, country }`. `street`, `town`, `state`, `postCode` and `country` are all required; `subStreet` is optional. A missing sub-field is `ERRCUS_1118`–`1121` or `1123`; an invalid `postCode` is `ERRCUS_1122` and an invalid `address.country` is `ERRCUS_1124`. `postCode` is format-checked for `USA`, `DEU`, `IND` and `GBR` only.

Beneficiary fields

One entry per beneficial owner. At least one is required, and at least one must be a UBO.

Field	Required	Notes
`firstName` / `lastName`	Yes
`email`	Yes	Valid email. Beneficiaries are matched by email (case-insensitive): entries that share an email are merged into one owner, keeping the first entry’s details and returning one `applicantId`. Send each person once.
`country`	Yes	ISO alpha-3.
`dob`	Yes	`DD-MM-YYYY`, not in the future.
`shareSize`	No	0–100. The sum across beneficiaries must not exceed 100.
`types`	No	Only `ubo` is supported. Empty or absent defaults to `["ubo"]`.
`address`	Yes	Same shape and same required sub-fields as the company address.

Every beneficiary needs an address, and at least one must be a UBO. A missing address is 400 ERRCUS_1215 (beneficiaries[0].address is required). A set of beneficiaries with no ubo among their types is 400 ERRCUS_1201.

director is no longer a supported beneficiary type. Previously types accepted ["ubo"], ["director"] or both, and a person listed as both was merged into one owner. Now any value other than ubo — including director, in any letter case — is rejected with 400 before anything is created:

{
  "code": 400,
  "message": "Onboarding validation failed",
  "status": "ERROR",
  "data": null,
  "errors": [
    {
      "code": "ERRCUS_1214",
      "message": "beneficiaries[1].types must be a subset of [ubo]; 'director' is not supported",
      "field": "beneficiaries[1].types"
    }
  ]
}

A director beneficiary used to fail later, at verification, with a 500. List only the company’s UBOs as beneficiaries.

Company document types

idDocType is always COMPANY_DOC. idDocSubType says which document:

`idDocSubType`	Group	Document
`INCORPORATION_CERT`	legal presence	Certificate of Incorporation
`INCORPORATION_ARTICLES`	legal presence	Articles of Incorporation / Association
`SHAREHOLDER_REGISTRY`	ownership structure	Register of Shareholders

Legal presence is satisfied by either incorporation document. Ownership structure needs the shareholder registry.

Owner document types

PASSPORT · ID_CARD · DRIVERS · RESIDENCE_PERMIT · SELFIE · UTILITY_BILL (proof of address) These are the recommended values. Endl does not validate the value; any non-blank idDocType is passed to the verification provider, and ERRCUS_1406 is not returned on this endpoint. DRIVERS_LICENSE is still accepted as an alias for DRIVERS. Same limits as individuals: JPEG, PNG or PDF, maximum 5 MB, content sniffed rather than trusted by extension.

Updating and deleting

Update changes company fields — beneficiaries are not changed here, and the questionnaire cannot be updated at all (400 ERRCUS_1303). An update must change at least one field; an empty one, or {"company":{}}, is 400 ERRCUS_1502. It returns 200 with the updated business customer. After COMPLETED the business is fully locked: any company change returns 409 ERRCUS_1604. Delete is a soft delete, with the same funded-delete 409 ERRCUS_1606 guard and the same email release.

Importing a business

Pass a shareToken with userType: "BUSINESS". Both email and companyName are required alongside it — a missing companyName is ERRCUS_1125; country is validated if present.

{
  "shareToken": "_act-sbx-jwt-…",
  "userType": "BUSINESS",
  "email": "acme.imported@example.com",
  "companyName": "Acme Trading LLC",
  "country": "DEU"
}

Tokens are single-use, exactly as for individuals.

Introduction

Endpoints

Company fields

Beneficiary fields

Company document types

Owner document types

Updating and deleting

Importing a business

​Company fields

​Beneficiary fields

​Company document types

​Owner document types

​Updating and deleting

​Importing a business

Company fields

Beneficiary fields

Company document types

Owner document types

Updating and deleting

Importing a business