Cowdidocs
API ReferenceAgents

List the agent's customers

GET
/v1/agents/{userId}/customers

List the customers currently assigned to one agent. Requires the org:agents:read permission. Available to the agent and to a caller who can see the agent, 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.

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/customers"
[  {    "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"}

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.

Assign customers to the agent POST

Assign one or more customers to an agent. Requires the `org:agents:write` permission. The agent must be visible to the caller and able to take new customers. Each customer must exist in the organization. Returns 404 when the agent or a customer does not exist. Returns 403 when the agent can't take new customers or a customer is already assigned to a different agent.