Cowdidocs
API ReferenceAgents

Create an agent

POST
/v1/agents

Register a user as an agent in the caller's organization. Requires the org:agents:write permission. The user must exist in the organization and must not already be an agent. The supervisor named in supervisor_user_id, when set, must be an active agent able to supervise the requested role. Returns 404 if the user or the supervisor does not exist, and 409 if the user is already an 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

Request Body

application/json

Request to create a new agent.

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" \  -H "Content-Type: application/json" \  -d '{    "user_id": "550e8400-e29b-41d4-a716-446655440000",    "role": "AGENT",    "commission_rate": 0.05,    "base_salary": {      "value": 100000,      "currency": "KES"    }  }'
{  "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"}

List agents GET

List agents in the caller's organization. Requires the `org:agents:read` permission. Without the `org:agents.all:read` permission, the caller sees only themself and their supervised subtree. Set `scope` to `OWN` to force that subtree view even when the caller holds `org:agents.all:read`. Filter by `role`, `status`, `territory`, or `q`, and page with `size`, `after`, and `before`.

Transfer customers between agents POST

Move customers from one agent to another in a single call. Requires the `org:agents:write` permission. Both agents must be visible to the caller, and the destination agent must be able to take new customers. Every customer in `customer_user_ids` must have an active assignment to the source agent. `from_user_id` and `to_user_id` must differ. Returns 404 when either agent does not exist.