# MicroCrop API

> Integrate parametric crop & livestock insurance into your systems.

- [Introduction](https://docs.microcrop.app/introduction.md): Verifiable parametric determination — and, if you want it, settlement — for crop & livestock cover.
- [Service tiers](https://docs.microcrop.app/guides/service-tiers.md): What DETERMINATION buys, what DETERMINATION_AND_SETTLEMENT adds, and exactly where our responsibility ends.
- [Requirements](https://docs.microcrop.app/requirements.md): Everything your organization needs before it can sell cover, and what changes by service tier.
- [Quickstart](https://docs.microcrop.app/quickstart.md): Register a farmer, quote, sell, activate, and read the determination.
- [Authentication](https://docs.microcrop.app/authentication.md): Authenticate server-to-server requests with your organization API key.
- [Onboarding your organization](https://docs.microcrop.app/guides/onboarding.md): From signup to a verified organization with recorded underwriting capacity.
- [Policy lifecycle](https://docs.microcrop.app/guides/policy-lifecycle.md): Crop and livestock cover, from quote to determination to cancellation.
- [Payments](https://docs.microcrop.app/guides/payments.md): Collect premiums via M-Pesa on Tier 2, or attest off-platform premium on Tier 1.
- [Tracking status](https://docs.microcrop.app/guides/status-tracking.md): Poll for policy, determination, payment and payout updates.
- [Determinations](https://docs.microcrop.app/guides/determinations.md): Read the signed determination and its evidence package for any of your policies.
- [Tier 1 integration](https://docs.microcrop.app/guides/tier-1-integration.md): The DETERMINATION tier end to end: sell cover, activate on your own premium, receive the determination, settle the farmer yourself, report it back.
- [Independent verification](https://docs.microcrop.app/guides/verification.md): Reproduce our hash and recover our signature yourself, without trusting or calling MicroCrop.
- [Webhooks](https://docs.microcrop.app/guides/webhooks.md): Receive signed, real-time event notifications instead of polling.
- [Errors](https://docs.microcrop.app/guides/errors.md): Response envelopes and error codes.
- [Rate limits](https://docs.microcrop.app/guides/rate-limits.md): Request quotas and how to handle them.
- [API reference](https://docs.microcrop.app/api-reference/overview.md): The MicroCrop partner REST API.
- [Register a farmer](https://docs.microcrop.app/api-reference/farmers/register-a-farmer.md)
- [List farmers](https://docs.microcrop.app/api-reference/farmers/list-farmers.md)
- [Get a farmer](https://docs.microcrop.app/api-reference/farmers/get-a-farmer.md)
- [Approve or reject farmer KYC](https://docs.microcrop.app/api-reference/farmers/approve-or-reject-farmer-kyc.md)
- [List plots](https://docs.microcrop.app/api-reference/plots/list-plots.md)
- [Register a plot](https://docs.microcrop.app/api-reference/plots/register-a-plot.md)
- [Register a herd (livestock)](https://docs.microcrop.app/api-reference/herds/register-a-herd-livestock.md)
- [Quote a policy](https://docs.microcrop.app/api-reference/policies/quote-a-policy.md): Prices a policy without writing anything. Not KYB-gated.
- [Purchase a policy](https://docs.microcrop.app/api-reference/policies/purchase-a-policy.md): Creates a PENDING policy awaiting premium. Requires the organization to be KYB-verified and the farmer's KYC to be APPROVED.
- [List policies](https://docs.microcrop.app/api-reference/policies/list-policies.md)
- [Get a policy](https://docs.microcrop.app/api-reference/policies/get-a-policy.md)
- [Get policy status](https://docs.microcrop.app/api-reference/policies/get-policy-status.md): Full policy plus daysRemaining, payouts[] and damageAssessments[]. The best single call for current state.
- [Activate a policy on attested off-platform premium](https://docs.microcrop.app/api-reference/policies/activate-a-policy-on-attested-off-platform-premium.md): Attests that premium for a PENDING policy was received OFF-PLATFORM, and flips it to ACTIVE. This is the NORMAL activation path on the DETERMINATION (Tier 1) service tier, where MicroCrop never collects premium; on DETERMINATION_AND_SETTLEMENT it is the reconciliation fallback for premium that did n…
- [Cancel a policy](https://docs.microcrop.app/api-reference/policies/cancel-a-policy.md)
- [Quote a KES→USDC conversion](https://docs.microcrop.app/api-reference/payments/quote-a-kes→usdc-conversion.md)
- [Initiate a premium payment (M-Pesa STK push)](https://docs.microcrop.app/api-reference/payments/initiate-a-premium-payment-m-pesa-stk-push.md): Rate limited to 10 requests/hour. `reference` is the policy id (`policyId` is accepted as a legacy alias; if both are sent they must match). TIER-GATED: on a policy whose frozen settlementMode is DETERMINATION this returns 403 TIER_NOT_ENTITLED before any transaction row is written and before any ST…
- [Get payment status](https://docs.microcrop.app/api-reference/payments/get-payment-status.md)
- [List payouts](https://docs.microcrop.app/api-reference/payouts/list-payouts.md)
- [Get a payout](https://docs.microcrop.app/api-reference/payouts/get-a-payout.md)
- [Retry a failed payout](https://docs.microcrop.app/api-reference/payouts/retry-a-failed-payout.md): Requires the `payout:retry` capability. TIER-GATED on the PAYOUT'S POLICY: 403 TIER_NOT_ENTITLED if that policy's settlementMode is DETERMINATION. A Tier 1 policy has no payouts at all.
- [Get your organization](https://docs.microcrop.app/api-reference/organization/get-your-organization.md): Includes kybStatus, countryCode, serviceTier, isActive and settings. It does NOT include apiKey, apiSecret or webhookSecret — those are stripped from this response. Read key metadata at GET /organizations/me/api-key and the webhook secret at GET /organizations/me/webhook.
- [API key metadata (masked)](https://docs.microcrop.app/api-reference/organization/api-key-metadata-masked.md): Masked metadata only — the plaintext key is never returned here. ORG_ADMIN only.
- [Rotate the API key](https://docs.microcrop.app/api-reference/organization/rotate-the-api-key.md): Mints a fresh key + secret and returns the plaintext EXACTLY ONCE. The previous key stops working immediately. ORG_ADMIN only.
- [Revoke the API key](https://docs.microcrop.app/api-reference/organization/revoke-the-api-key.md): x-api-key auth rejects the key with 401 afterwards. Reversible by rotating. ORG_ADMIN only.
- [Get webhook configuration](https://docs.microcrop.app/api-reference/organization/get-webhook-configuration.md): The endpoint URL and the plaintext signing secret (needed to verify HMAC signatures). ORG_ADMIN only.
- [Set the webhook endpoint URL](https://docs.microcrop.app/api-reference/organization/set-the-webhook-endpoint-url.md): Must be https. A signing secret is generated on first use and returned in the response. ORG_ADMIN only. NOTE: PUT /organizations/me/settings does NOT configure webhooks — it accepts only brandColor and contactPhone.
- [Rotate the webhook signing secret](https://docs.microcrop.app/api-reference/organization/rotate-the-webhook-signing-secret.md): The new secret is returned once. Deliveries signed with the old secret stop verifying immediately. ORG_ADMIN only.
- [List webhook deliveries](https://docs.microcrop.app/api-reference/organization/list-webhook-deliveries.md): Newest first. Attempt metadata only — the delivery payload is not returned. ORG_ADMIN only.
- [Re-enqueue a webhook delivery](https://docs.microcrop.app/api-reference/organization/re-enqueue-a-webhook-delivery.md): Re-sends the stored payload against your CURRENT url and secret, with the same body.id. ORG_ADMIN only.
- [Update display settings](https://docs.microcrop.app/api-reference/organization/update-display-settings.md): Accepts brandColor and contactPhone ONLY. webhookUrl is deliberately NOT accepted here — use PUT /organizations/me/webhook. ORG_ADMIN only.
- [Get KYB status](https://docs.microcrop.app/api-reference/organization/get-kyb-status.md)
- [List your determinations](https://docs.microcrop.app/api-reference/determinations/list-your-determinations.md): Signed, independently verifiable determinations for YOUR OWN policies, newest first. The organization scope is applied in the query, so a determination belonging to another organization is simply not in the result set. Requires the `determination:read` capability.
- [Get one determination](https://docs.microcrop.app/api-reference/determinations/get-one-determination.md): Three facts, never collapsed into one status: `determined` (what MicroCrop determined — signed, hashed, anchored), `settlement` (whether MicroCrop settled, and under the DETERMINATION tier that it deliberately did NOT) and `partnerReport` (what the partner claims happened — partner-attested and unve…
- [Get the evidence package](https://docs.microcrop.app/api-reference/determinations/get-the-evidence-package.md): The self-contained, independently verifiable evidence package: signed canonical body, hash, signature, signer, source provenance, linked policy and notary anchor receipt. Chain-neutral and currency-neutral by construction.
- [List the settlement reports on this determination](https://docs.microcrop.app/api-reference/determinations/list-the-settlement-reports-on-this-determination.md): Every report recorded against this determination, newest first, INCLUDING superseded ones — the correction chain is the audit trail. `current` is the newest un-superseded report. Everything returned is partner-attested and unverified by MicroCrop.
- [Report what you paid the farmer (DETERMINATION tier only)](https://docs.microcrop.app/api-reference/determinations/report-what-you-paid-the-farmer-determination-tier-only.md): Record YOUR statement of how you settled this determination off-platform, off your own balance sheet. MicroCrop stores and echoes the statement and NEVER verifies it: `verificationStatus` is structurally one-valued (`UNVERIFIED`) and every response restates `verifiedByMicrocrop: false`. Nothing here…

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)