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

# POST /v1/organizations/:id/kyb — Submit Business Docs

> Upload business registration details and supporting documents to start KYB verification for your organization. Requires the X-Organization-Id header.

Submit business verification documents for your organization. Provide your business type, industry, registration number, and upload supporting files such as a certificate of incorporation or KRA PIN certificate. The request must use `multipart/form-data`. Both the path `:id` and the `X-Organization-Id` header must match your organization's ID.

<Note>
  This endpoint expects `multipart/form-data`, not JSON. Use `-F` flags in curl or a multipart form library in your client.
</Note>

## Endpoint

```
POST https://api.nyotaimara.com/v1/organizations/:id/kyb
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token issued after sign-in. Format: `Bearer <token>`.
</ParamField>

<ParamField header="X-Organization-Id" type="string" required>
  The organization's unique ID. Must match the `:id` path parameter.
</ParamField>

## Path parameters

<ParamField path="id" type="string" required>
  The organization ID to submit KYB for. Must match `X-Organization-Id`.
</ParamField>

## Body

<ParamField body="businessType" type="string" required>
  Legal structure of the business. Common values: `sole_proprietorship`, `limited_company`, `partnership`.
</ParamField>

<ParamField body="industry" type="string" required>
  Industry the business operates in. Examples: `technology`, `retail`, `logistics`.
</ParamField>

<ParamField body="description" type="string" required>
  Brief description of the business and its activities.
</ParamField>

<ParamField body="registrationNumber" type="string" required>
  Official government-issued business registration number.
</ParamField>

<ParamField body="certificateOfIncorporation" type="file">
  Certificate of incorporation (required for `limited_company`).
</ParamField>

<ParamField body="kraPin" type="file">
  KRA PIN certificate.
</ParamField>

<ParamField body="cr12" type="file">
  CR12 — official list of directors (required for `limited_company`).
</ParamField>

<ParamField body="memorandumOfAssociation" type="file">
  Memorandum and Articles of Association.
</ParamField>

<Note>
  Document fields are dynamic and depend on `businessType`. The backend accepts any file fields you include and stores them under their field name. Include all documents relevant to your business structure.
</Note>

## Response

<ResponseField name="success" type="boolean">
  `true` on a successful submission.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable confirmation. Value: `"KYB submitted successfully."`.
</ResponseField>

```json theme={null}
{
  "success": true,
  "message": "KYB submitted successfully."
}
```

## Errors

| Status | Error message                          | Cause                                                                                          |
| ------ | -------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `400`  | `"KYB is already pending."`            | A pending review already exists for this organization.                                         |
| `400`  | `"KYB is already verified."`           | The organization has already been verified.                                                    |
| `400`  | `"Missing required business details."` | One or more of `businessType`, `industry`, `description`, or `registrationNumber` was omitted. |
| `500`  | `"Failed to process KYB documents."`   | Server-side upload or database error.                                                          |

## Example

```bash theme={null}
curl -X POST https://api.nyotaimara.com/v1/organizations/org_01j9z.../kyb \
  -H "Authorization: Bearer <token>" \
  -H "X-Organization-Id: org_01j9z..." \
  -F "businessType=limited_company" \
  -F "industry=technology" \
  -F "description=A B2B software platform for SMEs." \
  -F "registrationNumber=CPR/2021/123456" \
  -F "certificateOfIncorporation=@/path/to/certificate.pdf" \
  -F "kraPin=@/path/to/kra_pin.pdf" \
  -F "cr12=@/path/to/cr12.pdf"
```