Cowdidocs
API ReferenceAgents

Get customer insights

GET
/v1/agents/me/customers/{customerId}/insights

Get aggregate insights for one customer: account count, overdue installments, outstanding balance, and activity status. Requires the org:agents:read permission. Available for a customer assigned to the caller or to an agent the caller supervises. inactive_threshold_days sets when the customer counts as INACTIVE rather than ACTIVE. Returns 404 when the caller is not an agent, the customer has no active assignment, or the assigned agent is outside the caller's visibility.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Path Parameters

customerId*string

ID of the customer to get insights for.

Formatuuid

Query Parameters

inactive_threshold_days?integer

Days without a disbursement before a customer is INACTIVE. Defaults to 60.

Formatint32

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/agents/me/customers/550e8400-e29b-41d4-a716-446655440001/insights?inactive_threshold_days=60"
{  "customer_user_id": "550e8400-e29b-41d4-a716-446655440001",  "account_count": 3,  "active_account_count": 2,  "overdue_installment_count": 2,  "total_outstanding_amount": {    "value": 100000,    "currency": "KES"  },  "last_installment_at": "2026-02-10T08:15:00Z",  "activity_status": "ACTIVE"}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "code": "BAD_REQUEST",  "description": "Invalid input"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

List the caller's team customers GET

List customers assigned to the caller and to the agents the caller supervises. Requires the `org:agents:read` permission. Filter with `q` for a case-insensitive match on the customer's name, email, or phone number, and with `activity_status`. Set `exclude_agent_user_id` to hide one agent's customers, for example the caller's own when looking for customers to transfer. Page with `size`, `after`, and `before`.

Get the caller's agent dashboard GET

Roll up the caller's directly assigned customers into totals and a repayment rate. Requires the `org:agents:read` permission. `inactive_threshold_days` sets when a customer without a recent disbursement counts as `INACTIVE`, and `repayment_window_days` sets the window behind `repayment_rate`. Returns 404 when the caller is not an agent in the granted organization.