> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endl.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Business (KYB)

> Onboard a company and its beneficial owners

A business is one company plus one entry per owner or director. Each owner gets
their own applicant id in the create response, which you use to upload that
owner's documents.

<Steps>
  <Step title="Create the business" icon="building-circle-check">
    [`POST /api/v0/customer`](/api-reference/onboarding/create-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:

    ```json theme={null}
    {
      "userId": "cf4d8086-3574-4522-aed8-05d8ac06193e",
      "userType": "BUSINESS",
      "status": "INITIATED",
      "companyApplicantId": "6a9998a19369a8e431904f89",
      "beneficiaries": [
        { "applicantId": "6a9998a144ccd5000e5f2481", "email": "owner1@acme.example", "shareSize": 60.0, "status": "PENDING" },
        { "applicantId": "6a9998a1bbbb2222", "email": "director@acme.example", "shareSize": 40.0, "status": "PENDING" }
      ]
    }
    ```

    **Save each `applicantId`** — that is the `uboRef` for that owner's uploads.
  </Step>

  <Step title="Upload company documents" icon="file-contract">
    [`POST /api/v0/customer/{userId}/documents`](/api-reference/onboarding/upload-document)
    with `idDocType=COMPANY_DOC`, using `idDocSubType` to say which document it is.

    ```bash theme={null}
    curl -X POST https://qa-api.endl.xyz/api/v0/customer/$USER_ID/documents \
      -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.
  </Step>

  <Step title="Upload each owner's documents" icon="users">
    [`POST /api/v0/customer/{userId}/ubo/{uboRef}/documents`](/api-reference/onboarding/upload-ubo-document),
    where `uboRef` is that owner's `applicantId`.

    ```bash theme={null}
    curl -X POST https://qa-api.endl.xyz/api/v0/customer/$USER_ID/ubo/$UBO_REF/documents \
      -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`. An unknown `uboRef` returns `404`.
  </Step>

  <Step title="Everything submits together" icon="paper-plane">
    Once the company documents **and** every owner's documents are uploaded, the
    business auto-submits: status moves to `PENDING`, and the company and all
    owners go to review together.
  </Step>
</Steps>

***

## Company fields

| Field                               | Required | Notes                                         |
| ----------------------------------- | -------- | --------------------------------------------- |
| `companyName`                       | Yes      |                                               |
| `registrationNumber`                | Yes      |                                               |
| `country`                           | Yes      | ISO alpha-3.                                  |
| `email`                             | Yes      | Unique — this is the account key.             |
| `type`, `website`, `taxId`, `phone` | No       |                                               |
| `incorporatedOn`                    | No       | `YYYY-MM-DD`.                                 |
| `address`                           | No       | `{ street, town, state, postCode, country }`. |

## Beneficiary fields

One entry per owner or director. At least one is required.

| Field                    | Required | Notes                                                        |
| ------------------------ | -------- | ------------------------------------------------------------ |
| `firstName` / `lastName` | Yes      |                                                              |
| `email`                  | Yes      | Valid email.                                                 |
| `country`                | Yes      | ISO alpha-3.                                                 |
| `dob`                    | No       | `DD-MM-YYYY`.                                                |
| `shareSize`              | No       | 0–100. The **sum across beneficiaries must not exceed 100**. |
| `types`                  | No       | e.g. `["ubo"]`, `["director"]`. Defaults to `["ubo"]`.       |
| `address`                | No       | Same shape as the company address.                           |

<Tip>
  **Give every owner an address.** It is optional to the API, but the verification
  provider needs it to approve that owner. Omitting it leaves the UBO
  unapprovable even though the create call succeeds.
</Tip>

## 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_LICENSE` · `RESIDENCE_PERMIT` · `SELFIE` ·
`UTILITY_BILL` (proof of address)

Same limits as individuals: JPEG, PNG or PDF, maximum 2 MB, content sniffed
rather than trusted by extension.

## Updating and deleting

[Update](/api-reference/onboarding/update-customer) changes company fields and the
company questionnaire — **beneficiaries are not changed here**. It returns
`200` with `Business customer updated successfully`. After completion the company
identity fields lock, exactly as for an individual.

[Delete](/api-reference/onboarding/delete-customer) is a soft delete, with the same
funded-delete `409` guard and the same email release.

## Importing a business

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

```json theme={null}
{
  "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.