Cowdidocs
API ReferenceAgents

Get an agent

GET
/v1/agents/{userId}

Get one agent by user ID. Requires the org:agents:read permission. The caller can always read their own agent record; any other agent must be in the caller's supervised subtree, unless the caller holds org:agents.all:read. Returns 404 when the agent does not exist or 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

userId*string

ID of the agent's user account.

Formatuuid

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"
{  "user_id": "550e8400-e29b-41d4-a716-446655440000",  "user_email": "jane.wanjiru@example.com",  "name": "Jane Wanjiru",  "phone_number": "+254712345678",  "role": "AGENT",  "status": "ACTIVE",  "territory": "Nairobi North",  "supervisor_user_id": "550e8400-e29b-41d4-a716-446655440002",  "supervisor_name": "Peter Kamau",  "supervisor_email": "peter.kamau@example.com",  "supervisor_phone_number": "+254722334455",  "commission_rate": 0.05,  "base_salary": {    "value": 100000,    "currency": "KES"  },  "hire_date": "2026-01-10",  "termination_date": "2026-06-30",  "customer_count": 18,  "created_at": "2026-09-01T10:15:30Z",  "updated_at": "2026-10-15T14:22:00Z",  "resource_id": "string"}
{  "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"}

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.

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.