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 an account with your organisation's details.
- Open Sandbox in the dashboard and press Create sandbox key. Copy the secret: it is shown once.
- Send a signed call using the example under Authentication.
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 dashboard | In the API |
|---|---|
| Bring Your Own Farmers: add a farmer, farm and loan details | POST /farmers, PUT /farmers/{id}/farm-profile, PUT /farmers/{id}/loan-application |
| Farm Verification | POST /farmers/{id}/verification |
| Assessment and reports | POST /applications/{id}/assessments, GET /reports/{id} |
| Monitoring & Evaluation: timeline and comparison | GET .../monitoring/timeline, GET .../monitoring/compare |
| Monitoring & Evaluation: schedule and updates | PUT /farmers/{id}/monitoring, POST /farmers/{id}/monitoring/runs |
| Risk Alerts: list, open, acknowledge | GET /alerts, POST /alerts/{id}/unlock, POST /alerts/{id}/acknowledge |
| Credits & Billing | GET /billing/balance, GET /billing/ledger |
| Farmers who join with your referral code | Dashboard only |
60-second quickstart
Sandbox base URL:
https://sandbox-api.cropcura.com- Make your key on the dashboard's Sandbox page. You get an
X-Partner-Key(your key id) and an HMAC secret. - Check the service is reachable, with no authentication:
GET /health - Register a farmer and submit the farm profile (signed, with
Idempotency-Key):POST /api/partner/v1/farmers, thenPUT /api/partner/v1/farmers/{id}/farm-profile - Trigger an assessment (signed, with
Idempotency-Key):POST /api/partner/v1/applications/{external_application_id}/assessments - 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:
| Header | Value |
|---|---|
X-Partner-Key | your key id |
X-Timestamp | ISO 8601 time, for example 2000-01-01T00:00:00Z |
X-Nonce | a unique string for each request |
X-Signature | lowercase 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:
METHOD
PATH
CANONICAL_QUERY_STRING
BODY_SHA256_HEX
TIMESTAMP
NONCEMETHOD: uppercase, for exampleGETorPOST.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.TIMESTAMPandNONCE: exactly the values sent in the headers.
X-Signature = hex(HMAC_SHA256(secret, canonical_string))
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.
| Scope | Allows |
|---|---|
application:read | List and fetch applications |
application:create | POST /applications |
assessment:create | Trigger an assessment; set a monitoring schedule, run a monitoring update; open and acknowledge risk alerts |
assessment:read | Read assessments, the monitoring timeline and comparison, a farm's monitoring and risk alerts |
report:read | Read the report catalog and reports; generate a report bundle |
farmer:create | POST /farmers |
farmer:read | GET /farmers and GET /farmers/{id} |
farmer:write | Submit 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:
{
"request_id": "00000000-0000-0000-0000-000000000000",
"status": "success",
"data": { },
"error": null
}{
"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.
| HTTP | Code | Meaning |
|---|---|---|
| 401 | missing_auth_headers | One of the four signing headers is missing |
| 401 | invalid_timestamp | The timestamp cannot be parsed |
| 401 | expired_timestamp | The timestamp is outside the 300 second window |
| 401 | replayed_nonce | The nonce was already used |
| 401 | invalid_signature | Signature mismatch, or the key is unknown or disabled |
| 403 | missing_scopes | The key lacks a scope this endpoint needs |
| 400 | missing_idempotency_key | An endpoint that needs Idempotency-Key did not get one |
| 409 | idempotency_conflict | The same key was reused with a different body |
| 404 | application_not_found | No such application for your institution |
| 404 | assessment_not_found | No such assessment |
| 404 | report_not_found | No such report |
| 404 | farmer_not_found | The external_farmer_id is not registered under your institution |
| 404 | alert_not_found | No such alert for your institution |
| 403 | alert_locked | The alert is locked; open it first (POST /alerts/{id}/unlock) |
| 409 | farm_profile_missing | Submit the farmer's farm profile before verifying or monitoring the farm |
| 503 | update_failed | The monitoring reading could not be taken. You were not charged. Try again |
| 422 | validation error | The body is missing a required field or has a wrong type |
Idempotency
These endpoints need an Idempotency-Key: <string> header:
POST /applicationsPOST /applications/{id}/assessmentsPOST /applications/{id}/reports/generatePOST /farmersPUT /farmers/{id}/farm-profilePUT /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.
| Method | Path | Purpose | Scope |
|---|---|---|---|
| GET | /health | Service liveness (no signing) | none |
| GET | /api/partner/v1/applications | List applications | application:read |
| GET | /api/partner/v1/applications/{id} | Fetch one application | application:read |
| POST | /api/partner/v1/applications | Create an application (BYOF) | application:create |
| POST | /api/partner/v1/applications/{id}/assessments | Trigger a run (answers 202) | assessment:create |
| GET | /api/partner/v1/applications/{id}/assessments | Assessment history | assessment:read |
| GET | /api/partner/v1/assessments/{id} | Fetch one assessment | assessment:read |
| GET | /api/partner/v1/reports/catalog | Report types the engine supports | report:read |
| GET | /api/partner/v1/applications/{id}/reports | All reports for an application | report:read |
| POST | /api/partner/v1/applications/{id}/reports/generate | Generate a PDF bundle | report:read |
| GET | /api/partner/v1/reports/{id} | Report and a fresh signed URL | report:read |
| GET | /api/partner/v1/applications/{id}/monitoring/timeline | Runs over the season | assessment:read |
| GET | /api/partner/v1/applications/{id}/monitoring/compare | Latest run against a baseline | assessment:read |
| POST | /api/partner/v1/farmers | Register a farmer (BYOF) | farmer:create |
| GET | /api/partner/v1/farmers | List your farmers | farmer:read |
| GET | /api/partner/v1/farmers/{id} | Fetch one farmer | farmer:read |
| PUT | /api/partner/v1/farmers/{id}/farm-profile | Submit a farm profile | farmer:write |
| PUT | /api/partner/v1/farmers/{id}/loan-application | Submit a loan application | farmer:write |
| POST | /api/partner/v1/farmers/{id}/verification | Verify and unlock the farm so it can be monitored | farmer:write |
| GET | /api/partner/v1/farmers/{id}/monitoring | Schedule, readings and alerts of a farm | assessment:read |
| PUT | /api/partner/v1/farmers/{id}/monitoring | Set the schedule: weekly, biweekly, monthly, on_request or off | assessment:create |
| POST | /api/partner/v1/farmers/{id}/monitoring/runs | Take a fresh satellite reading now | assessment:create |
| GET | /api/partner/v1/alerts | Risk alerts on your farmers (status=open or acknowledged) | assessment:read |
| POST | /api/partner/v1/alerts/{id}/unlock | Open an alert found between updates | assessment:create |
| POST | /api/partner/v1/alerts/{id}/acknowledge | Mark an open alert as seen | assessment:create |
| GET | /api/partner/v1/billing/balance | Your credit balance and the environment you are on | any valid key |
| GET | /api/partner/v1/billing/ledger | Your credit history | any 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.
{
"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
}{
"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
}{
"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 /applicationstakesstatus_filter,limitandcursor.POST /applications/{id}/assessmentsneedsIdempotency-Key. It answers202 Acceptedwithassessment, areportslist (each report may already be available, or still pending or failed),report_count,pollingandnotes. You can ask for specific reports withreport_keysin 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 sameIdempotency-Keyso the run is not started twice.GET /applications/{id}/assessmentstakeslimitandcursor.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/timelinereturns the runs for one application in time order over the cropping season.GET .../monitoring/comparecompares 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 /alertsshows that a risk exists on a farm but not what it is, until you callPOST /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
- Register the farmer
POST /farmersNeeds farmer:create and Idempotency-Key. Returns 201 with an internal_user_id that starts with CCP-. - Submit the farm profile
PUT /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. - Submit the loan application
PUT /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. - Create the partner application
POST /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. - Run the assessment
POST /applications/{id}/assessmentsNeeds assessment:create and Idempotency-Key. Returns 202 with assessment, reports (a list), report_count, polling and notes. - Collect the results
GET /applications/{id}/reports and GET /applications/{id}/monitoring/timelineThe PDFs, and the credit checkpoints over the season.
What each request must contain
POST /farmers
{
"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
{
"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, GovernmentwaterSource: Rain, Rainfed, Well, Borehole, River, OtherwantsSoilTest: Yes, NofarmChallenges: 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
{
"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
{
"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
Sandbox results are sample data for integration only and must not be used in credit decisions.