API Reference

YieldSecure

Parametric agricultural insurance — quote and issue multi-peril policies, check live trigger status, and subscribe to payout-triggering webhook events.

post/yieldsecure/quote

Generate a premium quote

Requires an Authorization: Bearer header.

Request body

farm_idstringrequired

field_idstringrequired

perilsenum<string>[]required

sum_insurednumberrequired

Maximum payout, in `currency`

currencystringoptional

ISO 4217 code for sum_insured/premium

Response 200

farm_idstringrequired

field_idstringrequired

perilsstring[]required

sum_insurednumberrequired

currencystringrequired

ratenumberrequired

Combined premium rate as a fraction of sum_insured

premiumnumberrequired

breakdownobjectrequired

Per-peril premium contribution

platform_versionstringrequired

POST /yieldsecure/quote

curl -X POST "https://api.cropsense.africa/yieldsecure/quote" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "farm_id": "3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a",
    "field_id": "8b6e1a2f-2d4c-4e9a-9b0f-1c7d3e5a6f42",
    "perils": [
      "drought"
    ],
    "sum_insured": 1.5,
    "currency": "USD"
  }'

Example response · 200

{
  "farm_id": "3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a",
  "field_id": "8b6e1a2f-2d4c-4e9a-9b0f-1c7d3e5a6f42",
  "perils": [
    "perils"
  ],
  "sum_insured": 1.5,
  "currency": "USD",
  "rate": 1.5,
  "premium": 1.5,
  "breakdown": {},
  "platform_version": "platform_version"
}

get/yieldsecure/policies

List policies

Requires an Authorization: Bearer header.

Parameters

statusstringquery

active | expired | claimed | lapsed

farm_idstringquery

perilenum<string>query

droughtfloodvegetation_stressstorm

pageintegerquery

page_sizeintegerquery

Response 200

itemsPolicyListItem[]required

totalintegerrequired

pageintegerrequired

page_sizeintegerrequired

GET /yieldsecure/policies

curl -X GET "https://api.cropsense.africa/yieldsecure/policies?status=status&farm_id=3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a&peril=drought&page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response · 200

{
  "items": [
    {
      "policy_id": "policy_id",
      "farm_id": "3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a",
      "field_id": "8b6e1a2f-2d4c-4e9a-9b0f-1c7d3e5a6f42",
      "crop_type": "crop_type",
      "sum_insured": 1.5,
      "currency": "USD",
      "premium": 1.5,
      "perils": [
        "perils"
      ],
      "status": "status",
      "issued_at": "2026-06-15T09:30:00Z",
      "term_start": "2026-06-15",
      "term_end": "2026-06-15",
      "next_monitoring_date": "2026-06-15"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 1
}

post/yieldsecure/policies

Issue a parametric insurance policy

Requires an Authorization: Bearer header.

Request body

farm_idstringrequired

field_idstringrequired

crop_typestringoptional

perilsenum<string>[]required

sum_insurednumberrequired

currencystringoptional

ISO 4217 code for sum_insured/premium

term_startstring<date>required

term_endstring<date>required

Response 201

policy_idstringrequired

organization_idstringrequired

environmentstringrequired

farm_idstringrequired

field_idstringrequired

farm_namestringoptional

field_namestringoptional

field_area_hanumberoptional

field_locationstringoptional

crop_typestringoptional

sum_insurednumberrequired

currencystringrequired

premiumnumberrequired

perilsstring[]required

triggersTriggerStatus[]required

Current status of every peril on this policy

statusstringrequired

issued_atstring<date-time>required

term_startstring<date>required

term_endstring<date>required

platform_versionstringrequired

next_monitoring_datestring<date>optional

POST /yieldsecure/policies

curl -X POST "https://api.cropsense.africa/yieldsecure/policies" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "farm_id": "3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a",
    "field_id": "8b6e1a2f-2d4c-4e9a-9b0f-1c7d3e5a6f42",
    "crop_type": "crop_type",
    "perils": [
      "drought"
    ],
    "sum_insured": 1.5,
    "currency": "USD",
    "term_start": "2026-06-15",
    "term_end": "2026-06-15"
  }'

Example response · 201

{
  "policy_id": "policy_id",
  "organization_id": "organization_id",
  "environment": "environment",
  "farm_id": "3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a",
  "field_id": "8b6e1a2f-2d4c-4e9a-9b0f-1c7d3e5a6f42",
  "farm_name": "farm_name",
  "field_name": "field_name",
  "field_area_ha": 1.5,
  "field_location": "field_location",
  "crop_type": "crop_type",
  "sum_insured": 1.5,
  "currency": "USD",
  "premium": 1.5,
  "perils": [
    "perils"
  ],
  "triggers": [
    {
      "peril": "peril",
      "trigger_index": "trigger_index",
      "current_index_reading": 1.5,
      "trigger_threshold": 1.5,
      "comparison": "comparison",
      "data_available": true
    }
  ],
  "status": "status",
  "issued_at": "2026-06-15T09:30:00Z",
  "term_start": "2026-06-15",
  "term_end": "2026-06-15",
  "platform_version": "platform_version",
  "next_monitoring_date": "2026-06-15"
}

get/yieldsecure/policies/{policy_id}

Retrieve a policy

Requires an Authorization: Bearer header.

Parameters

policy_idstringpathrequired

Response 200

policy_idstringrequired

organization_idstringrequired

environmentstringrequired

farm_idstringrequired

field_idstringrequired

farm_namestringoptional

field_namestringoptional

field_area_hanumberoptional

field_locationstringoptional

crop_typestringoptional

sum_insurednumberrequired

currencystringrequired

premiumnumberrequired

perilsstring[]required

triggersTriggerStatus[]required

Current status of every peril on this policy

statusstringrequired

issued_atstring<date-time>required

term_startstring<date>required

term_endstring<date>required

platform_versionstringrequired

next_monitoring_datestring<date>optional

GET /yieldsecure/policies/{policy_id}

curl -X GET "https://api.cropsense.africa/yieldsecure/policies/policy_id" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response · 200

{
  "policy_id": "policy_id",
  "organization_id": "organization_id",
  "environment": "environment",
  "farm_id": "3fa2c9e1-6b3a-4d2e-9c11-4a8e5f9d2b7a",
  "field_id": "8b6e1a2f-2d4c-4e9a-9b0f-1c7d3e5a6f42",
  "farm_name": "farm_name",
  "field_name": "field_name",
  "field_area_ha": 1.5,
  "field_location": "field_location",
  "crop_type": "crop_type",
  "sum_insured": 1.5,
  "currency": "USD",
  "premium": 1.5,
  "perils": [
    "perils"
  ],
  "triggers": [
    {
      "peril": "peril",
      "trigger_index": "trigger_index",
      "current_index_reading": 1.5,
      "trigger_threshold": 1.5,
      "comparison": "comparison",
      "data_available": true
    }
  ],
  "status": "status",
  "issued_at": "2026-06-15T09:30:00Z",
  "term_start": "2026-06-15",
  "term_end": "2026-06-15",
  "platform_version": "platform_version",
  "next_monitoring_date": "2026-06-15"
}

post/yieldsecure/policies/{policy_id}/evaluate

Evaluate a policy's triggers now, or as of a historical date for a backtest

Requires an Authorization: Bearer header.

Parameters

policy_idstringpathrequired

Request body

as_ofstring<date>optional

Response 200

policy_idstringrequired

as_ofstring<date>required

eventsTriggerEventResponse[]required

Only perils with a reading in their window this evaluation — see skipped_perils for the rest

total_payoutnumberrequired

currencystringrequired

is_backtestbooleanrequired

payout_countintegeroptional

policy_statusstringoptional

triggers_evaluatedintegerrequired

Count of perils with a reading in their window this evaluation

triggers_totalintegerrequired

Total perils on this policy

skipped_perilsstring[]optional

Perils with no reading in their window — could not be checked for breach, not the same as 'not breached'

POST /yieldsecure/policies/{policy_id}/evaluate

curl -X POST "https://api.cropsense.africa/yieldsecure/policies/policy_id/evaluate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "as_of": "2026-06-15"
  }'

Example response · 200

{
  "policy_id": "policy_id",
  "as_of": "2026-06-15",
  "events": [
    {
      "peril": "peril",
      "index": "index",
      "observed_value": 1.5,
      "threshold": 1.5,
      "breached": true,
      "severity": 1.5
    }
  ],
  "total_payout": 1.5,
  "currency": "USD",
  "is_backtest": true,
  "payout_count": 1,
  "policy_status": "policy_status",
  "triggers_evaluated": 1,
  "triggers_total": 1,
  "skipped_perils": [
    "skipped_perils"
  ]
}

post/yieldsecure/webhooks/trigger-events

Subscribe to trigger-breach notifications

Requires an Authorization: Bearer header.

Request body

urlstringrequired

HTTPS endpoint to receive trigger.breached webhook events

descriptionstringoptional

Response 201

webhook_idstringrequired

organization_idstringrequired

event_typestringrequired

urlstringrequired

descriptionstringoptional

is_activebooleanrequired

created_atstring<date-time>required

raw_secretstringrequired

POST /yieldsecure/webhooks/trigger-events

curl -X POST "https://api.cropsense.africa/yieldsecure/webhooks/trigger-events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "url",
    "description": "Notes about this record."
  }'

Example response · 201

{
  "webhook_id": "webhook_id",
  "organization_id": "organization_id",
  "event_type": "event_type",
  "url": "url",
  "description": "Notes about this record.",
  "is_active": true,
  "created_at": "2026-06-15T09:30:00Z",
  "raw_secret": "raw_secret"
}

get/yieldsecure/policies/{policy_id}/evaluations

Trigger evaluation history for a policy, with any resulting payout

Requires an Authorization: Bearer header.

Parameters

policy_idstringpathrequired

pageintegerquery

page_sizeintegerquery

Response 200

policy_idstringrequired

itemsTriggerEvaluationHistoryItem[]required

totalintegerrequired

pageintegerrequired

page_sizeintegerrequired

GET /yieldsecure/policies/{policy_id}/evaluations

curl -X GET "https://api.cropsense.africa/yieldsecure/policies/policy_id/evaluations?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response · 200

{
  "policy_id": "policy_id",
  "items": [
    {
      "evaluation_id": "evaluation_id",
      "peril": "peril",
      "trigger_index": "trigger_index",
      "observed_value": 1.5,
      "threshold": 1.5,
      "breached": true,
      "severity": 1.5,
      "as_of": "2026-06-15",
      "window_start": "2026-06-15",
      "window_end": "2026-06-15",
      "evaluated_at": "2026-06-15T09:30:00Z",
      "payout": {
        "payout_id": "payout_id",
        "amount": 1.5,
        "currency": "USD",
        "status": "status",
        "settled_at": "2026-06-15T09:30:00Z"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 1
}