👥 Users API: How to Use It

🔎 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
Advanced filtering through query parameters
User lifecycle operations support (onboarding, status tracking, updating, and deletion)

All operations are secured via Mutual TLS and OAuth2 authentication protocols.

🔐 Authentication

To use the API:

Obtain client certificate and credentials via the Clara platform.
Request an access token via POST /oauth/token with your client_id and client_secret.
Use the access token in the Authorization header for all subsequent API requests.

🔧 Core Use Cases

1️⃣ List Users

GET /api/v3/users — with filters for role, name, status.
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		[email protected]	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:

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:

{
  "totalElements": 1,
  "content": [
    {
      "uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
      "fullName": "John Doe",
      "name": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "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"
        }
      }
    }
  ]
}

2️⃣Create a 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 optional but recommended for financial transactions and tax reporting.
`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:

{
  "email": "[email protected]",
  "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:

{
  "uuid": "b1d23c20-bc00-4cfd-b429-d0623585912f"
}

3️⃣ Retrieve 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 Parameters:

Parameter	Type	Description
`uuid`	string	UUID of the user

Example Request:

GET /api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN

Example Response:

{
  "uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
  "fullName": "John Doe",
  "name": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "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": "[email protected]",
    "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"
    }
  }
}

4️⃣Update User Info

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.
`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.

{
  "name": "Johnathan",
  "mobilePhone": 5512345679,
  "lada": "+52",
  "groupsToAdd": [
    "a0c82a20-ac09-4cfd-b429-d0623585911e"
  ],
  "groupsToRemove": [
    "10c82a20-ac09-4cfd-b429-d0623585912e"
  ],
  "cleanGroups": false
}

Example Response:

"User updated"

5️⃣ Delete a 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:

DELETE /api/v3/users/a0c82a20-ac09-4cfd-b429-d0623585911e HTTP/1.1
Authorization: Bearer YOUR_ACCESS_TOKEN

Example Response:

204 No Content

🔄 User Lifecycle Statuses

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

Create → Activate → Use → Lock/Block → Deactivate/Delete

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.
Activation: After onboarding steps are completed, the user transitions to ACTIVE.
Usage: The user actively participates in the platform's operations.
Locking/Blocking: If needed, the user may be LOCKED, MASTER_LOCKED, or CLARA_BLOCKED due to policy violations or security issues.
Deactivation: Users can be set to INACTIVE if no longer participating but still retained in the system.
Deletion: Finally, the user can be marked as DELETED via the DELETE /api/v3/users/{uuid} endpoint.

🔎 What Is the Users API?

🔐 Authentication

🔧 Core Use Cases

1️⃣ List Users

2️⃣Create a User

3️⃣ Retrieve by UUID

4️⃣Update User Info

Group Management Fields

⚠️When cleanGroups is true, groupsToAdd must include at least one group. The user must always remain in at least one group.

5️⃣ Delete a User

🔄 User Lifecycle Statuses

📋 Lifecycle Flow

⚠️
When `cleanGroups` is true, `groupsToAdd` must include at least one group. The user must always remain in at least one group.