🔍 What is the Labels API?
The Labels API (v2) allows you to manage custom classification tags (called labels) in your Clara account. Labels are useful for organizing transactions, users, or workflows based on internal categorization (e.g., "Client A", "Internal Event", "R&D", etc.).
With this API, you can:
- Create, update, and delete labels
- Retrieve all existing labels or a specific one
- Bulk-delete labels when no longer needed
📌 Available Endpoints
| Operation | Endpoint | Method |
|---|---|---|
| List all labels | /v2/labels | GET |
| Get label by UUID | /v2/labels/{uuid} | GET |
| Create multiple label | /v2/labels | POST |
| Update a label | /v2/labels/{uuid} | PATCH |
| Delete a label | /v2/labels/{uuid} | DELETE |
| Delete multiple labels | /v2/labels/delete | POST |
1️⃣ List all labels
Use this endpoint to retrieve all the labels that have been created in your organization.
You can use this data to show label options in a UI, filter transactions by label, or review current classification structures.
🔗 Endpoint
GET /v2/labels
📤 cURL Request
curl -X GET \
"https://public-api.mx.clara.com/api/v2/labels" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
📥 Sample JSON Response
[
{
"uuid": "label-123",
"name": "Marketing",
"description": "Marketing-related expenses",
"status": "ACTIVE"
}
]
2️⃣ Get Label by UUID
Use this to fetch full details for a specific label, including its name, description, status, and metadata.
🔗 Endpoint
GET /v2/labels/{uuid}
📤 cURL Request
curl -X GET \
"https://public-api.mx.clara.com/api/v2/labels/label-123" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
📥 Sample JSON Response
{
"uuid": "label-123",
"name": "Marketing",
"description": "Marketing-related expenses",
"status": "ACTIVE"
}
3️⃣ Create multiple Labels
Use this to create a new label, specifying its name and an optional description. You can later assign this label to transactions or users.
🔗 Endpoint
POST /v2/labels
📤 cURL Request
curl -X POST \
"https://public-api.mx.clara.com/api/v2/labels" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Events",
"description": "Internal event budgets"
}'
📥 Sample JSON Response
{
"uuid": "label-789",
"name": "Events",
"description": "Internal event budgets",
"status": "ACTIVE"
}
4️⃣ Update a Label details
Use this endpoint to modify an existing label, such as changing the label name or updating its description.
🔗 Endpoint
PATCH /v2/labels/{uuid}
📤 cURL Request
curl -X PATCH \
"https://public-api.mx.clara.com/api/v2/labels/label-789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Events & Sponsorships",
"description": "Updated name and scope"
}'
5️⃣ Delete a single Label
Use this to delete a single label by UUID. This is useful when a label is no longer relevant or has been replaced by another.
⚠️ Note: Deleting a label doesn't remove it from historical data, but it will no longer be assignable.
🔗 Endpoint
DELETE /v2/labels/{uuid}
📤 cURL Request
curl -X DELETE \
"https://public-api.mx.clara.com/api/v2/labels/label-789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
6️⃣ Delete Multiple Labels
Use this endpoint to bulk-delete labels. This is especially useful for cleanup tasks or automated workflows where multiple labels must be removed at once.
🔗 Endpoint
POST /v2/labels/delete
📤 cURL Request
curl -X POST \
"https://public-api.mx.clara.com/api/v2/labels/delete" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"uuids": ["label-123", "label-456"]
}'
💡 Tip: Labels can be used across transactions, reports, and internal workflows for custom tracking and analysis.
⚠️ Note: Once deleted, a label cannot be reassigned to new entities.