Cowdidocs
API ReferenceAgents

Get the agent's commission

GET
/v1/agents/{userId}/commissions

Calculate an agent's commission for a time range from stored commission events. Available to the agent, an agent who directly supervises them, or a caller with the org:agents.all:read permission. from is inclusive and to is exclusive. model_id selects the calculation model; only default exists today. Returns 404 when the agent does not exist.

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

userId*string

ID of the agent's user account.

Formatuuid

Query Parameters

from*string

Start of the time range (inclusive), an ISO 8601 timestamp with timezone offset.

Formatdate-time
to*string

End of the time range (exclusive), an ISO 8601 timestamp with timezone offset.

Formatdate-time
model_id?string

Commission calculation model to use. Only default exists today. Defaults to default.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/commissions?from=2026-01-01T00%3A00%3A00%2B03%3A00&to=2026-02-01T00%3A00%3A00%2B03%3A00&model_id=default"
{  "agent_user_id": "550e8400-e29b-41d4-a716-446655440000",  "from": "2026-01-01T00:00:00Z",  "to": "2026-02-01T00:00:00Z",  "total_commission": 245000,  "transaction_commissions": 230000,  "penalties": -15000,  "penalty_reversals": 15000,  "currency": "KES",  "event_count": 12,  "model_id": "default",  "line_items": [    {      "event_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",      "event_type": "LOAN_PAID",      "reference_id": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",      "amount": 50000,      "description": "Loan payment commission",      "event_occurred_at": "2026-01-20T10:00:00Z",      "is_supervisor_commission": false    }  ]}
{  "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"}

Update an agent PUT

Replace an agent's role, status, territory, supervisor, commission rate, and base salary. Requires the `org:agents:write` permission, without the supervised-subtree limit most agent operations have. Setting `status` to `INACTIVE` fails with 400. Deactivate the agent with `POST /v1/agents/{userId}/deactivate` instead. Returns 404 when the agent or the new `supervisor_user_id` does not exist.

List the agent's customers GET

List the customers currently assigned to one agent. Requires the `org:agents:read` permission. Available to the agent and to a caller who can see the agent, under the same visibility rule as `GET /v1/agents/{userId}`. Returns 404 when the agent does not exist or is outside the caller's visibility.