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

> Create a new organization tag of a given data type

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

### Body Parameters

| Parameter     | Type   | Required | Description                                                                                         |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | Name of the tag (1–64 characters). It is converted to a URL-safe slug, which becomes the tag's `id` |
| `dataType`    | string | Yes      | Data type of the tag. One of `DROPDOWN`, `VARCHAR`, `NUMBER`, `DATETIME`                            |
| `description` | string | No       | Description of the tag (1–1024 characters)                                                          |

### Data Type Values

| Value      | Description                                                                                                             |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `DROPDOWN` | Tag with a fixed set of selectable values. Add values to it with the [Tag Value Creation API](/apis/tag-value-creation) |
| `VARCHAR`  | Free-text value                                                                                                         |
| `NUMBER`   | Numeric value                                                                                                           |
| `DATETIME` | Date / time value                                                                                                       |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/tag \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Cost Center",
      "dataType": "DROPDOWN",
      "description": "Cost center the expense belongs to"
    }'
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/tag', {
    method: 'POST',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Cost Center',
      dataType: 'DROPDOWN',
      description: 'Cost center the expense belongs to'
    })
  });

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

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

  url = "https://api.pazy.io/v1.0/tag"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "name": "Cost Center",
      "dataType": "DROPDOWN",
      "description": "Cost center the expense belongs to"
  }

  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 was created                                       |
| `tag`     | object  | The created tag                                                             |
| `tag.id`  | string  | Slug identifier of the created tag. Use this as `tagId` in related tag APIs |

### Response Example

```json theme={null}
{
  "ok": true,
  "created": true,
  "tag": {
    "id": "cost-center"
  }
}
```

## Error Responses

### Reserved Tag Name

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Custom Tag name cannot be one of the reserved tags. Please use a different name"
  }
}
```

### Tag Already Exists

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

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

### Validation Error

Returned when a required field is missing or `dataType` is not one of the allowed values.

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/dataType: must be equal to one of the allowed values"
  }
}
```

### Tag Creation Failed

In the rare case the tag 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

* The tag `name` is normalized into a slug (for example, `Cost Center` becomes `cost-center`) — that slug is returned as `tag.id` and is what you use in other tag APIs
* Always check the `created` flag in addition to the HTTP status; a tag-creation failure is returned with `ok: false` and `created: false` under a `200 OK` status
* Create a `DROPDOWN` tag first, then add its selectable values with the [Tag Value Creation API](/apis/tag-value-creation)
* Access is limited to users with tag create permission and an admin or bookkeeper role