Cowdidocs
API ReferenceUsers

Create a user

POST
/v1/users

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.

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 user, or reuse an existing one when their email or phone matches.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/users" \  -H "Content-Type: application/json" \  -d '{    "first_name": "Jane",    "last_name": "Doe",    "organization": "greenwheels"  }'
{  "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"}
{  "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"}

List users GET

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.

Activate a user POST

Activate a suspended or inactive user in the caller's organization. This is an admin action, not a profile change. Requires the caller's `org:users:write` permission. Returns 404 when no user exists with this ID in the caller's organization.