> ## 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.

# Requirements

> Everything your organization needs before it can sell cover, and what changes by service tier.

Integration is **progressively unlocked**. You can sign up and explore (register
farmers, get quotes) immediately, but **underwriting is gated** until your
organization is KYB-verified, licensed in its market, and has recorded underwriting
capacity with MicroCrop.

## Go-live checklist

<Steps>
  <Step title="Create an organization account">
    Sign up via the [dashboard](https://app.microcrop.app) or
    `POST /api/auth/register-organization`. This creates your organization and its
    first admin user, and returns login tokens. Your organization starts with
    `kybStatus: NOT_STARTED`.
  </Step>

  <Step title="Get your API key">
    The signup response carries the new key at `data.organization.apiKey` — copy it
    there, or read it in the dashboard. Afterwards `GET /api/organizations/me/api-key`
    returns **masked metadata only**, and
    `POST /api/organizations/me/api-key/rotate` mints a fresh key and returns the
    plaintext exactly once. See [Authentication](/authentication).
  </Step>

  <Step title="Complete KYB verification">
    Submit your KYB documents (`POST /api/organizations/me/kyb`, or in the dashboard).
    The required set is **country-specific** and includes your insurance regulator's
    operating licence — IRA in Kenya, NIC in Ghana. A MicroCrop admin reviews them; on
    approval `kybStatus` becomes `VERIFIED`. **This is required before you can sell
    cover.** See [Onboarding](/guides/onboarding).
  </Step>

  <Step title="Have your underwriting capacity recorded">
    MicroCrop does **not** custody your capital. Capacity is *attested*, not deposited:
    a MicroCrop administrator records a dated statement — by a named officer of a named
    legal entity, on stated evidence — of the maximum **aggregate sum insured** your
    off-platform capital stands behind, in one currency, for a bounded period. Without
    a live attestation `POST /api/policies/purchase` is refused. There is no partner
    endpoint for this; contact MicroCrop. See [the capacity model](#the-capacity-model).
  </Step>

  <Step title="Confirm your service tier">
    `DETERMINATION` (Tier 1 — we determine, you settle) or
    `DETERMINATION_AND_SETTLEMENT` (Tier 2 — we also settle). New organizations start on
    `DETERMINATION`. Read `serviceTier` from `GET /api/organizations/me`. Changing it is
    a MicroCrop-side commercial action. See [Service tiers](/guides/service-tiers).
  </Step>
</Steps>

## What's gated

| Gate                                                         | Applies to                                                          | On failure                                                                                                                    |
| ------------------------------------------------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `kybStatus: VERIFIED`                                        | `POST /api/policies/purchase`                                       | `403 FORBIDDEN`                                                                                                               |
| Current regulator licence on file                            | `POST /api/policies/purchase`                                       | `403 REGULATOR_LICENSE_REQUIRED` / `403 REGULATOR_LICENSE_EXPIRED`                                                            |
| A live solvency attestation with headroom                    | `POST /api/policies/purchase`                                       | `400 INVALID_INPUT`, message naming which of *never recorded / expired / revoked / not yet effective / over capacity* applies |
| `settlementMode: DETERMINATION_AND_SETTLEMENT` on the policy | `POST /api/payments/initiate`, `POST /api/payouts/{payoutId}/retry` | `403 TIER_NOT_ENTITLED`                                                                                                       |
| `settlementMode: DETERMINATION` on the policy                | `POST /api/determinations/{id}/settlement-report`                   | `403 NOT_PARTNER_SETTLED`                                                                                                     |

Everything else — registering farmers, plots and herds, **quoting** policies, reading
data, reading determinations and evidence packages — works before verification.

## The capacity model

Each organization underwrites against **its own capital, held off-platform** in its own
trust or treaty. MicroCrop never takes custody of it, so solvency is not a balance the
API can read; it is an attestation MicroCrop records and then enforces.

At purchase, MicroCrop compares the proposed sum insured plus your **in-force exposure**
(the sum insured of your `PENDING` and `ACTIVE` policies whose cover period has not
ended, in that currency) against the attested capacity. Over the limit, the purchase is
refused with a message naming the current exposure and the binding limit.

Two properties worth knowing:

* **Capacity is never converted between currencies.** An attestation in KES cannot back
  a policy written in GHS; a mismatch is a refusal, not an FX conversion.
* **It is a limit on cover in force, not a drawdown ledger.** Capacity is released when a
  policy expires, not when it pays. Restating capital net of claims paid happens when the
  attestation is renewed, which is why attestation windows are bounded.

<Warning>
  The old custodial model — a MicroCrop-provisioned wallet, `POST /me/wallet/fund`,
  `POST /me/reserve/deposit`, `GET /me/reserve` — has been **removed**. Those endpoints
  return `404`. If your integration calls them, delete those calls.
</Warning>

## Environments

|            | Network      | Base URL                        |
| ---------- | ------------ | ------------------------------- |
| Production | Base mainnet | `https://app.microcrop.app/api` |

<Warning>
  There is no public sandbox host yet. If you need a test environment for integration
  testing, contact your MicroCrop technical contact.
</Warning>