Cowdidocs
API ReferenceAgents

List agents

GET
/v1/agents

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.

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

Query Parameters

size?integer

Maximum number of agents to return. Defaults to 20.

Range0 < value
Default20
after?string

Opaque cursor for the page after this one, taken from a previous response's links.next. Omit for the first page.

before?string

Opaque cursor for the page before this one, taken from a previous response's links.prev.

role?string

Filter by the agent's role.

Value in

  • "AGENT"
  • "MANAGER"
  • "LEADER"
status?string

Filter by the agent's status.

Value in

  • "ACTIVE"
  • "INACTIVE"
  • "SUSPENDED"
territory?string

Case-insensitive partial match on the agent's territory.

q?string

Case-insensitive partial match on the agent's name, email, or phone number.

scope?"OWN"

Set to OWN to restrict the list to the caller and their supervised subtree, even for a caller who would otherwise see the whole organization.

Value in

  • "OWN"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/agents?size=20&after=eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9&before=eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMSJ9&role=AGENT&status=ACTIVE&territory=Nairobi&q=jane&scope=OWN"
{  "data": [    {      "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"    }  ],  "links": {    "next": "/v1/payees?after=eyJpZCI6MX0",    "prev": "/v1/payees?before=eyJpZCI6MX0"  }}
{  "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"}

Reject an invitation POST

Reject the caller's own pending merchant invitation, matched by their email. Requires an authenticated user token; only the invitee may reject. Returns 404 when no pending invitation exists for the caller's email.

Create an agent POST

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.