Tracking status

Poll for policy, determination, payment and payout updates.

Prefer push over poll? Webhooks deliver signed policy.activated, determination.*, payout.* and kyb.* events in real time. Polling (below) is the fallback and the way to reconcile anything you miss.

What to poll

You want to know…	Poll	Watch for
A determination was issued	GET /api/determinations?policyId={id}	a row appears; determined.triggered, settlement.amountOwed
Full detail of one determination	GET /api/determinations/{determinationId}	determined, settlement, partnerReport
Premium payment result (Tier 2)	GET /api/payments/status/{reference}	status: COMPLETED / FAILED
Policy became active	GET /api/policies/{policyId}/status	status: ACTIVE, premiumPaid: true
A payout was made (Tier 2)	GET /api/policies/{policyId}/status	payouts[], damageAssessments[] populate
Payout progress across policies (Tier 2)	GET /api/payouts?status=PROCESSING	status: COMPLETED
Your own settlement reports (Tier 1)	GET /api/determinations/{determinationId}/settlement-report	current, reports[]
KYB approval	GET /api/organizations/me/kyb	kybStatus: VERIFIED
Your service tier	GET /api/organizations/me	serviceTier

GET /api/organizations/me/reserve and GET /api/organizations/me/wallet no longer exist — they return 404. Underwriting capacity is an attestation MicroCrop records for you, not a balance you can read; see Requirements.

Polling guidance

• Determinations: index determinations are periodic, not real-time. A daily reconciliation sweep over GET /api/determinations (newest first, page/limit paginated, limit capped at 100) is sufficient. Filter with policyId, status or kind.
• Payments (Tier 2): poll payments/status/{reference} every ~10–15s until it leaves PENDING (or for a few minutes, then treat as abandoned).
• Activation: after a COMPLETED payment, poll policies/{id}/status until ACTIVE (on-chain settlement can lag slightly). On Tier 1 the policy is ACTIVE as soon as PUT /api/policies/{id}/activate returns.
• Payouts (Tier 2): a daily or hourly sweep over GET /api/payouts filtered by status and farmerId, plus per-policy status checks, is enough.
• Respect rate limits (100 req/min). Prefer list endpoints with filters over many per-item calls when reconciling in bulk.
• Add jitter to polling intervals so retries don’t synchronize.

The policy status endpoint

GET /api/policies/{policyId}/status returns the full policy plus daysRemaining, its farmer, plot/herd, payouts[] and damageAssessments[] — the single best call for a policy’s current state.

{ "success": true, "data": {
  "id": "po1…", "policyNumber": "MC-KE-2026-000123", "status": "ACTIVE",
  "premiumPaid": true, "daysRemaining": 96, "currency": "KES",
  "settlementMode": "DETERMINATION",
  "payouts": [], "damageAssessments": []
} }

On a DETERMINATION-tier policy payouts[] is always empty — MicroCrop settles nothing there, by design. That is not a missing payout; the determination is the artifact. Read it at GET /api/determinations. See Service tiers.

Webhooks

Get signed events pushed to your endpoint instead of polling.