Cowdidocs
API ReferenceAgents

Unassign customers from the agent

POST
/v1/agents/{userId}/customers/unassign

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.

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 to unassign customers from.

Formatuuid

Request Body

application/json

Request to assign customers to an agent.

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/customers/unassign" \  -H "Content-Type: application/json" \  -d '{    "customer_user_ids": [      "550e8400-e29b-41d4-a716-446655440001"    ]  }'
[  {    "id": "6f9619ff-8b86-4d11-9a6e-8b1a3d3a2f10",    "agent_user_id": "550e8400-e29b-41d4-a716-446655440000",    "agent_user_name": "Jane Wanjiru",    "agent_phone_number": "+254712345678",    "agent_email": "jane.wanjiru@example.com",    "customer_user_id": "550e8400-e29b-41d4-a716-446655440001",    "customer_name": "John Otieno",    "customer_email": "john.otieno@example.com",    "customer_phone_number": "+254798765432",    "assigned_at": "2026-01-15T09:30:00Z",    "unassigned_at": "2026-02-20T14:00:00Z",    "assigned_by": "550e8400-e29b-41d4-a716-446655440002",    "unassigned_by": "550e8400-e29b-41d4-a716-446655440002",    "assignment_reason": "Territory reassignment",    "unassignment_reason": "Customer transferred to another agent",    "is_active": true,    "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 customer assignment history GET

List every customer assignment and unassignment for one agent, newest first. Requires the `org:agents:read` permission. Available 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.

Deactivate the agent POST

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.