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 if not.

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

Step 5 branches on your service tier. New organizations start on DETERMINATION (Tier 1), where you collect premium and settle the farmer. Check with GET /api/organizations/me → data.serviceTier.

1. Register a farmer

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

Response (data is the created farmer):

{ "success": true, "data": { "id": "f1a2…", "kycStatus": "PENDING", "...": "…" } }

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

2. Register a plot (for crop cover)

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

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
  }'

{ "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.

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
  }'

{ "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

Tier 1 — DETERMINATION

You collect premium off-platform, then attest it:

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.

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.

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": "[phone]" }'

On a Tier 1 policy this returns 403 TIER_NOT_ENTITLED. See Payments.

6. Receive the determination

Subscribe to determination.delivered, or poll:

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.

# the self-contained, independently verifiable artifact
curl "https://app.microcrop.app/api/determinations/$DET_ID/evidence" \
  -H "x-api-key: $MICROCROP_API_KEY"

Service tiers

What DETERMINATION buys, and where our responsibility ends.

Tier 1 integration

The full Tier 1 path: sell, activate, determine, settle, report.

Verify it yourself

Re-derive our hash and recover our signature without calling us.

Policy lifecycle

Every state, livestock (IBLI) cover, and cancellations.