> ## Documentation Index > Fetch the complete documentation index at: https://developers.clara.team/llms.txt > Use this file to discover all available pages before exploring further. # Users > Create, update, retrieve, and delete users in a company account. Recommended for all new integrations. ## What is the Users API? Version 3 of Clara's Users API lets you manage user accounts securely, with support for: * Role and location handling * Advance filtering through query parameters * User lifecycle operations support (onboarding, status tracking, updating, and deletion) All operations are secured via Mutual TLS and OAuth 2 authentication protocols.
## Authentication To use the API: 1. Obtain your client certificate and credentials via the Clara platform. 2. Request an access token via `POST /oauth/token` with your `client_id` and `client_secret`. 3. Use the access token in the `Authorization` header for all subsequent API requests.
## Core Use Cases ### **List Users** Retrieve a list of users with optional filters like status, role, or name. * \*\*`GET /api/v3/users` \*\*- with filters for status, role, name. * **Successful Response HTTP Status:**
`200 OK` : List of users successfully returned * **Query Parameters:** | Parameter | Type | Default | Example | Description | | ---------------- | ------- | ------- | ------------------------------------------------- | -------------------------------------------------------------- | | `page` | integer | 0 | | Zero-based page index (default: 0) | | `size` | integer | 50 | | Number of users per page (default: 50) | | `status` | string | | ACTIVE | Filter by user status (e.g., ACTIVE, LOCKED) | | `role` | string | | EMPLOYEE | Filter by role (EMPLOYEE, MANAGER, COMPANY\_OWNER, BOOKKEEPER) | | `uuid` | string | | 90a50162-f673-4be0-bfa0-67dc0adde16f | Filter by specific user UUID | | `name` | string | | John | Filter by first name | | `lastName` | string | | Cena | Filter by last name | | `fullName` | string | | John Cena | Filter by full name | | `email` | string | | [johncena@clara.team](mailto:johncena@clara.team) | Filter by email address | | `mobilePhone` | string | | 5512345678 | Filter by mobile phone number | | `taxIdentifier` | string | | DANT120619Z45 | Filter by tax identifier | | `erpId` | string | | SADSADASDASDAS351345 | Filter by ERP ID | | `createdAtStart` | string | | 2022-03-28 | Filter users created after this date (YYYY-MM-DD) | | `createdAtEnd` | string | | 2025-03-28 | Filter users created before this date (YYYY-MM-DD) | | `locationUuid` | string | | 90a50162-f673-4be0-bfa0-67dc0adde16f | Filter by location UUID | | `locationName` | string | | Barcelona | Filter by location name | | `managerUuid` | string | | 90a50162-f673-4be0-bfa0-67dc0adde16f | Filter by manager UUID | * **Example Request:** ```http theme={null} GET /api/v3/users?page=0&size=5&status=ACTIVE&role=EMPLOYEE HTTP/1.1 Host: public-api.mx.clara.com Authorization: Bearer YOUR_ACCESS_TOKEN ``` * **Example Response:** ```json theme={null} { "totalElements": 1, "content": [ { "uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e", "fullName": "John Doe", "name": "John", "lastName": "Doe", "email": "johndoe@clara.team", "mobilePhone": "5512345678", "taxIdentifier": "DANT120619Z45", "role": "EMPLOYEE", "erpId": "SADSADASDASDAS351345", "status": "ACTIVE", "createdAt": "2023-10-01T12:00:00", "location": { "uuid": "loc-123", "name": "Barcelona", "_links": { "self": { "href": "https://public-api.mx.clara.com/api/v3/locations/loc-123" } } }, "manager": { "uuid": "manager-uuid", "_links": { "self": { "href": "https://public-api.mx.clara.com/api/v3/users/manager-uuid" } } }, "_links": { "self": { "href": "https://public-api.mx.clara.com/api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e" } } } ] } ```
### **Create User** * `POST /api/v3/users` - add a new user to your organization. * **Successful Response HTTP Status:**
`201 Created`: User successfully created * **Request Body Parameters:** | Parameter | Type | Required | Description | | --------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `email` | string | ✅ | User's email address which also serves as their username. This is the primary identifier for the user in the system and is used for login purposes and notifications. It must be unique within the company and is a required field for user creation. | | `name` | string | ✅ | User's first name. Used for display purposes throughout the system. This field is used in reports, notifications, and user interfaces. It is a required field for user creation and part of the user's identity in the system. | | `lastName` | string | ✅ | User's last name. Used for display purposes throughout the system. This field is used in reports, notifications, and user interfaces. It is a required field for user creation and part of the user's identity in the system. | | `groups` | string | ❌ | List of group UUIDs that the user will be assigned to. Groups determine the user's access permissions and organizational structure. This field is required for all users except those with the COMPANY\_OWNER role. At least one group must be provided for non-company owner users. | | `lada` | string | ❌ | User's phone country code (lada). Used for contact information. If not provided, defaults to +52 for Mexico, +55 for Brazil, and +57 for Colombia based on company location. This field is used together with mobilePhone for user notifications and contact purposes. | | `mobilePhone` | string | ✅ | User's mobile phone number. Used for contact information and notifications. This is a required field for user creation and is used for sending important notifications to the user. The format should follow the country's phone number standard without the country code. | | `role` | string | ✅ | User's role in the system. Determines the user's permissions and access level. This is a required field for user creation and affects the validation of other fields. COMPANY\_OWNER users have special privileges and different validation rules. Common values include EMPLOYEE, MANAGER, COMPANY\_OWNER, and BOOKKEEPER. | | `managerUuid` | string | ❌ | UUID of the user's direct manager or supervisor. Used to establish the organizational hierarchy and reporting structure. This field is optional but recommended for proper organizational structure visualization. It affects approval workflows and reporting relationships in the system. | | `locationUuid` | string | ❌ | UUID of the location where the user is assigned. Associates the user with a specific physical or organizational location in the company. This field is required for all users except those with the COMPANY\_OWNER role. It affects location-based reports, filters, and organizational structure. | | `erpId` | string | ❌ | User's Enterprise Resource Planning (ERP) identifier. Used to link the user with external ERP systems. This field facilitates integration with other business systems and is optional. If provided, it should match the identifier used in the connected ERP system. | | `taxIdentifier` | string | ❌ | User's tax identification number. Used for financial and tax-related purposes. This field is required for financial transactions and tax reporting. Updating this field will change the user's tax information in the system. The length must be valid for the country: MX (11 or 13), CO (7, 8, 9, or 10), BR (11). | | `foreign` | boolean | ❌ | Flag indicating if the user is from a foreign country. Affects how the system handles certain validations and processes for the user. If not provided, defaults to false. This field may impact tax calculations and regulatory compliance. | * **Example Request:** ```json theme={null} { "email": "janedoe@clara.team", "name": "Jane", "lastName": "Doe", "mobilePhone": 5512345678, "lada": "+52", "role": "EMPLOYEE", "groups": ["a0c82a20-ac09-4cfd-b429-d0623585911e"], "locationUuid": "409e3ccd-4e87-480a-98d5-126c54ff9457", "managerUuid": "0d761141-6cee-495c-a27e-99875bdce721", "erpId": "ERP-001", "taxIdentifier": "RFC123456789", "foreign": false } ``` * **Example Response:** ```json theme={null} { "uuid": "b1d23c20-bc00-4cfd-b429-d0623585912f" } ```
### **Retrieve a User by UUID** * `GET /api/v3/users/{uuid}` - fetch details of a single user using their UUID * **Successful Response HTTP Status:**
`200 OK`: User successfully retrieved * **Path Parameter:** | Parameter | Type | Description | | --------- | ------ | ---------------- | | `uuid` | string | UUID of the user | * **Example Request:** ```http theme={null} GET /api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e HTTP/1.1 Authorization: Bearer YOUR_ACCESS_TOKEN ``` * **Example Response:** ```json theme={null} { "uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e", "fullName": "John Doe", "name": "John", "lastName": "Doe", "email": "johndoe@clara.team", "mobilePhone": "5512345678", "taxIdentifier": "RFC987654321", "role": "EMPLOYEE", "erpId": "ERP-001", "status": "ACTIVE", "createdAt": "2023-10-01T12:00:00", "groups": [ { "uuid": "group-123", "name": "Engineering", "_links": { "self": { "href": "https://public-api.mx.clara.com/api/v3/groups/group-123" } } } ], "location": { "uuid": "loc-456", "name": "Mexico City", "_links": { "self": { "href": "https://public-api.mx.clara.com/api/v3/locations/loc-456" } } }, "cards": [ { "uuid": "card-001", "status": "ACTIVE", "lockCode": "UNLOCKED", "alias": "Main Card", "threshold": 1000, "periodicity": "MONTHLY", "maskedPan": "514509******5946", "type": "MASTER_VIRTUAL", "_links": { "self": { "href": "https://public-api.mx.clara.com/api/v3/cards/card-001" } } } ], "manager": { "uuid": "manager-uuid-789", "name": "Jane", "lastName": "Smith", "email": "janesmith@clara.team", "erpId": "ERP-002", "_links": { "self": { "href": "https://public-api.mx.clara.com/api/v3/users/manager-uuid-789" } } }, "_links": { "self": { "href": "https://public-api.mx.clara.com/api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e" } } } ```
### **Update User** * `PATCH /api/v3/users/{uuid}` - modify the details of an existing user. * **Successful Response HTTP Status:**
`200 OK`: User successfully updated * **Path Parameter:** | Parameter | Type | Description | | --------- | ------ | ---------------- | | `uuid` | string | UUID of the user | * **Request Body Parameters:** | Parameter | Type | Description | | ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `email` | string | User's email/username. Serves as the primary identifier for the user in the system. This field is used for login purposes and notifications. Updating this field will change the user's login credentials. | | `name` | string | User's first name. Used for display purposes throughout the system. This field is used in reports, notifications, and user interfaces. Updating this field will change how the user's name appears in the system. | | `lastName` | string | User's last name. Used for display purposes throughout the system. This field is used in reports, notifications, and user interfaces. Updating this field will change how the user's name appears in the system. | | `lada` | string | User's phone country code (lada). Used for contact information. Must be provided together with mobilePhone or not at all. If one is provided without the other, a validation error will occur. Updating this field will change the user's contact information. | | `mobilePhone` | string | User's mobile phone number. Used for contact information and notifications. Must be provided together with lada or not at all. If one is provided without the other, a validation error will occur. Updating this field will change the user's contact information. | | `role` | string | User's role. Determines the user's permissions and access level in the system. Changing a user's role may affect their access to certain features and data. This field triggers an update to the user's role in the system. | | `locationUuid` | string | User's location UUID. Associates the user with a specific location in the company. This field is used to determine the user's physical or organizational location. Updating this field will change where the user appears in location-based reports and filters. | | `erpId` | string | User's Enterprise Resource Planning (ERP) identifier. Used to link the user with external ERP systems. This field facilitates integration with other business systems. Updating this field will change how the user is identified in integrated ERP systems. | | `taxIdentifier` | string | User's tax identification number. Used for financial and tax-related purposes. This field is required for financial transactions and tax reporting. Updating this field will change the user's tax information in the system. The length must be valid for the country: MX (11 or 13), CO (7, 8, 9, or 10), BR (11). | | `managerUuid` | string | User's manager UUID. Identifies the user's direct supervisor or manager in the organizational hierarchy. This field is used for reporting structures and approval workflows. Updating this field will change the user's position in the organizational chart. | | `groupsToAdd` | string | User's groups UUIDs to add. Specifies which groups the user should be added to. If provided, must contain at least one group UUID. Cannot contain groups that the user is already a member of unless cleanGroups is true. Cannot contain the same group UUIDs as groupsToRemove. At least one group must be provided when cleanGroups is true. After applying all changes, the user must remain in at least one group. | | `groupsToRemove` | string | User's groups UUIDs to remove. Specifies which groups the user should be removed from. If provided, must contain at least one group UUID. Must only contain groups that the user is currently a member of. Cannot contain the same group UUIDs as groupsToAdd. Should not be provided when cleanGroups is true. After applying all changes, the user must remain in at least one group. | | `cleanGroups` | boolean | Flag to indicate if all existing groups should be removed before adding new ones. When true, all of the user's current groups will be removed and replaced with the groups specified in groupsToAdd. When true, groupsToRemove should not be provided as it would be redundant. When true, groupsToAdd must contain at least one group to ensure the user remains in at least one group. Defaults to false if not provided. | * **Example Request:** #### Group Management Fields The following fields enhance how a user's group memberships are updated: * **`groupsToAdd`**: Adds the user to one or more groups. Must not duplicate existing memberships. * **`groupsToRemove`**: Removes the user from specified groups. Must already be a member of those groups. * **`cleanGroups`**: If true, removes all existing groups before adding new ones from `groupsToAdd`. > ⚠️ When `cleanGroups` is true, `groupsToAdd` must include at least one group. The user must always remain in at least one group. ```json theme={null} { "name": "Johnathan", "mobilePhone": 5512345679, "lada": "+52", "groupsToAdd": [ "a0c82a20-ac09-4cfd-b429-d0623585911e" ], "groupsToRemove": [ "10c82a20-ac09-4cfd-b429-d0623585912e" ], "cleanGroups": false } ``` * **Example Response:** ```json theme={null} "User updated" ```
### **Delete User** * `DELETE /api/v3/users/{uuid}` - delete a user using their UUID. * **Successful Response HTTP Status:**
`204 No Content`: User successfully deleted * **Path Parameter:** | Parameter | Type | Description | | --------- | ------ | ---------------- | | `uuid` | string | UUID of the user | * **Example Request:** ```http theme={null} DELETE /api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e HTTP/1.1 Authorization: Bearer YOUR_ACCESS_TOKEN ``` * **Example Response:** ```http theme={null} 204 No Content ```
## User Lifecycle Status * `ONBOARDING_CANDIDATE`: User has been created but not fully onboarded. * `WAITING`: User is awaiting some verification or action. * `DELETED`: User account has been marked for deletion. * `ACTIVE`: User is active and can use the system. * `LOCKED`: User account is locked. * `INACTIVE`: User is not currently active but may be reactivated. * `PENDING`: User creation is pending. * `MASTER_LOCKED`: User is locked at the highest permission level. * `CLARA_BLOCKED`: User is blocked by the system administrator.
## Lifecycle Flow 1. **Creation**: A user is created via the `POST /api/v3/users` endpoint. Initially, they may be in a status such as `ONBOARDING_CANDIDATE` or `PENDING`. 2. **Activation**: After onboarding steps are completed, the user transitions to `ACTIVE`. 3. **Usage**: The user actively participates in the platform's operations. 4. **Locking/Blocking**: If needed, the user may be `LOCKED`, `MASTER_LOCKED`, or `CLARA_BLOCKED` due to policy violations or security issues. 5. **Deactivation**: Users can be set to `INACTIVE` if no longer participating but still retained in the system. 6. **Deletion**: Finally, the user can be marked as `DELETED` via the `DELETE /api/v3/users/{uuid}` endpoint. *** ## Endpoint Reference ### `GET /api/v3/users` List all users (v3) **Parameters:** | Parameter | In | Type | Required | Description | | ---------------- | ----- | ------------- | -------- | ----------------------------- | | `status` | query | string | | Filter by user status | | `role` | query | string | | Filter by user role | | `uuid` | query | string (uuid) | | Filter by user UUID | | `name` | query | string | | Filter by first name | | `lastName` | query | string | | Filter by last name | | `fullName` | query | string | | Filter by full name | | `email` | query | string | | Filter by email | | `mobilePhone` | query | string | | Filter by mobile phone | | `taxIdentifier` | query | string | | Filter by tax ID | | `erpId` | query | string | | Filter by ERP ID | | `createdAtStart` | query | string (date) | | Filter by creation date start | | `createdAtEnd` | query | string (date) | | Filter by creation date end | | `locationUuid` | query | string (uuid) | | Filter by location UUID | | `locationName` | query | string | | Filter by location name | | `managerUuid` | query | string (uuid) | | Filter by manager UUID | **Response Schema (`UserPageV3`):** | Field | Type | Example | | --------------- | ------------------- | ------- | | `content` | array of UserItemV3 | | | `totalElements` | integer | | | `totalPages` | integer | | | `size` | integer | | | `number` | integer | | ### `POST /api/v3/users` Create user (v3) **Request Body (`CreateUserRequestV3`):** | Field | Type | Example | | --------------- | ----------------- | -------------------------------------- | | `email` | string (email) | `johndoe@clara.team` | | `name` | string | `John` | | `lastName` | string | `Doe` | | `groups` | array of string | | | `lada` | string | `+52` | | `mobilePhone` | string | `5512345678` | | `role` | object (UserRole) | | | `managerUuid` | string (uuid) | `0d761141-6cee-495c-a27e-99875bdce721` | | `locationUuid` | string (uuid) | `409e3ccd-4e87-480a-98d5-126c54ff9457` | | `erpId` | string | `SADSADASDASDAS351345` | | `taxIdentifier` | string | `DANT120619Z45` | ### `GET /api/v3/users/{uuid}` Get user by UUID (v3) **Parameters:** | Parameter | In | Type | Required | Description | | --------- | ---- | ------------- | -------- | ----------- | | `uuid` | path | string (uuid) | ✅ | | **Response Schema (`UserV3`):** | Field | Type | Example | | --------------- | ------------------- | -------------------------------------- | | `uuid` | string (uuid) | `a0c82a20-ac09-4cfd-b429-d0623585911e` | | `fullName` | string | `John Doe` | | `lastName` | string | `Doe` | | `name` | string | `John` | | `email` | string (email) | `johndoe@clara.team` | | `mobilePhone` | string | `5512345678` | | `taxIdentifier` | string | `DANT120619Z45` | | `role` | object (UserRole) | | | `erpId` | string | `SADSADASDASDAS351345` | | `status` | object (UserStatus) | | | `createdAt` | string (date-time) | `2023-10-01T12:00:00` | | `groups` | array of GroupV2 | | | `cards` | array of UserCardV2 | | | `manager` | object (BasicUser) | | | `location` | object (LocationV2) | | ### `PATCH /api/v3/users/{uuid}` Update user (v3) **Parameters:** | Parameter | In | Type | Required | Description | | --------- | ---- | ------------- | -------- | ----------- | | `uuid` | path | string (uuid) | ✅ | | **Request Body (`UpdateUserRequestV3`):** | Field | Type | Example | | ---------------- | ----------------- | -------------------------------------- | | `email` | string (email) | `johndoe@clara.team` | | `name` | string | `John` | | `lastName` | string | `Doe` | | `lada` | string | `+52` | | `mobilePhone` | string | `5512345678` | | `role` | object (UserRole) | | | `locationUuid` | string (uuid) | `409e3ccd-4e87-480a-98d5-126c54ff9457` | | `erpId` | string | `SADSADASDASDAS351345` | | `taxIdentifier` | string | `DANT120619Z45` | | `managerUuid` | string (uuid) | `0d761141-6cee-495c-a27e-99875bdce721` | | `groupsToAdd` | array of string | | | `groupsToRemove` | array of string | | | `cleanGroups` | boolean | | ### `DELETE /api/v3/users/{uuid}` Delete user (v3) **Parameters:** | Parameter | In | Type | Required | Description | | --------- | ---- | ------------- | -------- | ----------- | | `uuid` | path | string (uuid) | ✅ | | ## What is the Users API? The **Users API (v2)** allows you to programmatically manage users within your Clara organization. You can create users, list all users, and retrieve detailed information about any user by UUID. This API is commonly used to: * Onboard new employees into the platform * Synchronize users from an external HR system * Manage user metadata such as job title, department, or phone number * Prepare users to receive cards, assign roles, or link them to approval workflows *
## Available Endpoints | Operation | Endpoint | Method | | ------------------ | ------------------ | ------ | | Retrieve all users | `/v2/users` | GET | | Create a new user | `/v2/users` | POST | | Get user by UUID | `/v2/users/{uuid}` | GET |
## Retrieve All Users Fetch a complete list of users registered in your organization. ### Endpoint `GET /v2/users` ### cURL Request ```curl cURL theme={null} curl -X GET \ "https://public-api.mx.clara.com/api/v2/users" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Sample JSON Response ```json JSON theme={null} [ { "uuid": "3b3123e7-d7b4-4c92-a3b6-57e9f7aafadb", "email": "john.doe@company.com", "fullName": "John Doe", "status": "ACTIVE", "role": "EMPLOYEE" } ] ```
## Retrieve All Users Register a new user with name, email, and optional details like job title, phone number, or department. The new user can later be assigned roles and permissions. ### Endpoint `POST /v2/users` ### cURL Request ```curl cURL theme={null} curl -X POST \ "https://public-api.mx.clara.com/api/v2/users" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "fullName": "Jane Smith", "email": "jane.smith@company.com", "phoneNumber": "+5215512345678", "jobTitle": "Operations Manager", "department": "Operations" }' ``` ### Sample JSON Response ```json JSON theme={null} { "uuid": "9d8122e5-4173-497a-9015-f4f2d9482c1a", "email": "jane.smith@company.com", "fullName": "Jane Smith", "status": "PENDING_INVITATION" } ```
## Retrieve All Users Fetch detailed information about a specific user using their UUID. ### Endpoint `GET /v2/users/{uuid}` ### cURL Request ```curl cURL theme={null} curl -X GET \ "https://public-api.mx.clara.com/api/v2/users/9d8122e5-4173-497a-9015-f4f2d9482c1a" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Sample JSON Response ```json JSON theme={null} { "uuid": "9d8122e5-4173-497a-9015-f4f2d9482c1a", "email": "jane.smith@company.com", "fullName": "Jane Smith", "status": "ACTIVE", "jobTitle": "Operations Manager", "department": "Operations", "createdAt": "2024-06-15T12:45:00Z" } ```
💡\*\* Tip:\*\* After creating a user, you can assign roles and issue cards programmatically using the Roles and Cards APIs. ⚠️ **Note:** Users with PENDING\_INVITATION status must complete onboarding via the invitation email before accessing Clara's platform. *** ## Endpoint Reference ### `GET /api/v2/users` List all users (v2) ### `POST /api/v2/users` Create user (v2) **Request Body (`CreateUserRequestV2`):** | Field | Type | Example | | ------------------ | ------ | ------- | | `createUserParams` | object | | ### `GET /api/v2/users/{uuid}` Get user by UUID (v2) **Parameters:** | Parameter | In | Type | Required | Description | | --------- | ---- | ------------- | -------- | ----------- | | `uuid` | path | string (uuid) | ✅ | | **Response Schema (`UserV2`):** | Field | Type | Example | | --------------- | ------------------- | ------------------------------------------------- | | `uuid` | string (uuid) | `1f2e3a4c-5d67-89a0-ba1c-2b3d4b567801` | | `userFullName` | string | `Manuela Sanchez` | | `username` | string | `muela.g+3@clara.team` | | `role` | string (enum) | `EMPLOYEE`/`MANAGER`/`COMPANY_OWNER`/`BOOKKEEPER` | | `taxIdentifier` | string | `BRZ0000002102` | | `erpId` | string | `103892` | | `status` | object (CardStatus) | | | `location` | object (LocationV2) | | | `cards` | array of UserCardV2 | | | `manager` | object (BasicUser) | | | `groups` | array of GroupV2 | | v1 is legacy and read-only. Migrate to v3 for full user management. ## What is the Users API? The **Users API v1** provides read-only access to user profiles registered in your Clara organization. It allows external systems to retrieve user information such as names, emails, roles, and statuses. This version is ideal for integrations that require: * Listing users for mapping or sync purposes * Displaying user names or emails in custom dashboards * Linking other entities (transactions, cards, policies) with user metadata 🆚 Note: This is a **read-only** API. For user creation and updates, use [Users API v2](#).
## Available Endpoints | Operation | Endpoint | Method | | ---------------- | ------------------ | ------ | | List all users | `/v1/users` | GET | | Get user by UUID | `/v1/users/{uuid}` | GET |
## List all users Use this endpoint to **retrieve a list of all users** in your organization. The response includes basic information for each user such as name, email, and status. ### Endpoint `GET /v1/users` ### cURL Request ```curl cURL theme={null} curl -X GET \ "https://public-api.mx.clara.com/api/v1/users" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Sample JSON Response ```json JSON theme={null} [ { "uuid": "user-123", "fullName": "Ana Gómez", "email": "ana.gomez@empresa.com", "status": "ACTIVE", "role": "EMPLOYEE" }, { "uuid": "user-456", "fullName": "Luis Torres", "email": "luis.torres@empresa.com", "status": "DISABLED", "role": "ADMIN" } ] ```
## Find user by UUID Use this endpoint to retrieve detailed information about a specific user using their unique identifier (uuid). ### Endpoint `GET /v1/users/{uuid}` ### cURL Request ```curl cURL theme={null} curl -X GET \ "https://public-api.mx.clara.com/api/v1/users/user-123" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Sample JSON Response ```json JSON theme={null} { "uuid": "user-123", "fullName": "Ana Gómez", "email": "ana.gomez@empresa.com", "status": "ACTIVE", "role": "EMPLOYEE" } ```
**💡 Tip:** Combine this API with other entity UUIDs (e.g., transactions or cards) to enrich reporting or audit logs with human-readable user information. **⚠️ Note:** This API is read-only and does not support creation, update, or deactivation of users. *** ## Endpoint Reference ### `GET /api/v1/users` Find all users **Parameters:** | Parameter | In | Type | Required | Description | | ------------ | ----- | ------------------------------------------------------------------ | -------- | ----------------------------------- | | `page` | query | integer | | Zero-based page index (0..N) | | `size` | query | integer | | The size of the page to be returned | | `statusName` | query | enum: `ONBOARDING_CANDIDATE`/`WAITING`/`DELETED`/`ACTIVE`/`LOCKED` | | Status of the user | | `role` | query | enum: `EMPLOYEE`/`MANAGER`/`COMPANY_OWNER`/`BOOKKEEPER` | | Role of the user. | ### `GET /api/v1/users/{uuid}` Find user by UUID **Parameters:** | Parameter | In | Type | Required | Description | | --------- | ---- | ------ | -------- | ----------- | | `uuid` | path | string | ✅ | User UUID |