LEAP MIS | PSP Statistics API

Overview

The PSP Statistics API returns household and caregiver counts for the authenticated PSP, nested by region → district → community.

Base path: /api/v1/psp_statistics (alias /api/v1/psp-statistics)
Grouping: household region_code, district_code, community_code

Auth follows the same PSP session pattern as PSP Enrollment.

Authentication

Sign in with POST /api/v1/session. Send the session token on every request:

token: YOUR_SESSION_TOKEN
Authorization: Bearer YOUR_SESSION_TOKEN
x-access-token: YOUR_SESSION_TOKEN

Your account organisation_code must match an active PSP uniqueCode. Otherwise the API returns 403. Missing tokens return 401.

GET statistics

GET /api/v1/psp_statistics

Returns nested caregiver statistics for households assigned to the session PSP. Optional location filters restrict counts to matching household location columns.

Query parameters

Name	Type	Description
`region_code`	string	Optional. Match `lpm_households_selected_all.region_code` (e.g. `02`).
`district_code`	string	Optional. Match `lpm_households_selected_all.district_code` (e.g. `02-03`).
`community_code`	string	Optional. Match `lpm_households_selected_all.community_code` (e.g. `02-03-006`).

Filters may be combined with AND. Applied filters are echoed in the response filter object; otherwise filter is null.

Example request

curl -X GET "https://YOUR_HOST/api/v1/psp_statistics" \
  -H "token: YOUR_SESSION_TOKEN"

curl -X GET "https://YOUR_HOST/api/v1/psp_statistics?region_code=02&district_code=02-03" \
  -H "token: YOUR_SESSION_TOKEN"

Example response

{
  "successful": true,
  "psp": {
    "id": 9,
    "uniqueCode": "GHIPSS",
    "name": "Ghana Interbank Payment and Settlement Systems"
  },
  "filter": {
    "region_code": "02",
    "district_code": "02-03"
  },
  "totals": {
    "householdCount": 120,
    "primaryCaregiverCount": 118,
    "secondaryCaregiverCount": 95,
    "caregiverRequestCount": 3400,
    "caregiverResponseCount": 210
  },
  "data": [
    {
      "regionCode": "02",
      "regionName": "Ashanti",
      "householdCount": 120,
      "primaryCaregiverCount": 118,
      "secondaryCaregiverCount": 95,
      "caregiverRequestCount": 3400,
      "caregiverResponseCount": 210,
      "districts": [
        {
          "districtCode": "02-03",
          "districtName": "Example District",
          "paymentProviderId": 3,
          "pspName": "Example PSP",
          "pspCode": "PSP-EX",
          "householdCount": 120,
          "primaryCaregiverCount": 118,
          "secondaryCaregiverCount": 95,
          "caregiverRequestCount": 3400,
          "caregiverResponseCount": 210
        }
      ]
    }
  ]
}

Response shape

Envelope

Field	Notes
`successful`	`true` on success.
`psp`	Resolved PSP `id`, `uniqueCode`, and `name`.
`filter`	Applied location filters, or `null`.
`totals`	Sum of counts across the returned tree.
`data`	Array of region nodes (see below).

Count fields (every level)

Field	Notes
`householdCount`	Distinct households with a non-empty `gnhrHouseholdUUID`.
`primaryCaregiverCount`	Named primary caregivers linked to those households.
`secondaryCaregiverCount`	Named secondary caregivers linked to those households.
`caregiverRequestCount`	Rows in `lpm_psp_caregiver_requests` for the PSP (joined to selected households).
`caregiverResponseCount`	Subset of those request rows with a response received (`response_action`, `response_ts`, or `response_payload` set).
`paymentProviderId` / `pspName` / `pspCode`	District rows only: assigned payment service provider for households in that district.

Nesting

Region: regionCode, regionName, rolled-up counts, districts[]
District: districtCode, districtName, paymentProviderId, pspName, pspCode, counts

Aggregates stop at district (no community level). When multiple PSPs have households in the same district, that district appears once per PSP.

Errors

HTTP	When
`401`	No valid session token.
`403`	Session is not a registered/active PSP.
`405`	Unsupported method (POST / PUT / DELETE).
`500`	Database or server error.

PSP Statistics API

On this page