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

# Labels

> Create, update, retrieve, and delete transaction labels.

<Warning>This service is not yet available in v3. Available in **v2** only.</Warning>

## 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

<br />

## 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   |

## 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 cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/labels" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Sample JSON Response

```json JSON theme={null}
[
  {
    "uuid": "label-123",
    "name": "Marketing",
    "description": "Marketing-related expenses",
    "status": "ACTIVE"
  }
]
```

<br />

## 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 cURL theme={null}
curl -X GET \
"https://public-api.mx.clara.com/api/v2/labels/label-123" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

```

### Sample JSON Response

```json JSON theme={null}
 {
    "uuid": "label-123",
    "name": "Marketing",
    "description": "Marketing-related expenses",
    "status": "ACTIVE"
  }
```

<br />

## 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 cURL theme={null}
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

```json JSON theme={null}
{
  "uuid": "label-789",
  "name": "Events",
  "description": "Internal event budgets",
  "status": "ACTIVE"
}
```

<br />

## 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 cURL theme={null}
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"
}'
```

<br />

## 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 cURL theme={null}
curl -X DELETE \
"https://public-api.mx.clara.com/api/v2/labels/label-789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

<br />

## 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 cURL theme={null}
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"]
}'
```

<br />

**💡 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.

***

## Endpoint Reference

### `GET /api/v2/labels`

List all labels (v2)

### `POST /api/v2/labels`

Create labels (v2)

**Request Body (`CreateLabelsRequest`):**

| Field   | Type            | Example |
| ------- | --------------- | ------- |
| `names` | array of string |         |

### `PUT /api/v2/labels/{uuid}`

Update label (v2)

**Parameters:**

| Parameter | In   | Type          | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid`    | path | string (uuid) | ✅        |             |

**Request Body (`UpdateLabelRequest`):**

| Field  | Type   | Example              |
| ------ | ------ | -------------------- |
| `name` | string | `Updated Label Name` |

### `DELETE /api/v2/labels/{uuid}`

Delete label (v2)

**Parameters:**

| Parameter | In   | Type          | Required | Description |
| --------- | ---- | ------------- | -------- | ----------- |
| `uuid`    | path | string (uuid) | ✅        |             |

### `DELETE /api/v2/labels/bulk-delete`

Bulk delete labels (v2)

**Request Body (`BulkDeleteLabelsRequest`):**

| Field   | Type            | Example |
| ------- | --------------- | ------- |
| `uuids` | array of string |         |