👥 Groups API: How to Use It

🔍 What is the Groups API?

The Groups API allows you to manage user-defined groups within your organization. These groups can represent teams, departments, or any custom segmentation of users, and are useful for assigning policies, budgets, or approval rules.

This API enables you to:

• Create and update groups
• Retrieve details of individual or all groups
• Delete groups when no longer needed

📌 Available Endpoints

Operation	Endpoint	Method
Retrieve all groups	/v2/groups	GET
Retrieve group by ID	/v2/groups/{uuid}	GET
Create group	/v2/groups	POST
Update group	/v2/groups/{uuid}	PATCH
Delete group	/v2/groups/{uuid}	DELETE

1️⃣ Retrieve All Groups

List all groups defined in your organization.

🔗 Endpoint

GET /v2/groups

📤 cURL Request

cURL

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

📥 Sample JSON Response

JSON

[
  {
    "uuid": "group-123",
    "name": "Finance",
    "description": "Handles all financial operations",
    "status": "ACTIVE"
  },
  {
    "uuid": "group-456",
    "name": "Engineering",
    "description": "Software and product development",
    "status": "ACTIVE"
  }
]

2️⃣ Retrieve Group by UUID

Get full details of a specific group by its UUID.

🔗 Endpoint

GET /v2/groups/{uuid}

📤 cURL Request

cURL

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

📥 Sample JSON Response

JSON

{
    "uuid": "group-123",
    "name": "Finance",
    "description": "Handles all financial operations",
    "status": "ACTIVE"
}

3️⃣ Create a Group

Create a new user group by specifying a name and optional description.

🔗 Endpoint

POST /v2/groups

📤 cURL Request

cURL

curl -X POST \
"https://public-api.mx.clara.com/api/v2/groups" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Operations",
  "description": "Logistics and supply chain team"
}'

📥 Sample JSON Response

JSON

{
  "uuid": "group-789",
  "name": "Operations",
  "description": "Logistics and supply chain team",
  "status": "ACTIVE"
}

4️⃣ Update a Group

Edit the name or description of an existing group.

🔗 Endpoint

PATCH /v2/groups/{uuid}

📤 cURL Request

cURL

curl -X PATCH \
"https://public-api.mx.clara.com/api/v2/groups/group-789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "Ops",
  "description": "Updated name for Operations team"
}'

5️⃣ Delete a Group

Remove a group from your organization by UUID. Use with caution, as this may impact user-role associations or policy rules.

🔗 Endpoint

DELETE /v2/groups/{uuid}

📤 cURL Request

cURL

curl -X DELETE \
"https://public-api.mx.clara.com/api/v2/groups/group-789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

💡 Tip: Groups can be used to assign policies, budgets, or approval flows in a centralized way.

⚠️ Note: Deleting a group does not affect users, but it may disrupt processes tied to that group such as approval chains or spend limits.