Cowdidocs
API ReferenceUsers

List users

GET
/v1/users

List users in the caller's organization with pagination. Filter by status, search text, phone number, tag, or external_user_id. Requires the caller's org:users:read permission. Results use keyset pagination; follow the next or prev response link. Returns 200 with an empty data array when no user matches the filters.

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 users to return. Defaults to 20.

Range0 < value
after?string

Opaque cursor. Returns the page of users after this position.

before?string

Opaque cursor. Returns the page of users before this position.

status?string

Optional. Filter by user status: one of ACTIVE, INACTIVE, or SUSPENDED.

q?string

Optional. Unified search across name, email, and phone number (partial match, case-insensitive).

phone_number?string

Optional. Filter by exact phone number, in E.164 format.

tag?|

Optional. Filter by exact user tag (case-insensitive).

external_user_id?string

Optional. Filter by the exact external user ID in the caller's organization. The match is case-sensitive. Use 1 to 255 characters.

Length1 <= length <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/users?size=20&after=eyJ1c2VySWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAifQ&before=eyJ1c2VySWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAifQ&status=ACTIVE&q=jane&phone_number=%2B254712345678&tag=%40john-doe-1234&external_user_id=GW-12345"
{  "data": [    {      "id": "b50e8400-e29b-41d4-a716-446655440000",      "auth_id": "sadoj21su9b23b19gvgb",      "first_name": "John",      "last_name": "Doe",      "status": "ACTIVE",      "email": "john.doe@example.com",      "email_verified": true,      "phone_number": "+254712345678",      "tag": "@johnd1234",      "locale": "en-KE",      "timezone": "Africa/Nairobi",      "last_login_at": "2026-02-03T10:15:30Z",      "organization": "cowdi",      "external_user_id": "GW-12345",      "is_test": false,      "source": "ADMIN_API",      "suspension": {        "at": "2026-03-10T08:00:00Z",        "reason": "FRAUD",        "internal_note": "string",        "external_message": "string"      },      "avatar_options": "seed=k3f9x2&skinColor=edb98a",      "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 organization invitation, matched by their verified email. Requires an authenticated user token; only the invitee may reject. Returns 404 when no pending invitation exists for the caller's email.

Create a user POST

Create a user in an organization, or reuse an existing user when their email or phone matches one already on the platform. Requires the caller's `org:users:write` permission on the target `organization`. Returns 409 with the existing user's ID in `identifier` when the email or phone matches a different existing user; returns 409 without an `identifier` when the request has conflicting identifiers.