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

# Onboarding your organization

> From signup to a verified organization with recorded underwriting capacity.

Before you can sell cover, your organization must be created, **KYB-verified** (which
includes your insurance regulator's operating licence), and have **underwriting capacity
recorded** by MicroCrop. This is a one-time setup.

## 1. Create the account

Self-service signup creates your organization and its first admin user, and returns
login tokens **and your API key**:

```bash theme={null}
curl -X POST https://app.microcrop.app/api/auth/register-organization \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "Acme Insurance Ltd",
    "registrationNumber": "C.12345",
    "type": "INSURANCE_COMPANY",
    "countryCode": "KE",
    "county": "Nairobi",
    "firstName": "Asha",
    "lastName": "Otieno",
    "email": "asha@acme.co.ke",
    "password": "••••••••",
    "phone": "+254712345678"
  }'
```

* `type` is one of `COOPERATIVE`, `NGO`, `MFI`, `INSURANCE_COMPANY`, `GOVERNMENT`, `OTHER`.
* `countryCode` is `KE` or `GH` (defaults to `KE`). It drives your market currency, the
  KYB document set and your regulator.
* `password` must be at least 8 characters with an uppercase letter, a digit and a
  special character.
* The new organization starts at `kybStatus: NOT_STARTED` and
  `serviceTier: DETERMINATION`.

```json theme={null}
{ "success": true, "data": {
  "organization": { "id": "…", "apiKey": "…", "kybStatus": "NOT_STARTED", "serviceTier": "DETERMINATION" },
  "user": { "…": "…" }, "accessToken": "…", "refreshToken": "…"
} }
```

<Warning>
  **Copy `data.organization.apiKey` now.** `GET /api/organizations/me` strips it. If you
  lose it, mint a new one with `POST /api/organizations/me/api-key/rotate`. See
  [Authentication](/authentication).
</Warning>

## 2. Check what your market requires

```bash theme={null}
curl https://app.microcrop.app/api/organizations/me/kyb -H "x-api-key: $KEY"
```

```json theme={null}
{ "success": true, "data": {
  "kybStatus": "NOT_STARTED",
  "onboardingStep": "KYB_VERIFICATION",
  "countryCode": "KE",
  "checklist": {
    "regulator": "IRA",
    "regulatorLicenseRequired": true,
    "regulatorLicenseDocType": "IRA_LICENSE",
    "livestockEnabled": true,
    "requiredDocuments": [
      { "documentType": "BUSINESS_REGISTRATION", "required": true, "satisfied": false },
      { "documentType": "TAX_CERTIFICATE",       "required": true, "satisfied": false },
      { "documentType": "IRA_LICENSE",           "required": true, "satisfied": false }
    ],
    "optionalDocuments": [ { "documentType": "PROOF_OF_ADDRESS", "…": "…" } ]
  },
  "verification": null
} }
```

`checklist` is the authority — read it rather than hard-coding a document set.

| Market       | Required documents                                                                        | Regulator |
| ------------ | ----------------------------------------------------------------------------------------- | --------- |
| Kenya (`KE`) | Business registration, KRA PIN tax certificate, **IRA operating licence**                 | IRA       |
| Ghana (`GH`) | **NIC operating licence**, Certificate of Incorporation, Ghana TIN, director's Ghana Card | NIC       |

## 3. Submit KYB documents

Multipart upload. The file field names map to document types:

| Field                        | Document type                  |
| ---------------------------- | ------------------------------ |
| `businessRegistrationCert`   | `BUSINESS_REGISTRATION`        |
| `taxPinCert`                 | `TAX_CERTIFICATE`              |
| `iraLicenseCert`             | `IRA_LICENSE`                  |
| `nicLicenseCert`             | `NIC_LICENSE`                  |
| `certificateOfIncorporation` | `CERTIFICATE_OF_INCORPORATION` |
| `ghanaTin`                   | `GHANA_TIN`                    |
| `directorId`                 | `DIRECTOR_ID`                  |
| `proofOfAddress`             | `PROOF_OF_ADDRESS`             |
| `bankStatement`              | `BANK_STATEMENT`               |
| `otherDocument`              | `OTHER`                        |

Send the licence **number and expiry** as ordinary form fields alongside the files:

```bash theme={null}
curl -X POST https://app.microcrop.app/api/organizations/me/kyb \
  -H "x-api-key: $KEY" \
  -F "businessRegistrationCert=@business-reg.pdf" \
  -F "taxPinCert=@kra-pin.pdf" \
  -F "iraLicenseCert=@ira-licence.pdf" \
  -F "regulatorLicenseNumber=IRA/12/3456" \
  -F "licenseExpiresAt=2027-12-31"
```

`licenseExpiresAt` must be an ISO date **in the future**. Files must be PDF, JPEG or PNG
and at most 10 MB each.

Requires `ORG_ADMIN`. Status moves to `PENDING_REVIEW`. Poll the same path with `GET`:

```bash theme={null}
curl https://app.microcrop.app/api/organizations/me/kyb -H "x-api-key: $KEY"
# data.kybStatus: NOT_STARTED → PENDING_REVIEW → VERIFIED | REJECTED
```

A resubmission only needs the documents you are replacing — documents already on file
count toward the required set.

<Note>
  Missing a required document returns `400` naming exactly which ones are missing. A
  verified organization whose regulator licence was never captured, or has lapsed, is
  still blocked from selling with `403 REGULATOR_LICENSE_REQUIRED` /
  `403 REGULATOR_LICENSE_EXPIRED`.
</Note>

## 4. Have your underwriting capacity recorded

MicroCrop does not hold your capital. Before you can sell, a MicroCrop administrator
records a **solvency attestation**: the maximum aggregate sum insured your off-platform
capital stands behind, in one currency, for a bounded period, on named evidence.

There is no partner endpoint for this — send MicroCrop the treaty, trust statement,
letter of credit, bank guarantee, proof of funds or regulator solvency return you want
it recorded against, with the effective window and a signing officer. Until a live
attestation exists, `POST /api/policies/purchase` is refused:

```json theme={null}
{ "success": false, "error": { "code": "INVALID_INPUT",
  "message": "This organization has no recorded solvency attestation. A platform administrator must record attested off-platform capacity before any cover can be sold. Contact MicroCrop to record or restate the attestation." } }
```

Over-capacity, expired, revoked, not-yet-effective and currency-mismatch each produce a
distinct message naming the condition — see [Requirements](/requirements#the-capacity-model).

<Warning>
  There is no `POST /me/wallet/fund`, `POST /me/reserve/deposit` or `GET /me/reserve`.
  Those endpoints were removed with the non-custodial model and now `404`.
</Warning>

## 5. Confirm your service tier

```bash theme={null}
curl https://app.microcrop.app/api/organizations/me -H "x-api-key: $KEY"
# → data.serviceTier: "DETERMINATION" | "DETERMINATION_AND_SETTLEMENT"
# → data.kybStatus, data.countryCode, data.isActive
```

New organizations start on `DETERMINATION`. Which tier you are on decides who settles the
farmer, and it is stamped onto every policy at purchase — see
[Service tiers](/guides/service-tiers).

## 6. Configure webhooks (recommended)

```bash theme={null}
curl -X PUT https://app.microcrop.app/api/organizations/me/webhook \
  -H "x-api-key: $KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://your-system.example.com/microcrop/webhooks" }'
```

See [Webhooks](/guides/webhooks).

You're now ready to [register farmers and sell policies](/guides/policy-lifecycle) —
and, on Tier 1, to follow the [Tier 1 integration guide](/guides/tier-1-integration).