👥 Users API: How to Use It

The Users API (v2) in Clara allows you to list, create, and retrieve user profiles in your organization. These users can later be assigned cards, policies, roles, and other permissions across the platform.

🔍 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

1️⃣ Retrieve All Users

Fetch a complete list of users registered in your organization.

🔗 Endpoint

GET /v2/users

📤 cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v2/users" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

📥 Sample JSON Response

JSON

[
  {
    "uuid": "3b3123e7-d7b4-4c92-a3b6-57e9f7aafadb",
    "email": "[email protected]",
    "fullName": "John Doe",
    "status": "ACTIVE",
    "role": "EMPLOYEE"
  }
]

2️⃣ 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 -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": "[email protected]",
  "phoneNumber": "[phone]",
  "jobTitle": "Operations Manager",
  "department": "Operations"
}'

📥 Sample JSON Response

JSON

{
  "uuid": "9d8122e5-4173-497a-9015-f4f2d9482c1a",
  "email": "[email protected]",
  "fullName": "Jane Smith",
  "status": "PENDING_INVITATION"
}

3️⃣ Retrieve All Users

Fetch detailed information about a specific user using their UUID.

🔗 Endpoint

GET /v2/users/{uuid}

📤 cURL Request

cURL

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

{
  "uuid": "9d8122e5-4173-497a-9015-f4f2d9482c1a",
  "email": "[email protected]",
  "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.