DEVELOPER DOCS · v1

Partner verification API

Send your farmers and plot boundaries. We check them against our records, run the deforestation analysis, and return a risk result for each plot.

Base URL: https://YOUR-DOMAIN/api/v1/. All requests and responses are JSON over HTTPS. Pricing, tokens and daily limits are set by the administrator for your plan.

Authentication

Send your key in the x-api-key header. Keys are created by the administrator under API & partners and are shown once. Keep them secret and never put them in browser code.

x-api-key: fk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST /verify.php

Starts a verification. Up to 2000 plots per request.

FieldTypeNotes
farmers[]arrayRequired. One entry per farmer.
farmers[].refstringYour own farmer id. Returned to you.
farmers[].namestringRecommended.
farmers[].national_idstringStrongly recommended. Used to recognise people we already know.
farmers[].plots[].refstringYour plot id.
farmers[].plots[].geometryGeoJSONPolygon or Point, coordinates as [longitude, latitude]. Or send lat and lng instead.
farmers[].plots[].area_hanumberHectares.
crop, variety, seasonstringOptional context, e.g. Coffee, Robusta.
contributebooleantrue means you agree that verified records may be added to our database. Default false: nothing is stored beyond your own submission.
{
  "contribute": true, "crop": "Coffee", "variety": "Robusta",
  "farmers": [{
    "ref": "F-100", "name": "Jane Example", "national_id": "CF85000000000A",
    "plots": [{ "ref": "P-1", "area_ha": 1.2,
      "geometry": { "type": "Polygon", "coordinates": [[[31.6001,-0.1501],[31.6010,-0.1501],[31.6010,-0.1510],[31.6001,-0.1510],[31.6001,-0.1501]]] } }]
  }]
}

Response 202 (verification started) or 200 (everything was already known):

{ "code": "analysis_queued",
  "data": { "submission": "SUB-261105-A1B2C3", "status": "verifying",
            "matched": [ { "plot_ref": "P-9", "our_plot_id": "PLT-000412", "our_farmer_id": "FRM-000230", "match": "plot_overlap",
                           "message": "Already in our database. Use these ids instead of creating new records." } ],
            "to_verify": 1, "errors": [], "tokens_to_charge": 1 } }

GET /status.php?ref=SUB-…

Poll every 5 to 10 seconds until status is completed (or failed). You can only see your own submissions.

{ "code": "analysis_completed",
  "data": { "submission": "SUB-261105-A1B2C3", "status": "completed", "matched_plots": 1, "verified_plots": 1,
    "result": { "verified": [ { "plot_ref": "P-1", "farmer_ref": "F-100",
                  "risk_perennial_crop": "low", "risk_annual_crop": "low", "risk_timber": "low", "overall": "low",
                  "our_plot_id": "PLT-000501", "our_farmer_id": "FRM-000311", "note": "Added to our database. Use these ids from now on." } ],
                "matched": [], "errors": [] } } }

Risk values: low, more_info_needed, high. overall is the risk for the crop type chosen by the administrator (perennial crops, such as coffee, by default). The our_*_id fields appear only when you set contribute to true.

Avoiding duplicates

Before anything is verified we look for each plot in our records: a farmer with the same national_id, or any plot whose location is within about 20 metres. A match is not added again and is not charged. We return our IDs in matched. Please store them against your own records and use them in future requests.

Only data you contributed (with contribute: true) is ever added to our database, and it is linked back to your references.

Limits, tokens and prices

Errors

HTTPcodeMeaning
400invalid_json / invalid_requestBody is not valid or has no farmers.
401unauthorizedMissing, wrong or revoked key.
402insufficient_tokensTop up tokens.
403api_disabledAPI is not enabled for your plan.
404not_foundUnknown submission reference.
413too_largeMore than 2000 plots.
429rate_limitedDaily limit reached.
502verification_unavailableAnalysis service unreachable. Nothing was charged. Retry later.

Per-plot problems (for example a missing geometry) do not fail the whole request. They are listed in errors.

Code samples

curl

curl -X POST https://YOUR-DOMAIN/api/v1/verify.php \
  -H "x-api-key: $FISKON_KEY" -H "Content-Type: application/json" \
  -d @submission.json
curl "https://YOUR-DOMAIN/api/v1/status.php?ref=SUB-261105-A1B2C3" -H "x-api-key: $FISKON_KEY"

Python

import os, time, requests
BASE, H = "https://YOUR-DOMAIN/api/v1", {"x-api-key": os.environ["FISKON_KEY"]}
sub = requests.post(f"{BASE}/verify.php", headers=H, json=payload, timeout=60)
sub.raise_for_status(); ref = sub.json()["data"]["submission"]
while True:
    r = requests.get(f"{BASE}/status.php", headers=H, params={"ref": ref}, timeout=60).json()
    if r["data"]["status"] in ("completed", "failed"): break
    time.sleep(8)
print(r["data"]["result"])

JavaScript (Node 18+)

const BASE = "https://YOUR-DOMAIN/api/v1", H = { "x-api-key": process.env.FISKON_KEY, "Content-Type": "application/json" };
const sub = await (await fetch(`${BASE}/verify.php`, { method: "POST", headers: H, body: JSON.stringify(payload) })).json();
const ref = sub.data.submission; let r;
do { await new Promise(s => setTimeout(s, 8000)); r = await (await fetch(`${BASE}/status.php?ref=${ref}`, { headers: H })).json(); }
while (!["completed", "failed"].includes(r.data.status));
console.log(r.data.result);

PHP

$ch = curl_init("https://YOUR-DOMAIN/api/v1/verify.php");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["x-api-key: " . getenv("FISKON_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode($payload)]);
$res = json_decode(curl_exec($ch), true); $ref = $res["data"]["submission"];

Ready-to-run versions are in docs/samples/.