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

# Quickstart

> Register a farmer, quote, sell, activate, and read the determination.

This walks through the core flow end to end. It assumes your organization is
**KYB-verified with underwriting capacity recorded** — see [Requirements](/requirements)
if not.

<Note>Base URL: `https://app.microcrop.app/api` · Auth header: `x-api-key: <your key>`</Note>

<Info>
  Step 5 branches on your [service tier](/guides/service-tiers). New organizations start on
  `DETERMINATION` (Tier 1), where **you** collect premium and settle the farmer. Check with
  `GET /api/organizations/me` → `data.serviceTier`.
</Info>

## 1. Register a farmer

```bash theme={null}
curl -X POST https://app.microcrop.app/api/farmers/register \
  -H "x-api-key: $MICROCROP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+254712345678",
    "nationalId": "12345678",
    "firstName": "Jane",
    "lastName": "Wanjiru",
    "county": "Nakuru",
    "subCounty": "Naivasha"
  }'
```

Response (`data` is the created farmer):

```json theme={null}
{ "success": true, "data": { "id": "f1a2…", "kycStatus": "PENDING", "...": "…" } }
```

<Note>A farmer's KYC must be `APPROVED` before you can purchase a policy for them.
Approve via `PUT /api/farmers/{farmerId}/kyc` (requires the `kyc:decide` capability —
`ORG_ADMIN` only, which is what your API key holds).</Note>

## 2. Register a plot (for crop cover)

```bash theme={null}
curl -X POST https://app.microcrop.app/api/plots \
  -H "x-api-key: $MICROCROP_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "farmerId": "f1a2…",
    "name": "North field",
    "latitude": -0.7167,
    "longitude": 36.4333,
    "acreage": 2.5,
    "cropType": "MAIZE"
  }'
```

## 3. Quote a policy

```bash theme={null}
curl -X POST https://app.microcrop.app/api/policies/quote \
  -H "x-api-key: $MICROCROP_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "farmerId": "f1a2…",
    "productType": "CROP",
    "plotId": "p1b2…",
    "sumInsured": 50000,
    "coverageType": "DROUGHT",
    "durationDays": 120
  }'
```

```json theme={null}
{ "success": true, "data": {
  "sumInsured": 50000, "premium": 2500, "platformFee": 125, "netPremium": 2375,
  "coverageType": "DROUGHT", "durationDays": 120,
  "breakdown": { "baseRate": "…", "cropFactor": "…", "durationFactor": "…" }
} }
```

Quoting writes nothing and is not gated, so you can price before going live.

## 4. Purchase the policy

Requires KYB verification, a current regulator licence, an `APPROVED` farmer KYC and
recorded underwriting headroom. Creates a `PENDING` policy awaiting premium.

```bash theme={null}
curl -X POST https://app.microcrop.app/api/policies/purchase \
  -H "x-api-key: $MICROCROP_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "farmerId": "f1a2…",
    "productType": "CROP",
    "plotId": "p1b2…",
    "sumInsured": 50000,
    "coverageType": "DROUGHT",
    "durationDays": 120
  }'
```

```json theme={null}
{ "success": true, "data": {
  "policy": { "id": "po1…", "policyNumber": "…", "status": "PENDING",
              "premiumPaid": false, "settlementMode": "DETERMINATION" },
  "paymentInstructions": { "amount": 2500, "policyNumber": "…", "message": "…" }
} }
```

`settlementMode` is **frozen onto the policy here**, from your organization's tier at the
moment of sale. It decides who owes this farmer for this cover, for the life of the
policy — a later tier change never touches it.

## 5. Get the policy to `ACTIVE`

<Tabs>
  <Tab title="Tier 1 — DETERMINATION">
    You collect premium off-platform, then attest it:

    ```bash theme={null}
    curl -X PUT https://app.microcrop.app/api/policies/po1…/activate \
      -H "x-api-key: $MICROCROP_API_KEY" -H "Content-Type: application/json" \
      -d '{
        "paymentReference": "SFH7TQ2K91",
        "reason": "Premium collected on the Acme till, reconciled 2026-09-01"
      }'
    ```

    Returns the policy at `status: ACTIVE`, `premiumPaid: true`. Both body fields are
    required. Full walkthrough: [Tier 1 integration](/guides/tier-1-integration).
  </Tab>

  <Tab title="Tier 2 — DETERMINATION_AND_SETTLEMENT">
    MicroCrop triggers an STK push to the payer's phone. On success the policy is
    **created on-chain and activated automatically**.

    ```bash theme={null}
    curl -X POST https://app.microcrop.app/api/payments/initiate \
      -H "x-api-key: $MICROCROP_API_KEY" -H "Content-Type: application/json" \
      -d '{ "reference": "po1…", "amount": 2500, "phoneNumber": "+254712345678" }'
    ```

    On a Tier 1 policy this returns `403 TIER_NOT_ENTITLED`. See
    [Payments](/guides/payments).
  </Tab>
</Tabs>

## 6. Receive the determination

Subscribe to [`determination.delivered`](/guides/webhooks), or poll:

```bash theme={null}
curl "https://app.microcrop.app/api/determinations?policyId=po1…" \
  -H "x-api-key: $MICROCROP_API_KEY"
```

Each row states three separate facts: what MicroCrop **determined**, whether MicroCrop
**settled**, and what you have **reported** back. On Tier 1 you then settle the farmer and
report it; on Tier 2 you watch `GET /api/payouts`.

```bash theme={null}
# the self-contained, independently verifiable artifact
curl "https://app.microcrop.app/api/determinations/$DET_ID/evidence" \
  -H "x-api-key: $MICROCROP_API_KEY"
```

<CardGroup cols={2}>
  <Card title="Service tiers" icon="scale-balanced" href="/guides/service-tiers">
    What DETERMINATION buys, and where our responsibility ends.
  </Card>

  <Card title="Tier 1 integration" icon="route" href="/guides/tier-1-integration">
    The full Tier 1 path: sell, activate, determine, settle, report.
  </Card>

  <Card title="Verify it yourself" icon="shield-check" href="/guides/verification">
    Re-derive our hash and recover our signature without calling us.
  </Card>

  <Card title="Policy lifecycle" icon="arrow-right" href="/guides/policy-lifecycle">
    Every state, livestock (IBLI) cover, and cancellations.
  </Card>
</CardGroup>