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

# Manage AUX codes with the break-reason taxonomy editor

> Define the presence / break reason codes your agents pick from when they change state — map each code to a WFM adherence bucket, mark it paid or unpaid, archive and restore the catalog, and audit every change.

An **AUX code** (short for "auxiliary", the telephony term for a not-ready reason) is a presence reason an agent picks when they step away from taking calls: `lunch`, `break`, `training`, `coffee`, `meeting`, whatever your floor actually uses. The editor at **Voice → AUX Codes** is the per-tenant catalog of those reasons. Agents see the labels when they change their status; workforce-management reporting buckets each one downstream.

Every control on this page is **tenant-owned**: the catalog, the bucket mapping, the paid flag, and the ordering live in your organization's configuration. Creating or editing a code changes reporting configuration only — it never touches call routing.

## 1. Why AUX codes matter: adherence buckets and paid vs unpaid

Each AUX code carries two properties that decide how it counts in adherence reporting:

* **Adherence bucket** — one of the fixed WFM vocabulary: `available`, `on_call`, `wrap_up`, `break`, `lunch`, `training`, `unavailable`, or `logged_out`. Every minute an agent spends in the code rolls into that bucket. Extend the vocabulary freely on slugs (`coffee`, `1-on-1`, `dental`); the bucket tells the report how to classify it.
* **Paid flag** — whether time in the code counts as paid. Paid breaks and unpaid lunch are the common split; your payroll export can read the flag directly.

Out of the box the platform understands three default reasons (`lunch`, `break`, `training`) and falls back to `unavailable` for anything else. The catalog overrides that: when you add a code, its explicit bucket replaces the fallback for every agent who picks it. Codes you don't add fall back to the defaults, unchanged.

## 2. Open Voice → AUX Codes and create a code

In the dashboard, open **Voice → AUX Codes**. The page lists your active catalog ordered by the sort position you set.

To add a code, click **Create code** and fill in:

* **Code** — the slug agents' status changes record. Lowercase ASCII letters, digits, hyphen, underscore; 1–64 characters. The slug is immutable once created (see archiving below).
* **Label** — the human-readable name shown in the agent picker, up to 200 characters.
* **Adherence bucket** — one of the eight fixed buckets above.
* **Paid** — on for paid time, off for unpaid.
* **Sort order** — integer 0–10,000 (default 100). Lower numbers float higher in the picker.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/zeelaltd/images/guides/aux-codes-list.png" alt="The Voice → AUX Codes editor listing the active catalog" />

Create via the API:

```bash cURL theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/aux-codes" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "coffee",
    "label": "Coffee break",
    "adherenceState": "break",
    "paidFlag": true,
    "sortOrder": 90
  }'
```

A slug collision against an active code returns `409 AUX_CODE_ALREADY_EXISTS`. A slug colliding only against an archived code creates fine — the active set is what is unique.

## 3. Edit, archive, and restore the catalog

<img src="https://mintlify.s3.us-west-1.amazonaws.com/zeelaltd/images/guides/aux-codes-create.png" alt="Creating a new AUX code — slug, label, bucket, paid flag, and sort order" />

Any member with the `owner` or `admin` role can edit; agents and supervisors pick from the catalog but a `403` tells them they can't change it.

* **Edit** — the label, bucket, paid flag, sort position, and active flag are all mutable. The **slug is not**: it is the identifier stored verbatim on the audit trail, so renaming would orphan historical rows. To rename, archive the old slug and create the new one.
* **Archive** — a soft delete. The code disappears from the agent picker and every new status change; history keeps the recorded slug.
* **Restore** — flip `isActive` back to `true` from the archived list (`includeInactive=true`), and the code is live again.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/zeelaltd/images/guides/aux-codes-edit.png" alt="Editing or archiving an AUX code — archive is a confirmed soft delete" />

List via the API (defaults to active only, paginated):

```bash cURL theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/aux-codes?page=1&pageSize=100" \
  -H "X-API-Key: dv_live_sk_your_key_here"

# include archived rows
curl "https://api.orbit.devotel.io/api/v1/voice/aux-codes?includeInactive=true" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

Update or archive / restore:

```bash cURL theme={null}
# update label, bucket, paid flag, sort order
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/aux-codes/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Team lunch", "adherenceState": "lunch", "paidFlag": false, "sortOrder": 110 }'

# restore an archived code
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/aux-codes/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": true }'

# archive (soft delete — never hard-removed, audit trail keeps the slug)
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/aux-codes/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

## 4. How agents pick a code when changing presence

When an agent's status changes in the dialer or inbox — stepping away, finishing a call, returning to available — the picker lists every **active** AUX code ordered by sort position, and the recorded slug lands on their status-change event. An agent with no code to pick still flips between the built-in defaults (`lunch`, `break`, `training`, or `unavailable` fallback). The catalog only extends the options; it never leaves agents without one.

## 5. How codes feed adherence reporting

Adherence compares schedule-versus-actual: the minutes an agent spends in each presence state roll into the bucket its code maps to, and the paid flag decides whether the minutes count toward payroll. The bucketing is what makes reports readable — 40 slugs would be noise; eight buckets are a plan.

Related reading:

* [Workforce-management workflows](/guides/wfm-workflows) — the adherence-exception loop and how the buckets feed the plan-vs-actual rollups.
* [Supervisor live monitoring (voice)](/guides/supervisor-live-monitoring-voice) — watch live AUX states across the floor.
* [Quality management program](/guides/quality-management-program) — where adherence rubs up against QA sampling and coaching.

## 6. Troubleshooting

**A code is missing from the agent picker.** Archived codes never render. List with `includeInactive=true` to check; restore via PATCH `{ "isActive": true }`.

**A new code returns 409.** The slug collides with an active row. Pick a different slug — or archive the collision first and re-create to "rename."

**Agents see a 403 editing the catalog.** Only `owner` and `admin` can create, update, or delete; agents and supervisors pick from the list. Issue an API key with the right role, or use a dashboard session with one of those memberships.

**Sort order not applying.** Sort position is an integer 0–10,000 and applies to the *active* set rendered in the picker; archived rows sort to the bottom regardless.

**Audit trail.** Every create / update / archive / restore writes to the audit log with actor, timestamp, and the slug. Read [the audit log guide](/guides/audit-log) to query the trail (`voice.aux_code.created`, `voice.aux_code.updated`, `voice.aux_code.deleted`).