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

# Call disposition tags: tenant-wide call labeling

> Curate a tenant-level catalog of call tags such as lead, vip, escalated, and follow-up. Stamp them on calls from the dashboard or the REST API for cross-cutting analytics and segment filtering.

# Call Disposition Tags

A disposition tag is a label you stamp on a call: *lead*, *vip*, *escalated*, *follow-up*. Unlike a queue's wrap-up code, which records a single outcome from a catalog defined per queue, disposition tags are a tenant-wide, many-per-call labeling system you curate from the dashboard. Use them to slice voice analytics and build segments across queues and campaigns.

This page covers the tenant-level tag catalog and stamping. If you are looking for the per-queue wrap-up catalog that gates `busy → available` (set `requireDisposition` on the queue; those codes come from queue configuration, not this editor), see [Wrap-up codes](/voice/wrap-up-codes).

**Base path:** `/api/v1/voice`

**Authentication:** Clerk session (`Authorization: Bearer <token>`) or API key (`X-API-Key`).

**Scope:** `voice` read to list the catalog and read a call's stamps, `voice` write to stamp a call. Catalog create, update, and delete are restricted to owners and admins.

***

## The tenant-level catalog, and how it differs from wrap-up codes

Orbit keeps two separate disposition axes. They sound alike and are easy to conflate:

|             | Disposition tags (this page)                          | Wrap-up codes ([guide](/voice/wrap-up-codes))         |
| ----------- | ----------------------------------------------------- | ----------------------------------------------------- |
| Scope       | One catalog for the whole tenant                      | A catalog per queue                                   |
| Cardinality | Many tags on one call                                 | Exactly one code per conversation                     |
| Source      | Editable in the dashboard at Voice → Disposition Tags | Defined in queue configuration                        |
| Gate        | No status gate; stamping is record-keeping            | Can block `busy → available` until a code is recorded |
| Purpose     | Cross-cutting analytics and segment filtering         | Outcome capture and wrap-up enforcement               |

Each tag row has:

* **`slug`**: the lowercase identifier you post back (for example `lead`, `vip`, `escalated`, `follow-up`). Unlike a wrap-up code, the slug is mutable: stamps reference the catalog row by id, so renaming a tag rewrites history cleanly instead of orphaning past stamps.
* **`label`**: the human-readable text the picker and chips show.
* **`color`**: optional hex value for the chip swatch.
* **`sortOrder`**: picker display order.
* **`isActive`**: retiring a tag is a soft-delete. Historical stamps keep resolving the label, the slug is freed for reuse, and you can reactivate the row later.

A slug must be unique among the tenant's active tags. Creating or renaming into a duplicate returns `409 DISPOSITION_TAG_ALREADY_EXISTS`.

## Curate the catalog in the dashboard

Open **Voice → Disposition Tags**. Owners and admins can:

1. **Create** a tag with a slug, label, and colour.
2. **Rename** a tag (slug or label). Past stamps follow the rename because they reference the row, not the slug.
3. **Recolour** the chip swatch, or **reorder** the picker.
4. **Retire** a tag. This is a soft-delete: stamps keep the label and the slug becomes available again. Reactivate from the same editor with the inactive-rows view.

Agents stamp from the catalog but do not curate it.

## Stamp and read tags on a call

On a call's detail page, the disposition-tag panel shows the tags already applied as coloured chips and offers the remaining active catalog for stamping. Applying is additive: re-stamping the same tag on the same call is idempotent (a retry refreshes who stamped it and when instead of duplicating the row), and there is no un-stamp operation (catalog retirement, not deletion from a call, is how a label leaves circulation).

Typical starter catalog: `lead`, `vip`, `escalated`, `follow-up`, plus your own product or campaign labels (for example `product-bug-login`).

### REST equivalent

Stamp a call by slug, or by catalog id; you can mix both in one request:

```http theme={null}
POST /api/v1/voice/calls/{callId}/disposition-tags
Content-Type: application/json

{
  "tagSlugs": ["vip", "follow-up"],
  "queueId": "5f1e2c4a-9b3d-4e7f-a1c8-2d5b7e9f0a12"
}
```

A slug or id that does not resolve to an active catalog row returns `404 DISPOSITION_TAG_NOT_FOUND` with the missing values listed. The stamp records the principal who posted it, so audit and analytics attribute the label correctly. `queueId` is optional context for where the stamp originated.

Read a call's current stamps:

```http theme={null}
GET /api/v1/voice/calls/{callId}/disposition-tags
```

The response joins against the catalog, so chips still render a label and colour even for a tag retired after the stamp.

## Catalog REST endpoints

For automation, such as syncing a taxonomy from another system or bulk-curating tags:

| Operation                                                                                                             | Endpoint                                     |
| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| List active tags (add `?includeInactive=true` for the editor view; paginated with `page` / `pageSize`, capped at 200) | `GET /api/v1/voice/disposition-tags`         |
| Create a tag                                                                                                          | `POST /api/v1/voice/disposition-tags`        |
| Rename, recolour, reorder, or retire/reactivate                                                                       | `PATCH /api/v1/voice/disposition-tags/{id}`  |
| Retire (soft-delete; reactivate with `PATCH { "isActive": true }`)                                                    | `DELETE /api/v1/voice/disposition-tags/{id}` |

Create body: `slug`, `label`, optional `color` (hex), optional `sortOrder`. Update accepts any subset of those fields plus `isActive`; a rename that lands on another active tag's slug returns `409`.

## Audit and analytics posture

Every catalog change and every stamp lands in the audit log with the actor (`voice.disposition_tag.created/updated/deleted`, `voice.call_tag.stamped`), so QA can answer "who labeled this call and when."

Tags exist purely in Orbit's data plane. Stamping a tag never touches SIP signalling; it changes no call routing, no billing, and no provider interaction. Tags stamp analytics: use them to filter and segment voice reporting (for example, compare handle time for `vip`-stamped calls against the fleet), alongside the outcome axis that [wrap-up codes](/voice/wrap-up-codes) record.