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

# Tracking status

> Poll for policy, determination, payment and payout updates.

<Tip>
  Prefer push over poll? [**Webhooks**](/guides/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.
</Tip>

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

<Warning>
  `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](/requirements#the-capacity-model).
</Warning>

## 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](/guides/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.

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

<Note>
  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](/guides/service-tiers).
</Note>

<Card title="Webhooks" icon="bolt" href="/guides/webhooks">
  Get signed events pushed to your endpoint instead of polling.
</Card>