Cowdidocs
API ReferenceAgents

Update an agent

PUT
/v1/agents/{userId}

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.

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

Request Body

application/json

Request to replace an existing agent's role, status, territory, supervisor, and pay.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/agents/550e8400-e29b-41d4-a716-446655440000" \  -H "Content-Type: application/json" \  -d '{    "role": "AGENT",    "status": "ACTIVE",    "territory": "Nairobi Central",    "commission_rate": 0.07,    "base_salary": {      "value": 100000,      "currency": "KES"    }  }'
{  "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 an agent GET

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.

Get the agent's commission GET

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.