> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/objects/tag.md).

# The tag object

The tag object in the Shortcut API - every field, an example, and the endpoints that return it.

A tag that can be attached to customers and leads.

## Fields

| Field       | Type      | Description                                 |
| ----------- | --------- | ------------------------------------------- |
| `id`        | id        | The tag's id.                               |
| `object`    | `"tag"`   | Always `tag`.                               |
| `name`      | string    | The tag's name as shown in the app.         |
| `createdAt` | timestamp | When the tag was created, ISO 8601 in UTC.  |
| `updatedAt` | timestamp | When the tag last changed, ISO 8601 in UTC. |

## Example

```json
{
  "id": "8cd6db81-8921-46c8-856b-520f81b58d56",
  "object": "tag",
  "name": "Corner lot",
  "createdAt": "2026-10-16T17:04:12.381Z",
  "updatedAt": "2026-10-16T17:04:12.381Z"
}
```

## Endpoints

| Endpoint              | What it does |
| --------------------- | ------------ |
| `GET /v1/tags`        | List tags    |
| `POST /v1/tags`       | Create a tag |
| `GET /v1/tags/{id}`   | Get a tag    |
| `PATCH /v1/tags/{id}` | Rename a tag |

## Deleted tag

The answer of `DELETE /v1/tags/{id}`.

| Field           | Type    | Description                                            |
| --------------- | ------- | ------------------------------------------------------ |
| `id`            | id      | The deleted tag's id.                                  |
| `object`        | `"tag"` | Always `tag`.                                          |
| `deleted`       | `true`  | Always true.                                           |
| `detachedCount` | integer | How many customers and leads the tag was removed from. |

```json
{
  "id": "8cd6db81-8921-46c8-856b-520f81b58d56",
  "object": "tag",
  "deleted": true,
  "detachedCount": 1
}
```