> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tag Value Creation API

> Add a selectable value to an existing dropdown tag

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json
```

## Request

**Content-Type:** `application/json`

This endpoint adds a value to an existing **dropdown** tag. Use the tag's slug (from the [Tag List API](/apis/tag-list) or [Tag Creation API](/apis/tag-creation)) as the `tagId` path parameter.

### Path Parameters

| Parameter | Type   | Required | Description                                                                |
| --------- | ------ | -------- | -------------------------------------------------------------------------- |
| `tagId`   | string | Yes      | Slug identifier of the dropdown tag the value belongs to (1–64 characters) |

### Body Parameters

| Parameter | Type   | Required | Description                                  |
| --------- | ------ | -------- | -------------------------------------------- |
| `value`   | string | Yes      | The tag value to create (1–256 characters)   |
| `alias`   | string | No       | An alias for the tag value (1–64 characters) |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/tag/cost-center/value \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "value": "Engineering",
      "alias": "ENG"
    }'
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/tag/cost-center/value', {
    method: 'POST',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      value: 'Engineering',
      alias: 'ENG'
    })
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/tag/cost-center/value"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "value": "Engineering",
      "alias": "ENG"
  }

  response = requests.post(url, headers=headers, json=payload)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field         | Type    | Description                                                                                                                           |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `ok`          | boolean | Indicates whether the request was successful                                                                                          |
| `created`     | boolean | Indicates whether the tag value was created                                                                                           |
| `tagValue`    | object  | The created tag value                                                                                                                 |
| `tagValue.id` | number  | Unique identifier of the created tag value. Use this as `tagId` in the [Invoice List API](/apis/invoice-list) to filter by this value |

### Response Example

```json theme={null}
{
  "ok": true,
  "created": true,
  "tagValue": {
    "id": 1024
  }
}
```

## Error Responses

### Tag Is Not a Dropdown

Returned when the target tag is not a dropdown tag (values can only be added to dropdown tags).

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Tag should be dropdown"
  }
}
```

### Tag Value Already Exists

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Tag value already exists"
  }
}
```

### Tag Not Found

**HTTP Status:** `404 Not Found`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "TAG_NOT_FOUND",
    "message": "Dropdown tag does not exist"
  }
}
```

### Tag Creation Not Allowed

Returned when adding values to this tag is not permitted because an accounting integration is connected and manages this tag.

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Tag creation not allowed when accounting is connected"
  }
}
```

### Validation Error

Returned when the required `value` field is missing.

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body: must have required property 'value'"
  }
}
```

### Tag Value Creation Failed

In the rare case the value could not be persisted, the response is returned with an HTTP `200 OK` status, `ok: false`, and `created: false`.

**HTTP Status:** `200 OK`

```json theme={null}
{
  "ok": false,
  "created": false
}
```

### Access Denied

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: Only admin and bookkeeper can create this resources"
  }
}
```

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

## Best Practices

* Values can only be added to `DROPDOWN` tags — create the tag with the [Tag Creation API](/apis/tag-creation) using `dataType: "DROPDOWN"` first
* Always check the `created` flag in addition to the HTTP status; a failure is returned with `ok: false` and `created: false` under a `200 OK` status
* Use the returned `tagValue.id` to filter transactions (for example, in the [Invoice List API](/apis/invoice-list)) by this tag value
* Access is limited to users with tag create permission and an admin or bookkeeper role