FIMS Public API

Overview

The FIMS API is a read-only REST API that exposes farmer registration, farm capture, cluster and aggregated analytics data. All responses are JSON.

Authentication

Every request to /api/v1/* must include a valid API token. Tokens are issued by a CCSA system administrator and take the format fims_live_{64 hex chars}.

Pass your token in one of two ways:

Option A — Authorization header (recommended)

curl https://fims.cosmopolitan.edu.ng/api/v1/farmers \
  -H "Authorization: Bearer fims_live_abc123..."

Option B — X-API-Key header

curl https://fims.cosmopolitan.edu.ng/api/v1/farmers \
  -H "X-API-Key: fims_live_abc123..."

Scopes

Each API key is granted specific scopes. Calling an endpoint that requires a scope your token does not have returns a 403 Forbidden.

Rate Limits

Rate limits are enforced per API key using a 60-second sliding window. Your token's limit is configured at creation time.

When the limit is exceeded the API responds with 429 Too Many Requests and a Retry-After: 60 header. Implement exponential back-off in your client.

Sensitive Fields & Privacy

Every response includes a meta.sensitiveFieldsExposed boolean and a meta.redactedGroups list so you always know exactly which fields are being withheld.

Farmers

curl "https://fims.cosmopolitan.edu.ng/api/v1/farmers?state=Kano&status=Enrolled&limit=20" \
  -H "X-API-Key: fims_live_abc123..."

curl "https://fims.cosmopolitan.edu.ng/api/v1/farmers/clxqp8yzf0000..." \
  -H "X-API-Key: fims_live_abc123..."

Sample response (sensitive fields redacted):

{
  "data": {
    "id": "clxqp8yzf0000abc",
    "firstName": "Aminu",
    "middleName": null,
    "lastName": "Suleiman",
    "gender": "Male",
    "state": "Kano",
    "lga": "Kano Municipal",
    "ward": "Fagge",
    "status": "Enrolled",
    "registrationDate": "2025-03-01T08:00:00.000Z",
    "nin": null,
    "bvn": null,
    "phone": null,
    "email": null,
    "cluster": { "id": "clust_001", "title": "Kano North Cluster" },
    "farms": [ { "id": "farm_001", "primaryCrop": "Maize", "farmSize": 2.5 } ]
  },
  "meta": {
    "sensitiveFieldsExposed": false,
    "redactedGroups": ["identity", "financial", "contact"],
    "note": "Identity, financial and contact fields are redacted."
  }
}

Farms

curl "https://fims.cosmopolitan.edu.ng/api/v1/farms?state=Katsina&crop=Sorghum&limit=20" \
  -H "X-API-Key: fims_live_abc123..."

curl "https://fims.cosmopolitan.edu.ng/api/v1/farms/farm_clxqp001" \
  -H "X-API-Key: fims_live_abc123..."

Clusters

curl "https://fims.cosmopolitan.edu.ng/api/v1/clusters?active=true" \
  -H "X-API-Key: fims_live_abc123..."

curl "https://fims.cosmopolitan.edu.ng/api/v1/clusters/clust_001?limit=10" \
  -H "X-API-Key: fims_live_abc123..."

Analytics

curl "https://fims.cosmopolitan.edu.ng/api/v1/analytics" \
  -H "X-API-Key: fims_live_abc123..."

{
  "data": {
    "summary": {
      "totalFarmers": 154820,
      "totalFarms": 142100,
      "totalClusters": 48,
      "totalFarmAreaHectares": 289450.5,
      "averageFarmSizeHectares": 2.04
    },
    "farmersByState": [
      { "state": "Kano", "count": 42100 },
      { "state": "Katsina", "count": 31200 }
    ],
    "farmersByGender": [
      { "gender": "Male", "count": 120400 },
      { "gender": "Female", "count": 34420 }
    ],
    "topCrops": [
      { "crop": "Maize", "farmCount": 58000 },
      { "crop": "Sorghum", "farmCount": 41200 }
    ]
  }
}

Error Codes

All errors follow this envelope:

{
  "error": "Forbidden",
  "message": "Your API key does not have the \"farms:read\" scope required for this endpoint.",
  "yourScopes": ["farmers:read", "analytics:read"]
}

Changelog

• 2026-03-24v1.0.0 — Initial release. Farmers, Farms, Clusters, Analytics endpoints. Token-based auth with granular scopes and per-key rate limiting.