Cowdidocs
API ReferenceAgents

Assign customers to the agent

POST
/v1/agents/{userId}/customers

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.

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 assign customers to.

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" \  -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 customers GET

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.

List the customer's account summaries GET

List a customer's accounts with balance, type, status, and currency. Requires the `org:agents:read` permission. Available to the agent the customer is assigned to and to that agent's supervisor chain. Returns 404 when the agent or the customer does not exist, or the customer is not currently assigned to the agent.