Developer API

Sandbox & API reference

A lightweight REST API to quote, enrol and collect premiums. Start with the sandbox endpoint below, then request a key to go live.

Request a sandbox key

API base URL

Use this base for all sandbox and live API calls.

API base URL

https://api.modela.co.ke

Sandbox enrolment endpoint

Simulate a farmer enrolment. No real policy is written, so you can integrate and test safely.

POST/api/v1/public/sandbox/enrol

Simulate a farmer enrolment. No real policy is written, so you can integrate and test safely.

Sandbox enrolment endpoint

POST/api/v1/public/sandbox/quote

Request a premium and sum-insured estimate for a given county, product and farmer type. No payment is taken.

Sandbox quote endpoint

POST/api/v1/public/sandbox/collect

Simulate an M-Pesa premium collection request. In sandbox, no real money is moved.

Sandbox premium collection endpoint

POST /api/v1/public/sandbox/enrol

Example request

POST /api/v1/public/sandbox/enrol
Content-Type: application/json
Authorization: Bearer $SANDBOX_TOKEN

{
  "farmer_msisdn": "+254712345678",
  "county": "Kitui",
  "product_code": "kaip-maize-2026",
  "consent_sms": true
}

Example response

{
  "success": true,
  "policy_ref": "SANDBOX-A1B2C3D4E5F6",
  "status": "pending"
}

Error example

{
  "success": false,
  "error": "consent_required",
  "message": "Farmer must confirm enrolment via SMS before cover can be activated."
}

Sandbox enrolment endpoint

farmer_msisdnrequired: Farmer phone number in E.164 format.
countyrequired: Kenyan county where the farm is located.
product_coderequired: Product code for the cover being quoted.
consent_smsrequired: Must be true — confirms SMS consent before enrolment.

Ready for live access?

Sandbox responses are synthetic. To bind real policies, request a sandbox key and we will set up partner credentials.

Request a sandbox key