Cowdidocs
API ReferenceAgents

Deactivate the agent

POST
/v1/agents/{userId}/deactivate

Permanently deactivate an agent and remove their supervisor relationships. Requires the org:agents:write permission, without the supervised-subtree limit most agent operations have. The agent must be ACTIVE. The agent must have no active customer assignments. Returns 404 when the agent does not exist, and 409 when it still has active customer assignments.

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

application/json

curl -X POST "https://example.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/deactivate"
{  "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": "BAD_REQUEST",  "description": "Invalid input"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Unassign customers from the agent POST

Remove one or more customers from an agent's active assignments. Requires the `org:agents:write` permission. A customer ID that is not currently assigned to this agent is ignored. Returns 404 when the agent does not exist or is outside the caller's visibility.

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.