FlockDash Lender API

Overview

The FlockDash Lender API gives financial institutions programmatic access to the Farm Health Score — a verified creditworthiness rating derived from a farm's actual production and financial records. Unlike self-reported income figures, FlockDash scores are based on data entered daily by the farmer: feed consumption, weight records, mortality logs, sales orders, and health events.

Banks and MFIs in Rwanda, Uganda, and Kenya use this data to make faster, better-informed lending decisions for smallholder farmers who lack traditional credit history.

Authentication

All API requests must include your API key as a Bearer token in the Authorization header. API keys are issued by FlockDash Africa and are scoped to your institution.

Authorization: Bearer fos_your_api_key_here

How authentication works

FlockDash uses a prefix + bcrypt hash scheme for secure key storage. When you send a request:

• The server reads the first 8 characters of your key (the prefix) to pre-filter the database
• It then runs a bcrypt verify against the stored hash of the full key
• The raw key is never stored — only the hash

This means your key cannot be recovered if lost. Rotation issues a new key and immediately revokes the old one.

Base URL & Versioning

Quick Start (5 minutes)

Make your first API call in under 5 minutes using cURL or any HTTP client.

curl -X GET \
  "https://api.flockdash.com/api/v1/lender/score/green-hills-farm" \
  -H "Authorization: Bearer fos_your_api_key_here" \
  -H "Accept: application/json"

// Node.js or browser (with CORS enabled)
const response = await fetch(
  'https://api.flockdash.com/api/v1/lender/score/green-hills-farm',
  {
    headers: {
      'Authorization': 'Bearer fos_your_api_key_here',
      'Accept': 'application/json',
    }
  }
);
const data = await response.json();
console.log(data.score.grade);  // "AA"

import requests

API_KEY = "fos_your_api_key_here"
FARM_SLUG = "green-hills-farm"

response = requests.get(
    f"https://api.flockdash.com/api/v1/lender/score/{FARM_SLUG}",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Accept": "application/json",
    }
)
data = response.json()
print(data["score"]["grade"])  # "AA"

$apiKey   = 'fos_your_api_key_here';
$farmSlug = 'green-hills-farm';
$url      = "https://api.flockdash.com/api/v1/lender/score/{$farmSlug}";

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer {$apiKey}",
        "Accept: application/json",
    ],
]);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
echo $data['score']['grade'];  // "AA"

GET /score/{slug} — Score Summary

Returns the latest Farm Health Score for a farm, identified by its unique slug. This is the most commonly used endpoint for loan assessment workflows. Consumes 1 quota call.

{
  "farm": {
    "name":    "Green Hills Farm Ltd",
    "slug":    "green-hills-farm",
    "country": "Rwanda"
  },
  "score": {
    "overall":              82,
    "grade":               "AA",
    "grade_label":         "Very strong",
    "recommendation":      "approve",
    "recommendation_label": "Approve"
  },
  "pillars": {
    "production":  88,
    "financial":   79,
    "consistency": 84,
    "health":      91,
    "repayment":   72
  },
  "metadata": {
    "score_id":          "01hx8kz...",
    "generated_at":      "2026-05-10T08:23:11+00:00",
    "batches_analysed":   7,
    "months_of_data":     14,
    "data_from":          "2025-03-01",
    "data_to":            "2026-05-10"
  }
}

GET /score/{slug}/full — Full Score Detail

Returns the complete score with pillar-level detail, batch performance data, financial breakdown, risk flags, strengths, and improvement recommendations. Requires the full scope on your API key. Consumes 1 quota call.

"production_detail": {
  "avg_fcr":        1.87,
  "avg_mortality":  2.4,
  "fcr_score":      92,
  "mort_score":     88,
  "batch_count":    7,
  "fcr_benchmark":  1.9,
  "mort_benchmark": 3.0,
  "batches": [
    {
      "code":         "BATCH-2026-007",
      "species":      "Chicken",
      "fcr":          1.82,
      "mortality_pct": 2.1,
      "margin_pct":   23.4,
      "start":        "Feb 2026"
    }
  ]
}

GET /quota — Quota Status

Returns your current API key's quota status. Does not consume a quota call. Use this before processing a batch of loan applications to confirm you have sufficient calls remaining.

{
  "lender":          "Bank of Kigali",
  "monthly_quota":  500,
  "calls_used":      127,
  "calls_remaining": 373,
  "reset_date":      "2026-06-01"
}

GET /credit/shared/{token} — Shared Score (No Auth)

Farmers can generate a time-limited share link from their FlockDash dashboard and send it to a loan officer. This endpoint serves the HTML report — it requires no API key, just the token from the URL. Does not consume quota.

Score Model — How Scores Are Calculated

The Farm Health Score is a weighted composite of five pillars, each drawing on a different dimension of farm management data recorded in FlockDash. No self-reported figures are used — all inputs come from daily operational records.

Grade Scale

Error Codes

All error responses follow the same JSON structure: { "error": "Human-readable message" }. Some errors include additional fields.

Quota exhaustion error (429)

{
  "error":      "Monthly quota exhausted.",
  "quota":      200,
  "used":       200,
  "reset_date": "2026-06-01"
}

When you receive a 429, log the reset_date in your system. You can purchase a top-up via the Lender Portal or email support@flockdash.com.

Quota & Billing

API calls are priced per-call with monthly quotas. Your quota resets on the 1st of each calendar month (East Africa Time). Top-ups can be purchased at any time and are added immediately to your monthly quota.

Rate Limits

In addition to monthly quotas, the following per-second and per-minute limits apply:

Response headers include rate-limit context: X-RateLimit-Remaining, X-RateLimit-Reset. Implement exponential backoff with jitter when you receive a 429 rate-limit response.

API Key Scopes

Each API key is issued with one or more scopes that control access level. Contact support@flockdash.com to request additional scopes.

Changelog

LOS Integration Guide

This guide shows how to integrate FlockDash scores into a typical Loan Origination System (LOS) workflow. The goal is to pull the score automatically when a loan application is received and attach it to the borrower's file.

Recommended integration flow

1. At application intake: Ask the borrower for their FlockDash slug (visible in their FlockDash dashboard URL or Settings page).
2. Check quota: Call GET /quota to confirm calls are available before the lookup.
3. Fetch score: Call GET /score/{slug}. Store score.overall, score.grade, score.recommendation, and metadata.score_id in your LOS against the application record.
4. Route the application: Use score.recommendation as a soft routing signal — strong_approve/approve to fast-track review, conditional/review to analyst queue, decline for automated rejection letter with appeal process.
5. Loan officer view: For manual review cases, display the pillars breakdown. If you have full scope, surface the flags and recommendations arrays to help the analyst ask the right questions.
6. Record keeping: Store metadata.score_id in your loan file. This allows FlockDash support to pull the exact score snapshot used for your decision if ever needed for audit or dispute purposes.

Complete Node.js integration example

// flockdash-client.js — reusable FlockDash API client

const BASE_URL = 'https://api.flockdash.com/api/v1/lender';
const API_KEY  = process.env.FLOCKDASH_API_KEY;  // store in env, never hardcode

async function flockdashRequest(path) {
  const res = await fetch(`${BASE_URL}${path}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Accept': 'application/json',
    },
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`FlockDash API ${res.status}: ${err.error}`);
  }
  return res.json();
}

// Check quota before processing a batch
async function checkQuota() {
  const q = await flockdashRequest('/quota');
  if (q.calls_remaining < 5) {
    console.warn('⚠️  Low quota:', q.calls_remaining, 'calls remaining');
  }
  return q;
}

// Fetch and attach score to a loan application
async function attachScoreToApplication(application) {
  const { flockdashSlug, applicationId } = application;

  try {
    const data = await flockdashRequest(`/score/${flockdashSlug}`);

    return {
      applicationId,
      flockdashScoreId:      data.metadata.score_id,
      overallScore:       data.score.overall,
      grade:              data.score.grade,
      recommendation:     data.score.recommendation,
      batchesAnalysed:    data.metadata.batches_analysed,
      monthsOfData:       data.metadata.months_of_data,
      scoredAt:           data.metadata.generated_at,
      pillars:            data.pillars,
      // Routing signal
      autoApprove: ['strong_approve', 'approve'].includes(data.score.recommendation),
      requiresReview: ['conditional', 'review'].includes(data.score.recommendation),
    };
  } catch (err) {
    // Score not available — flag for manual assessment
    return { applicationId, error: err.message, requiresManual: true };
  }
}

module.exports = { checkQuota, attachScoreToApplication };

Webhook Setup

FlockDash can notify your system when a farm generates a new score — useful for proactively refreshing scores for farms you have existing loans with.

Webhook payload

When a farm in your monitored list generates a new score, FlockDash sends a POST request to your endpoint:

{
  "event":      "score.generated",
  "farm_slug":  "green-hills-farm",
  "score_id":   "01hx8kz...",
  "grade":      "AA",
  "overall":    82,
  "generated_at": "2026-05-10T08:23:11+00:00"
}

Verify the authenticity of webhook calls by checking the X-FlockDash-Signature header (HMAC-SHA256 of the request body using your webhook secret).

Sandbox & Testing

A sandbox environment is available for integration testing. The sandbox is pre-populated with five test farms with different score profiles.

Test farm slugs