Cowdidocs
API ReferenceAgents

Get the caller's agent profile

GET
/v1/agents/me

Get the caller's own agent profile. Requires the org:agents:read permission. Returns 403 when the caller is not an agent in the granted organization.

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/agents/me"
{  "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": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

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.

List the caller's team customers GET

List customers assigned to the caller and to the agents the caller supervises. Requires the `org:agents:read` permission. Filter with `q` for a case-insensitive match on the customer's name, email, or phone number, and with `activity_status`. Set `exclude_agent_user_id` to hide one agent's customers, for example the caller's own when looking for customers to transfer. Page with `size`, `after`, and `before`.