List the agent's change history
List changes to an agent's role, status, territory, supervisor, and pay, newest first. Requires the org:agents:read permission. Available under the same visibility rule as GET /v1/agents/{userId}. Page with size, after, and before. Returns 404 when the agent does not exist or is outside the caller's visibility.
Authorization
oauth2 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
ID of the agent's user account.
uuidQuery Parameters
Maximum number of agents to return. Defaults to 20.
0 < value20Opaque cursor for the page after this one, taken from a previous response's links.next. Omit for the first page.
Opaque cursor for the page before this one, taken from a previous response's links.prev.
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/history?size=20&after=eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9&before=eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMSJ9"{ "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": "BAD_REQUEST", "description": "Invalid input"}{ "code": "RATE_LIMIT_EXCEEDED", "description": "Too Many Requests"}{ "code": "INTERNAL_ERROR", "description": "Internal Server Error"}Deactivate the agent POST
Permanently deactivate an agent and remove their supervisor relationships. Requires the `org:agents:write` permission, without the supervised-subtree limit most agent operations have. The agent must be `ACTIVE`. The agent must have no active customer assignments. Returns 404 when the agent does not exist, and 409 when it still has active customer assignments.
Suspend the agent POST
Temporarily suspend an agent so it can't be assigned new customers. Requires the `org:agents:write` permission. Available to the caller, the caller's supervised subtree, or a caller with `org:agents.all:read`. The agent must currently be `ACTIVE`. Returns 404 when the agent does not exist or is outside the caller's visibility.