Cowdidocs
API ReferenceAgents

Suspend the agent

POST
/v1/agents/{userId}/suspend

Temporarily suspend an agent so it can't be assigned new customers. Requires the org:agents:write permission. Available to the caller, the caller's supervised subtree, or a caller with org:agents.all:read. The agent must currently be ACTIVE. 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 POST "https://example.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/suspend"
{  "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"}

List the agent's change history GET

List changes to an agent's role, status, territory, supervisor, and pay, newest first. Requires the `org:agents:read` permission. Available under the same visibility rule as `GET /v1/agents/{userId}`. Page with `size`, `after`, and `before`. Returns 404 when the agent does not exist or is outside the caller's visibility.

Reactivate the agent POST

Reactivate a suspended agent so it can be assigned customers again. Requires the `org:agents:write` permission. Available to the caller, the caller's supervised subtree, or a caller with `org:agents.all:read`. The agent must currently be `SUSPENDED`. Returns 404 when the agent does not exist or is outside the caller's visibility.