# Create tag

> Creates a new tag on the team. The tag key is auto-generated by slugifying the name.

`POST /v2/api/tags`

<Note>
**Required scope:** `TAGS_WRITE`
</Note>

## Behavior

Pass a display **name** — the tag **key** (its identifier in the rest of the API) is generated automatically by slugifying the name (lowercase, alphanumeric). For example `"Interested"` becomes the key `interested`.

- Names are case-insensitive. Creating `Support` when `support` already exists returns a `409` with code `TAG_ALREADY_EXISTS`.
- Names that describe a call outcome (e.g. `voicemail`, `missed call`, `busy`) are reserved and rejected with a `400` and code `TAG_NAME_IS_CALL_OUTCOME`.
- `color` is an optional hex string (max 7 characters, e.g. `#FF0000`).

The created tag's `id` is the generated key — use it to add the tag to calls or to delete it.

## Idempotency

This endpoint supports the `Idempotency-Key` header. If a request succeeds and you retry with the same key, the stored response is returned without re-executing the operation. See [Idempotency](/docs/guides/error-handling#idempotency).
