{ "data": { "id": "7c0a3f9e-1b2d-4f6a-8c5d-9e2b4a7f1c83", "slug": "vip", "label": "VIP customer", "color": "#d946ef", "sortOrder": 10, "isActive": true, "createdAt": "2026-09-24T08:12:41.000Z", "updatedAt": "2026-09-24T08:12:41.000Z" }, "meta": { "request_id": "req_3kq1v8y2w5n0", "timestamp": "2026-09-24T08:12:41.012Z" } }

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. 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)
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:

Create a tag with a slug, label, and colour.
Rename a tag (slug or label). Past stamps follow the rename because they reference the row, not the slug.
Recolour the chip swatch, or reorder the picker.
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 — the sample section below posts a fully annotated body. The catalog and stamping endpoints are documented with full worked samples under Catalog and stamp samples. 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.

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.

Catalog and stamp samples

The samples below exercise the full catalog → stamp → read → error loop. SDK paths are relative to /api/v1; where the SDK has no typed helper for a route yet, the samples use the request escape hatch.

Create a catalog tag

POST /api/v1/voice/disposition-tags adds a tag to the tenant catalog. Owners and admins only. The request below sets the slug (what you post back), a label, and an optional colour and picker position.

curl -X POST "https://orbit.devotel.io/api/v1/voice/disposition-tags" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "slug": "vip",
  "label": "VIP customer",
  "color": "#d946ef",
  "sortOrder": 10
}'

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! })

const tag = await orbit.request('POST', '/voice/disposition-tags', {
  slug: 'vip',
  label: 'VIP customer',
  color: '#d946ef',
  sortOrder: 10,
})
console.log(tag.data.id)

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

result = client.request(
    "POST",
    "/voice/disposition-tags",
    json_body={
        "slug": "vip",
        "label": "VIP customer",
        "color": "#d946ef",
        "sortOrder": 10,
    },
)
print(result["data"]["id"])

{
  "data": {
    "id": "7c0a3f9e-1b2d-4f6a-8c5d-9e2b4a7f1c83",
    "slug": "vip",
    "label": "VIP customer",
    "color": "#d946ef",
    "sortOrder": 10,
    "isActive": true,
    "createdAt": "2026-09-24T08:12:41.000Z",
    "updatedAt": "2026-09-24T08:12:41.000Z"
  },
  "meta": {
    "request_id": "req_3kq1v8y2w5n0",
    "timestamp": "2026-09-24T08:12:41.012Z"
  }
}

{
  "error": {
    "code": "DISPOSITION_TAG_ALREADY_EXISTS",
    "message": "An active disposition tag with slug 'vip' already exists",
    "status": 409,
    "details": { "slug": "vip" }
  },
  "meta": {
    "request_id": "req_4nr1p6v0d2",
    "timestamp": "2026-09-24T08:13:02.121Z"
  }
}

Stamp a call

POST /api/v1/voice/calls/{callId}/disposition-tags applies one or more catalog tags to a call. Mix tagSlugs and tagIds in one body; queueId records optional queue context for where the stamp originated. A re-post of the same tags is idempotent — the API responds with the current stamps instead of duplicating rows.

CALL_ID="cl_8d7f3f0c1b9e"

curl -X POST "https://orbit.devotel.io/api/v1/voice/calls/${CALL_ID}/disposition-tags" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "tagSlugs": ["vip", "follow-up"],
  "tagIds": ["9a2e6d1c-7f3b-40a4-b7c2-6d713bd8a2b8"],
  "queueId": "5f1e2c4a-9b3d-4e7f-a1c8-2d5b7e9f0a12"
}'

const stamped = await orbit.request(
  'POST',
  `/voice/calls/${callId}/disposition-tags`,
  {
    tagSlugs: ['vip', 'follow-up'],
    tagIds: ['9a2e6d1c-7f3b-40a4-b7c2-6d713bd8a2b8'],
    queueId: '5f1e2c4a-9b3d-4e7f-a1c8-2d5b7e9f0a12',
  },
)
console.log(stamped.data.tags.map((t: { slug: string }) => t.slug))

// No typed helper for stamps yet — use the client.Request escape hatch.
body := map[string]any{
	"tagSlugs": []string{"vip", "follow-up"},
	"tagIds":   []string{"9a2e6d1c-7f3b-40a4-b7c2-6d713bd8a2b8"},
	"queueId":  "5f1e2c4a-9b3d-4e7f-a1c8-2d5b7e9f0a12",
}
var out map[string]any
err = client.Request(ctx, http.MethodPost,
	"/voice/calls/"+callID+"/disposition-tags", nil, body, &out, "")

{
  "data": {
    "callId": "cl_8d7f3f0c1b9e",
    "stampedAt": "2026-09-24T08:15:11.004Z",
    "tags": [
      {
        "id": "7c0a3f9e-1b2d-4f6a-8c5d-9e2b4a7f1c83",
        "slug": "vip",
        "label": "VIP customer"
      },
      {
        "id": "9a2e6d1c-7f3b-40a4-b7c2-6d713bd8a2b8",
        "slug": "follow-up",
        "label": "Follow-up"
      }
    ]
  },
  "meta": {
    "request_id": "req_7yt2r5j8c1",
    "timestamp": "2026-09-24T08:15:11.015Z"
  }
}

Read a call’s stamps

GET /api/v1/voice/calls/{callId}/disposition-tags returns each stamped tag joined to the catalog, so chips render label and colour even for a tag retired since the stamp.

curl "https://orbit.devotel.io/api/v1/voice/calls/${CALL_ID}/disposition-tags" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const stamps = await orbit.request(
  'GET',
  `/voice/calls/${callId}/disposition-tags`,
)
console.log(stamps.data.items)

result = client.request("GET", f"/voice/calls/{call_id}/disposition-tags")
print(result["data"]["items"])

{
  "data": {
    "callId": "cl_8d7f3f0c1b9e",
    "items": [
      {
        "id": "a41b5c2d-9f7e-4a31-b2c8-1d46f9b7a3f1",
        "tagId": "7c0a3f9e-1b2d-4f6a-8c5d-9e2b4a7f1c83",
        "slug": "vip",
        "label": "VIP customer",
        "color": "#d946ef",
        "isActive": true,
        "assignedBy": "user_2j8m1x0r",
        "queueId": "5f1e2c4a-9b3d-4e7f-a1c8-2d5b7e9f0a12",
        "assignedAt": "2026-09-24T08:15:11.004Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 64
  },
  "meta": {
    "request_id": "req_6qu3a9y4h0",
    "timestamp": "2026-09-24T08:15:22.431Z",
    "pagination": {
      "cursor": null,
      "has_more": false,
      "total": 1
    }
  }
}

Unresolved slug or id

If a tagSlugs entry or a tagIds entry does not resolve to an active catalog row, the stamp returns 404 DISPOSITION_TAG_NOT_FOUND and lists the values that failed to resolve — missingSlugs or missingIds respectively.

{
  "error": {
    "code": "DISPOSITION_TAG_NOT_FOUND",
    "message": "One or more tagSlugs do not resolve to an active catalog row",
    "status": 404,
    "details": {
      "missingSlugs": ["vip", "lead"]
    }
  },
  "meta": {
    "request_id": "req_2wd4t6k9x3",
    "timestamp": "2026-09-24T08:18:50.811Z"
  }
}

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 record. For the recovery runbook when a stamp 404s (DISPOSITION_TAG_NOT_FOUND) or the queue-side wrap-up gate refuses (DISPOSITION_REQUIRED, NOT_IN_WRAPUP), see Disposition and wrap-up errors.

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Call disposition tags: tenant-wide call labeling

Call Disposition Tags

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

Curate the catalog in the dashboard

Stamp and read tags on a call

REST equivalent

Catalog REST endpoints

Catalog and stamp samples

Create a catalog tag

Stamp a call

Read a call’s stamps

Unresolved slug or id

Audit and analytics posture

​Call Disposition Tags

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

​Curate the catalog in the dashboard

​Stamp and read tags on a call

​REST equivalent

​Catalog REST endpoints

​Catalog and stamp samples

​Create a catalog tag

​Stamp a call

​Read a call’s stamps

​Unresolved slug or id

​Audit and analytics posture

Call Disposition Tags

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

Curate the catalog in the dashboard

Stamp and read tags on a call

REST equivalent

Catalog REST endpoints

Catalog and stamp samples

Create a catalog tag

Stamp a call

Read a call’s stamps

Unresolved slug or id

Audit and analytics posture