Skip to content
API Reference · v3

API documentation

A single REST API for identity, verification and credit evaluation. JSON in, JSON out. Base URL https://score.farmsky.africa/v3.

Introduction

Every endpoint lives under /v3 and returns a consistent JSON envelope. Requests are authenticated with an API key; sensitive endpoints support request signing, idempotency keys and per-client rate limits. Data sources are abstracted — you consume one clean interface.

Authentication

Send your client credentials as a bearer token. Optionally sign requests with HMAC for banking-grade integrity.

Authorization: Bearer <client_id>:<client_secret>

# Optional request signing
X-Timestamp:  <unix_ms>
X-Nonce:      <random>
X-Signature:  HMAC_SHA256(secret, "<ts>.<nonce>.<method>.<path>.<sha256(body)>")

Generate and rotate credentials from the Console. Never embed a secret in client-side code.

Response format

All responses share one shape. Read success first, then data or error.

{
  "success": true,
  "data": { },
  "error": null,
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-01-01T00:00:00Z",
    "api_version": "v3",
    "environment": "live"
  }
}

Errors & rate limits

Errors return a stable machine code and a human message. Rate-limit state is returned in response headers.

StatusMeaning
400Invalid request
401Authentication failed
403Missing scope / forbidden
404Not found
409Conflict / replay detected
429Rate limit exceeded
 
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1735689600000
Customer Operations

Customer Operations

Onboarding & retrieval matching the Farmsky Customer Onboarding UI, plus plug-and-play widgets for lenders with existing websites.

POST /v3/applicants

Onboard an applicant (farmer / business).

Show example
Request body
{
  "applicant_type": "INDIVIDUAL_FARMER",
  "national_id": "31234567",
  "phone": "+254700123456",
  "farm": {
    "gps": {
      "lat": -0.2827,
      "lon": 36.0662
    },
    "crop": "MAIZE",
    "acreage_ha": 1.4
  }
}
cURL
curl -X POST "https://score.farmsky.africa/v3/applicants" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"applicant_type":"INDIVIDUAL_FARMER","national_id":"31234567","phone":"+254700123456","farm":{"gps":{"lat":-0.2827,"lon":36.0662},"crop":"MAIZE","acreage_ha":1.4}}'
GET /v3/applicants/:id

Retrieve an onboarded applicant.

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/applicants/{id}" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
GET /v3/applicants

List recent applicants.

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/applicants" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/consents

Create a granular consent record (consent ledger).

Show example
Request body
{
  "applicant_id": "appl_...",
  "scopes": [
    "CRB",
    "STATEMENTS",
    "IPRS",
    "GPS",
    "AGRONOMY"
  ]
}
cURL
curl -X POST "https://score.farmsky.africa/v3/consents" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"applicant_id":"appl_...","scopes":["CRB","STATEMENTS","IPRS","GPS","AGRONOMY"]}'
POST /v3/consents/:token/revoke

Revoke consent (propagates within 60s).

Show example
cURL
curl -X POST "https://score.farmsky.africa/v3/consents/{token}/revoke" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
GET /v3/plug-and-play/config

Get drop-in onboarding widget config & embed snippet.

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/plug-and-play/config" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
Statement & Financing Evaluation

Statement & Financing Evaluation

Automated parsing and financial scoring of M-Pesa, Till, Paybill and Bank statements with tamper detection.

POST /v3/statements/mpesa

Analyse an M-Pesa statement.

Show example
Request body
{
  "reference": "+254700123456"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/statements/mpesa" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"reference":"+254700123456"}'
POST /v3/statements/till

Analyse a Till Number statement.

Show example
Request body
{
  "reference": "5203451"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/statements/till" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"reference":"5203451"}'
POST /v3/statements/paybill

Analyse a Paybill Number statement.

Show example
Request body
{
  "reference": "888880"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/statements/paybill" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"reference":"888880"}'
POST /v3/statements/bank

Analyse a Bank statement (PDF/CSV).

Show example
Request body
{
  "reference": "KCB-2026-H1"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/statements/bank" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"reference":"KCB-2026-H1"}'
POST /v3/statements/upload

Upload a PDF statement → authenticity confidence + transaction extraction (multipart: file).

Show example
cURL
curl -X POST "https://score.farmsky.africa/v3/statements/upload" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/statements/analyse

Generic analyse with statement_type in body.

Show example
Request body
{
  "statement_type": "MPESA",
  "reference": "+254700123456"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/statements/analyse" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"statement_type":"MPESA","reference":"+254700123456"}'
Government & Identity Verification

Government & Identity Verification

Real-time National ID / alien card / citizen verification via IPRS.

POST /v3/iprs/verify

IPRS national ID verification.

Show example
Request body
{
  "national_id": "31234567"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/iprs/verify" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"national_id":"31234567"}'
Verification & Credit Data Operations

Verification & Credit Data Operations

KYC/KYB identity checks, biometrics, credit bureau (CRB) and the full composite credit/financing evaluation engine.

POST /v3/kyc

KYC — IPRS + biometric liveness for a natural person.

Show example
Request body
{
  "national_id": "31234567"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/kyc" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"national_id":"31234567"}'
POST /v3/kyb

KYB — business registration + directors.

Show example
Request body
{
  "brs_number": "PVT-XYZ12345",
  "tax_pin": "P051234567X",
  "directors": [
    {
      "national_id": "12345678",
      "shareholding_pct": 100
    }
  ]
}
cURL
curl -X POST "https://score.farmsky.africa/v3/kyb" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"brs_number":"PVT-XYZ12345","tax_pin":"P051234567X","directors":[{"national_id":"12345678","shareholding_pct":100}]}'
POST /v3/biometrics/verify

Biometric liveness + face match with configurable thresholds.

Show example
Request body
{
  "reference": "31234567",
  "t_approve": 0.85,
  "t_reject": 0.5
}
cURL
curl -X POST "https://score.farmsky.africa/v3/biometrics/verify" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"reference":"31234567","t_approve":0.85,"t_reject":0.5}'
POST /v3/crb

Credit Bureau pull (individual or business).

Show example
Request body
{
  "national_id": "31234567",
  "subject_type": "INDIVIDUAL"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/crb" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"national_id":"31234567","subject_type":"INDIVIDUAL"}'
POST /v3/credit/evaluations

Full composite credit decision (300–850 + SHAP).

Show example
Request body
{
  "applicant_type": "INDIVIDUAL_FARMER",
  "lender_reference": "LN-2026-000123",
  "applicant": {
    "national_id": "31234567",
    "phone": "+254700123456",
    "consent_token": "cst_..."
  },
  "farm": {
    "gps": {
      "lat": -0.2827,
      "lon": 36.0662
    },
    "crop": "MAIZE",
    "acreage_ha": 1.4,
    "planting_date": "2026-03-14"
  },
  "loan_application": {
    "amount_kes": 45000,
    "tenor_months": 6,
    "purpose": "INPUTS"
  }
}
cURL
curl -X POST "https://score.farmsky.africa/v3/credit/evaluations" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"applicant_type":"INDIVIDUAL_FARMER","lender_reference":"LN-2026-000123","applicant":{"national_id":"31234567","phone":"+254700123456","consent_token":"cst_..."},"farm":{"gps":{"lat":-0.2827,"lon":36.0662},"crop":"MAIZE","acreage_ha":1.4,"planting_date":"2026-03-14"},"loan_application":{"amount_kes":45000,"tenor_months":6,"purpose":"INPUTS"}}'
Transaction Operations

Transaction Operations

Digital invoicing and invoice-financing (factoring) eligibility evaluation.

POST /v3/invoices

Create a digital invoice (auto VAT).

Show example
Request body
{
  "issuer": {
    "name": "Green Agri Ltd"
  },
  "buyer": {
    "name": "Nakuru Millers"
  },
  "line_items": [
    {
      "description": "Maize 90kg bags",
      "qty": 200,
      "unit_price": 4200
    }
  ],
  "due_date": "2026-09-01"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/invoices" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"issuer":{"name":"Green Agri Ltd"},"buyer":{"name":"Nakuru Millers"},"line_items":[{"description":"Maize 90kg bags","qty":200,"unit_price":4200}],"due_date":"2026-09-01"}'
GET /v3/invoices/:id

Retrieve an invoice.

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/invoices/{id}" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/invoice-financing/evaluate

Evaluate invoice-financing / factoring eligibility.

Show example
Request body
{
  "invoice_amount_kes": 840000,
  "buyer_reference": "Nakuru Millers",
  "tenor_days": 60
}
cURL
curl -X POST "https://score.farmsky.africa/v3/invoice-financing/evaluate" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"invoice_amount_kes":840000,"buyer_reference":"Nakuru Millers","tenor_days":60}'
SDK, Workflows & Embeddable Verification

SDK, Workflows & Embeddable Verification

Drop-in client SDK plus the Workflow Builder Console (OTP-authenticated) that lets lenders assemble verification flows and embed them in native mobile & web apps. Console endpoints (/v3/app/*) require a Bearer session token; the embeddable verify runner (/v3/verify/*) is called by the SDK using a public Workflow Client ID.

GET /sdk/v1/farmsky.js

Hosted client SDK. Embed with <script src>, then call Farmsky.verify({ clientId, flow, onComplete }).

Show example
cURL
curl -X GET "https://score.farmsky.africa/sdk/v1/farmsky.js" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/auth/otp/request

Request a one-time passcode for Console sign-in (rate-limited per IP).

Show example
Request body
{
  "email": "lender@bank.co.ke"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/auth/otp/request" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"lender@bank.co.ke"}'
POST /v3/auth/otp/verify

Verify OTP → returns an opaque 7-day session token (fss_…).

Show example
Request body
{
  "email": "lender@bank.co.ke",
  "code": "123456"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/auth/otp/verify" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"lender@bank.co.ke","code":"123456"}'
GET /v3/auth/me

Current session identity (Bearer token).

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/auth/me" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/auth/logout

Revoke the current session token.

Show example
cURL
curl -X POST "https://score.farmsky.africa/v3/auth/logout" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
GET /v3/app/bootstrap

Console bootstrap: org, user, members, roles, workflows, tools, payments (Bearer).

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/app/bootstrap" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
GET /v3/app/workflows

List workflows for the org (Bearer).

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/app/workflows" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/app/workflows

Create a workflow (Bearer).

Show example
Request body
{
  "name": "Onboarding flow",
  "type": "onboarding"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/app/workflows" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Onboarding flow","type":"onboarding"}'
PUT /v3/app/workflows/:id

Update workflow settings/steps: certified timestamp, GDPR retention, redirect options, timeouts, retry block, steps (Bearer).

Show example
cURL
curl -X PUT "https://score.farmsky.africa/v3/app/workflows/{id}" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
DELETE /v3/app/workflows/:id

Delete a workflow (Bearer).

Show example
cURL
curl -X DELETE "https://score.farmsky.africa/v3/app/workflows/{id}" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
GET /v3/app/workflows/:id/integration

Reveal Client ID + SDK/webhook snippets (Bearer).

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/app/workflows/{id}/integration" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/app/workflows/:id/regenerate

Rotate the workflow Client ID + secret (Bearer).

Show example
cURL
curl -X POST "https://score.farmsky.africa/v3/app/workflows/{id}/regenerate" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
GET /v3/app/workflows/:id/history

Workflow audit trail / history (Bearer).

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/app/workflows/{id}/history" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/app/checkout/quote

Price premium modules used in a workflow before publish (Bearer).

Show example
Request body
{
  "workflow_id": "wf-uuid"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/app/checkout/quote" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"wf-uuid"}'
POST /v3/app/checkout/pay

Start M-Pesa STK push to unlock premium modules (Bearer).

Show example
Request body
{
  "workflow_id": "wf-uuid",
  "msisdn": "254712345678"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/app/checkout/pay" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"wf-uuid","msisdn":"254712345678"}'
POST /v3/app/checkout/confirm

Confirm payment & publish (sandbox completes instantly) (Bearer).

Show example
cURL
curl -X POST "https://score.farmsky.africa/v3/app/checkout/confirm" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
GET /v3/app/org

Organization profile (Bearer).

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/app/org" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
PUT /v3/app/org

Update org profile & security/compliance settings (Bearer).

Show example
cURL
curl -X PUT "https://score.farmsky.africa/v3/app/org" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
GET /v3/app/members

List members (Bearer).

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/app/members" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/app/members

Invite a member (Bearer).

Show example
Request body
{
  "email": "agent@bank.co.ke",
  "role": "Agent"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/app/members" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@bank.co.ke","role":"Agent"}'
GET /v3/app/roles

List roles & access matrix (Bearer).

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/app/roles" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/app/roles

Create a custom role (Bearer).

Show example
Request body
{
  "title": "Reviewer",
  "workflow_access": "All workflows"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/app/roles" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"title":"Reviewer","workflow_access":"All workflows"}'
POST /v3/verify/sessions

Start an embeddable verification session (SDK; header X-Workflow-Client).

Show example
Request body
{
  "flow": "wf-uuid"
}
cURL
curl -X POST "https://score.farmsky.africa/v3/verify/sessions" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"flow":"wf-uuid"}'
POST /v3/verify/sessions/:id/steps/:step

Submit a verification step (Compliance: document, face_match, proof_address, bank_statement, mobile_money, till_statement, paybill_statement, video_agreement, doc_signing, watchlist; Gov Checks: gov_id, business_verify, tax_verify; Credit Decisioning: credit_check, credit_individual, credit_business; custom).

Show example
cURL
curl -X POST "https://score.farmsky.africa/v3/verify/sessions/{id}/steps/{step}" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
GET /v3/verify/sessions/:id

Get verification session status & verdict.

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/verify/sessions/{id}" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
Bulk & Pricing

Bulk & Pricing

Batch/bulk evaluation jobs and the Admin-backed pricing catalogue that powers the on-site cost calculator (the calculator and simulator are on-site tools, not consumable product APIs).

GET /v3/pricing

Get the Admin-configured pricing catalogue.

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/pricing" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"
POST /v3/bulk/jobs

Create a batch evaluation job.

Show example
Request body
{
  "applicant_type": "INDIVIDUAL_FARMER",
  "rows": [
    {
      "applicant": {
        "national_id": "31234567",
        "consent_token": "cst_demo"
      },
      "farm": {
        "gps": {
          "lat": -0.28,
          "lon": 36.06
        },
        "crop": "MAIZE",
        "acreage_ha": 1.2
      },
      "loan_application": {
        "amount_kes": 30000,
        "tenor_months": 6,
        "purpose": "INPUTS"
      }
    }
  ]
}
cURL
curl -X POST "https://score.farmsky.africa/v3/bulk/jobs" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"applicant_type":"INDIVIDUAL_FARMER","rows":[{"applicant":{"national_id":"31234567","consent_token":"cst_demo"},"farm":{"gps":{"lat":-0.28,"lon":36.06},"crop":"MAIZE","acreage_ha":1.2},"loan_application":{"amount_kes":30000,"tenor_months":6,"purpose":"INPUTS"}}]}'
GET /v3/bulk/jobs/:id

Get bulk job status & results.

Show example
cURL
curl -X GET "https://score.farmsky.africa/v3/bulk/jobs/{id}" \
  -H "Authorization: Bearer $CLIENT_ID:$CLIENT_SECRET"