For banks, MFIs, insurers, farmer organisations and NGOs

Partner API Sandbox

This is a sandbox. Nothing here is charged, and every result is sample data, not a real analysis. It must not be used in credit decisions. To go live, see Go live.

Overview

Partner developers use this API to:

  • Register their own farmers, farm profiles and loan applications (Bring-Your-Own-Farmer).
  • Trigger credit assessments and monitoring updates over time, and set a monitoring schedule.
  • Receive risk alerts on their farms, open them and acknowledge them.
  • Read the monitoring timeline of a farm, compare the latest run with a baseline, and list the report types available.
  • Retrieve banker-facing PDF reports through short-lived signed URLs.

Everything described here lives under one versioned path: /api/partner/v1

CropCura also runs internal services and endpoints for its own app and tools. They are not part of this contract.

Get a sandbox key

You do not need to wait for anyone. Create an account and make your key in a minute.

Create your account
  1. Create an account with your organisation's details.
  2. Open Sandbox in the dashboard and press Create sandbox key. Copy the secret: it is shown once.
  3. Send a signed call using the example under Authentication.
Create an account

What the sandbox covers

Every part of the dashboard has a matching API call, so you can build the same journey in your own system. In the sandbox the results are sample data.

In the dashboardIn the API
Bring Your Own Farmers: add a farmer, farm and loan detailsPOST /farmers, PUT /farmers/{id}/farm-profile, PUT /farmers/{id}/loan-application
Farm VerificationPOST /farmers/{id}/verification
Assessment and reportsPOST /applications/{id}/assessments, GET /reports/{id}
Monitoring & Evaluation: timeline and comparisonGET .../monitoring/timeline, GET .../monitoring/compare
Monitoring & Evaluation: schedule and updatesPUT /farmers/{id}/monitoring, POST /farmers/{id}/monitoring/runs
Risk Alerts: list, open, acknowledgeGET /alerts, POST /alerts/{id}/unlock, POST /alerts/{id}/acknowledge
Credits & BillingGET /billing/balance, GET /billing/ledger
Farmers who join with your referral codeDashboard only

60-second quickstart

Sandbox base URL:

Base URL
https://sandbox-api.cropcura.com
  1. Make your key on the dashboard's Sandbox page. You get an X-Partner-Key (your key id) and an HMAC secret.
  2. Check the service is reachable, with no authentication: GET /health
  3. Register a farmer and submit the farm profile (signed, with Idempotency-Key): POST /api/partner/v1/farmers, then PUT /api/partner/v1/farmers/{id}/farm-profile
  4. Trigger an assessment (signed, with Idempotency-Key): POST /api/partner/v1/applications/{external_application_id}/assessments
  5. Retrieve a report (signed): GET /api/partner/v1/reports/{external_report_id}

Using your own farmers? Follow Bring-Your-Own-Farmer.

Authentication

Every endpoint under /api/partner/v1/* must be signed. Send these four headers:

HeaderValue
X-Partner-Keyyour key id
X-TimestampISO 8601 time, for example 2000-01-01T00:00:00Z
X-Noncea unique string for each request
X-Signaturelowercase hex HMAC-SHA256 of the canonical string

Timestamp window and nonce

The timestamp must be within 300 seconds of the server's clock, in either direction. A nonce can be used once per key within that window. Reusing it is rejected.

Canonical string

Six values joined with a single newline, with no trailing newline:

Canonical string
METHOD
PATH
CANONICAL_QUERY_STRING
BODY_SHA256_HEX
TIMESTAMP
NONCE
  • METHOD: uppercase, for example GET or POST.
  • PATH: the request path only, with the leading slash, for example /api/partner/v1/applications.
  • CANONICAL_QUERY_STRING: the query parameters sorted by name and then value, URL-encoded and joined with &. Empty when there is no query.
  • BODY_SHA256_HEX: sha256(raw_request_body_bytes) as hex. For a request with no body, this is the hash of the empty string.
  • TIMESTAMP and NONCE: exactly the values sent in the headers.

X-Signature = hex(HMAC_SHA256(secret, canonical_string))

Python example
import hashlib, hmac, uuid, urllib.parse
from datetime import datetime, timezone

def sign(secret, method, path, query, body_bytes):
    ts = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
    nonce = uuid.uuid4().hex
    qs = urllib.parse.urlencode(sorted(urllib.parse.parse_qsl(query, keep_blank_values=True)))
    canonical = "\n".join([method.upper(), path, qs, hashlib.sha256(body_bytes).hexdigest(), ts, nonce])
    sig = hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()
    return {"X-Timestamp": ts, "X-Nonce": nonce, "X-Signature": sig}

Send the same body bytes you hashed. If your HTTP library re-serialises the JSON, the signature will not match.

Scopes

Scopes are attached to your key and checked on each endpoint.

ScopeAllows
application:readList and fetch applications
application:createPOST /applications
assessment:createTrigger an assessment; set a monitoring schedule, run a monitoring update; open and acknowledge risk alerts
assessment:readRead assessments, the monitoring timeline and comparison, a farm's monitoring and risk alerts
report:readRead the report catalog and reports; generate a report bundle
farmer:createPOST /farmers
farmer:readGET /farmers and GET /farmers/{id}
farmer:writeSubmit a farm profile and a loan application for a farmer; verify a farm

Standard partners usually hold application:read, assessment:create, assessment:read and report:read. BYOF partners also receive application:create, farmer:create, farmer:read and farmer:write. A sandbox key holds every scope.

A key without the required scope gets 403 with code missing_scopes.

Responses and errors

Successful responses and resource errors use one envelope:

Success
{
  "request_id": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "data": { },
  "error": null
}
Error
{
  "request_id": "00000000-0000-0000-0000-000000000000",
  "status": "error",
  "data": null,
  "error": { "code": "application_not_found", "message": "Application was not found." }
}

Errors raised by the authentication, scope and idempotency checks come back as {"detail": {"code": "...", "message": "..."}} instead. In both cases read code to tell what went wrong.

List endpoints return data.items and data.next_cursor. Send next_cursor back as cursor to get the next page. limit defaults to 50.

Error codes

A few more errors only appear on live. They are explained in the Live guide in your dashboard, which opens once you tell us you have tested.

HTTPCodeMeaning
401missing_auth_headersOne of the four signing headers is missing
401invalid_timestampThe timestamp cannot be parsed
401expired_timestampThe timestamp is outside the 300 second window
401replayed_nonceThe nonce was already used
401invalid_signatureSignature mismatch, or the key is unknown or disabled
403missing_scopesThe key lacks a scope this endpoint needs
400missing_idempotency_keyAn endpoint that needs Idempotency-Key did not get one
409idempotency_conflictThe same key was reused with a different body
404application_not_foundNo such application for your institution
404assessment_not_foundNo such assessment
404report_not_foundNo such report
404farmer_not_foundThe external_farmer_id is not registered under your institution
404alert_not_foundNo such alert for your institution
403alert_lockedThe alert is locked; open it first (POST /alerts/{id}/unlock)
409farm_profile_missingSubmit the farmer's farm profile before verifying or monitoring the farm
503update_failedThe monitoring reading could not be taken. You were not charged. Try again
422validation errorThe body is missing a required field or has a wrong type

Idempotency

These endpoints need an Idempotency-Key: <string> header:

  • POST /applications
  • POST /applications/{id}/assessments
  • POST /applications/{id}/reports/generate
  • POST /farmers
  • PUT /farmers/{id}/farm-profile
  • PUT /farmers/{id}/loan-application

Sending the same key with the same body returns the original response. Sending the same key with a different body returns 409 idempotency_conflict.

Data model

Application

A loan application you created for one of your farmers. external_application_id, external_customer_id, status (accepted, validated, rejected, archived), submitted_at (optional), applicant, farm, external_farmer_id (BYOF only).

Assessment

One execution of the monitoring workflow. external_assessment_id, external_application_id, status (queued, processing, completed, failed, cancelled), stage (validation, profile_mapping, satellite_evaluation, credit_scoring, report_generation, completed, failed), and notes (text for debugging an integration).

Report

A PDF tied to an assessment. external_report_id, external_assessment_id, status (pending, available, failed), download_url (a signed URL, only when available), expires_at.

The public contract exposes status and the PDF report. It does not expose a stable raw analysis JSON.

Endpoints

These are the same calls on the sandbox and on live. On the sandbox every answer is sample data, not a real analysis: the scores, readings, alerts and report PDFs are example values.

MethodPathPurposeScope
GET/healthService liveness (no signing)none
GET/api/partner/v1/applicationsList applicationsapplication:read
GET/api/partner/v1/applications/{id}Fetch one applicationapplication:read
POST/api/partner/v1/applicationsCreate an application (BYOF)application:create
POST/api/partner/v1/applications/{id}/assessmentsTrigger a run (answers 202)assessment:create
GET/api/partner/v1/applications/{id}/assessmentsAssessment historyassessment:read
GET/api/partner/v1/assessments/{id}Fetch one assessmentassessment:read
GET/api/partner/v1/reports/catalogReport types the engine supportsreport:read
GET/api/partner/v1/applications/{id}/reportsAll reports for an applicationreport:read
POST/api/partner/v1/applications/{id}/reports/generateGenerate a PDF bundlereport:read
GET/api/partner/v1/reports/{id}Report and a fresh signed URLreport:read
GET/api/partner/v1/applications/{id}/monitoring/timelineRuns over the seasonassessment:read
GET/api/partner/v1/applications/{id}/monitoring/compareLatest run against a baselineassessment:read
POST/api/partner/v1/farmersRegister a farmer (BYOF)farmer:create
GET/api/partner/v1/farmersList your farmersfarmer:read
GET/api/partner/v1/farmers/{id}Fetch one farmerfarmer:read
PUT/api/partner/v1/farmers/{id}/farm-profileSubmit a farm profilefarmer:write
PUT/api/partner/v1/farmers/{id}/loan-applicationSubmit a loan applicationfarmer:write
POST/api/partner/v1/farmers/{id}/verificationVerify and unlock the farm so it can be monitoredfarmer:write
GET/api/partner/v1/farmers/{id}/monitoringSchedule, readings and alerts of a farmassessment:read
PUT/api/partner/v1/farmers/{id}/monitoringSet the schedule: weekly, biweekly, monthly, on_request or offassessment:create
POST/api/partner/v1/farmers/{id}/monitoring/runsTake a fresh satellite reading nowassessment:create
GET/api/partner/v1/alertsRisk alerts on your farmers (status=open or acknowledged)assessment:read
POST/api/partner/v1/alerts/{id}/unlockOpen an alert found between updatesassessment:create
POST/api/partner/v1/alerts/{id}/acknowledgeMark an open alert as seenassessment:create
GET/api/partner/v1/billing/balanceYour credit balance and the environment you are onany valid key
GET/api/partner/v1/billing/ledgerYour credit historyany valid key

Sample responses

Every value on this page is dummy data. The sandbox answers in the same shape as live, with sample values like these.

POST /farmers/{id}/monitoring/runs
{
  "request_id": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "data": {
    "external_farmer_id": "sample-farmer-001",
    "run_id": "sample-run-001",
    "ndvi": 0.61,
    "charged_ngn": 0.0,
    "balance_ngn": null,
    "new_alerts": [
      { "severity": "medium", "title": "Moderate drought stress risk (sample)", "message": "Sample alert. Every value on the sandbox is dummy data." }
    ]
  },
  "error": null
}
GET /alerts
{
  "request_id": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "data": {
    "items": [
      { "id": "sample-alert-001", "external_farmer_id": "sample-farmer-001", "severity": "medium",
        "locked": true, "status": "open", "title": "Risk found", "message": null, "created_at": "2000-01-01T00:00:00Z" }
    ]
  },
  "error": null
}
POST /applications/{id}/assessments (shortened)
{
  "request_id": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "data": {
    "assessment": { "external_assessment_id": "asmt_sample000001", "status": "completed", "stage": "completed" },
    "reports": [
      { "external_report_id": "rpt_sample000001", "report_key": "field-readiness-story", "status": "available",
        "download_url": "https://example.com/sample-report.pdf", "expires_at": "2000-01-01T00:15:00Z" }
    ],
    "report_count": { "total": 1, "available": 1, "failed": 0 }
  },
  "error": null
}

Notes on individual endpoints

  • GET /applications takes status_filter, limit and cursor.
  • POST /applications/{id}/assessments needs Idempotency-Key. It answers 202 Accepted with assessment, a reports list (each report may already be available, or still pending or failed), report_count, polling and notes. You can ask for specific reports with report_keys in the body. The call waits while the engine works and the reports are built. On the sandbox it answers quickly with sample data. Set your HTTP client timeout to at least 120 seconds anyway, and do not retry before it returns. If you do retry, send the same Idempotency-Key so the run is not started twice.
  • GET /applications/{id}/assessments takes limit and cursor.
  • GET /reports/{id} returns a short-lived signed URL (about 15 minutes). Download it straight away, or call the endpoint again for a fresh one.
  • GET .../monitoring/timeline returns the runs for one application in time order over the cropping season.
  • GET .../monitoring/compare compares two runs and reports the satellite-derived health changes and changes in the risk profile.
  • The verification, monitoring and alert routes work on farmers you registered with POST /farmers. On the sandbox a farm needs only its farm profile, nothing is charged, and the results are sample data.
  • Alerts found between monitoring updates are locked: GET /alerts shows that a risk exists on a farm but not what it is, until you call POST /alerts/{id}/unlock. A locked alert cannot be acknowledged.

Bring-Your-Own-Farmer (BYOF)

BYOF lets a partner register its own farmers, submit farm profiles and loan applications, and run credit and satellite assessments and reports the same way as for farmers CropCura shares. It suits partners that keep their own CRM or loan-origination system and want to use CropCura scoring as a service.

The flow

  1. Register the farmerPOST /farmersNeeds farmer:create and Idempotency-Key. Returns 201 with an internal_user_id that starts with CCP-.
  2. Submit the farm profilePUT /farmers/{id}/farm-profileNeeds farmer:write and Idempotency-Key. Boundaries and crops. If boundaryAreaSqMeters is left out, the system works it out from the boundary.
  3. Submit the loan applicationPUT /farmers/{id}/loan-applicationNeeds farmer:write and Idempotency-Key. Returns a stable application_key based on the applicant's phone number, normalised to Nigerian format.
  4. Create the partner applicationPOST /applicationsNeeds application:create and Idempotency-Key. Send the external_farmer_id and the internal ids are filled in from the farmer you registered. If that farmer is not registered you get 404 farmer_not_found.
  5. Run the assessmentPOST /applications/{id}/assessmentsNeeds assessment:create and Idempotency-Key. Returns 202 with assessment, reports (a list), report_count, polling and notes.
  6. Collect the resultsGET /applications/{id}/reports and GET /applications/{id}/monitoring/timelineThe PDFs, and the credit checkpoints over the season.

What each request must contain

POST /farmers

POST /farmers body
{
  "external_farmer_id": "sample-farmer-001",
  "applicant": {
    "full_name": "Sample Farmer",
    "phone": "+2340000000000",
    "national_id": "SAMPLE-0000"
  },
  "display_name": "Sample",
  "metadata": {}
}

Required: external_farmer_id (up to 120 characters) and applicant.full_name. applicant.phone and applicant.national_id are optional. Send the phone in international format (+234...) when you have it.

PUT /farmers/{id}/farm-profile

PUT /farmers/{id}/farm-profile body
{
  "yearsOfExperience": 6,
  "fields": [
    {
      "boundary": [
        { "latitude": 0.0000, "longitude": 0.0000 },
        { "latitude": 0.0000, "longitude": 0.0010 },
        { "latitude": 0.0010, "longitude": 0.0010 },
        { "latitude": 0.0010, "longitude": 0.0000 }
      ],
      "boundaryAreaSqMeters": 10000,
      "crops": [
        {
          "cropName": "Maize",
          "variety": "Sample variety",
          "dateOfPlanting": "2000-01-01",
          "expectedHarvestDate": "2000-06-01",
          "landRights": "Owned",
          "waterSource": "Rain",
          "wantsSoilTest": "Yes",
          "farmChallenges": "Pests",
          "photoPaths": []
        }
      ]
    }
  ]
}

Required for every field: boundary (a list of points, each with numeric latitude and longitude) and crops (at least one). Required for every crop: cropName, variety, dateOfPlanting, expectedHarvestDate, landRights, waterSource, wantsSoilTest, farmChallenges and photoPaths (a list, which may be empty). Allowed values:

  • landRights: Owned, Leased, Family, Community, Government
  • waterSource: Rain, Rainfed, Well, Borehole, River, Other
  • wantsSoilTest: Yes, No
  • farmChallenges: Yield, Soil Health, Irrigation, Access to Inputs, Others, Pests

A wrong value is refused with 422. A successful save returns data.farm_profile with status (saved), internal_user_id, farm_profile_version and updated_at.

PUT /farmers/{id}/loan-application

PUT /farmers/{id}/loan-application body
{
  "farmerIdentification": {
    "phoneNumber": "+2340000000000",
    "legalName": "Sample Farmer",
    "farmerProfilePicture": "https://example.com/sample-face.jpg",
    "governmentIdPhoto": "https://example.com/sample-id.jpg"
  },
  "marketAccess": {},
  "financialBehavior": {},
  "creditHistory": {},
  "financeDetails": { "amountRequested": 100000 },
  "otherInfo": {}
}

Required: farmerIdentification with phoneNumber, legalName, farmerProfilePicture and governmentIdPhoto. The other blocks are optional objects. A missing required value is refused with 422. A successful save returns data.loan_application with status, internal_user_id, internal_loan_application_id, application_key and updated_at.

POST /applications

POST /applications body
{
  "external_application_id": "sample-app-001",
  "external_customer_id": "sample-customer-001",
  "submitted_at": "2000-01-01T00:00:00Z",
  "applicant": { "full_name": "Sample Farmer" },
  "farm": { "declared_crop": "Maize", "declared_area_ha": 1.0, "season": "2000A" },
  "external_farmer_id": "sample-farmer-001",
  "metadata": {}
}

Required: external_application_id, external_customer_id, applicant.full_name and a farm block with declared_crop. declared_area_ha, season, geometry, bbox, submitted_at, external_farmer_id and metadata are optional. A request without a farm block is refused with 422.

The internal user id

Your external_farmer_id is mapped to an internal_user_id of the form CCP-<partner id>-<first 20 hex of sha256(partner id::external farmer id)>. The mapping is fixed, so a retry gives the same id. The same external id sent by a different partner gives a different id, so institutions are kept apart. Phone numbers, e-mail addresses and government ids are not stored in the core user table.

Reports

Each assessment produces its reports in the same call. A report's status is available when its PDF is ready, with a signed download_url and expires_at. If it is pending or failed, call GET /reports/{id} again later: the service retries the generation.

Go live

To go live, create an account and test your integration on the sandbox.Then request live access from your dashboard. CropCura reviews it separately from the approval of your account, and we email you when live access is open.
Create an account

Sandbox results are sample data for integration only and must not be used in credit decisions.