Beneficiary analytics

The ‘Beneficiaries’ card payload: the distinct-beneficiary active count (+ % change vs the equal-length prior window) and a top-N-by-volume ranked list per currency. A pure read-model over Payout — nothing is stored. Results are scoped to the caller’s Business and environment.

GET /v1/reporting/beneficiaries

Beneficiaries analytics over a window for the current Business and environment

cURL

curl --request GET \
  --url https://api.example.com/v1/reporting/beneficiaries \
  --header 'Authorization: Bearer <token>'

200

{
  "active_count": 123,
  "active_count_trend_pct": 123,
  "rankings": [
    {
      "currency": "<string>",
      "top": [
        {
          "beneficiary_id": "<string>",
          "name": "<string>",
          "volume_minor": 123
        }
      ]
    }
  ]
}

Authorizations

Authorization · string · header · required

Cleff API key issued to a Business that self-registers via POST /v1/registration

Query Parameters

from · string · required

Inclusive lower bound of the window (ISO-8601 date or timestamp).

to · string · required

Inclusive upper bound of the window (ISO-8601 date or timestamp). A date-only value covers the whole day.

Response

200

application/json

active_count · number · required

Distinct beneficiaries with at least one Money-Out payout in the window.

active_count_trend_pct · number | null · required

% change in the active-beneficiary count vs the equal-length prior window. Null when the prior window had none.

rankings · object[] · required

One ranked list per currency present in the window — never blended.

Show child attributes