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

# Custom dispositions

> Share call outcome labels across your workspace while preserving existing personal labels and call history.

Custom dispositions give a business label, such as **Follow up requested**, a built-in
outcome such as `Positive`. New definitions are shared across your workspace.
Members can select them when saving a call; workspace administrators manage them.

## API permissions

Create a key in **Settings → Developers** with `dispositions:read` and/or
`dispositions:write`. Existing keys keep their existing permissions.

* Reads work with personal or workspace keys and return shared definitions from
  the key's workspace.
* Writes require an unrestricted workspace key or a personal key whose owner is
  a current workspace administrator. A member-restricted workspace key cannot
  edit shared settings.
* Every write requires an `Idempotency-Key`. Persist one key per operation and
  reuse it for an identical retry. Reusing it with different data returns `409`.

## Manage shared definitions

| Operation | Endpoint |
| - | - |
| List definitions | `GET /custom-dispositions` |
| Create a definition | `POST /custom-dispositions` |
| Read a definition | `GET /custom-dispositions/{id}` |
| Rename or replace mappings | `PATCH /custom-dispositions/{id}` |
| Delete a definition | `DELETE /custom-dispositions/{id}` |

All paths are relative to `https://api.migration.powerdialer.ai/api/public/v2`.
Use `after` and `limit` for list pagination; follow `nextCursor` until it is null.

```bash theme={null}
curl --request POST \
  --url 'https://api.migration.powerdialer.ai/api/public/v2/custom-dispositions' \
  --header "Authorization: Bearer $POWERDIALER_API_KEY" \
  --header "Idempotency-Key: $POWERDIALER_REQUEST_ID" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Follow up requested","mappedDispositions":["Positive"]}'
```

Names are trimmed, case-sensitive, unique within the workspace and at most 100
characters. Built-in names are reserved. At least one built-in mapping is required.
The first mapping determines CRM, do-not-call and automation behavior when a call
is saved. Existing multiple-mapping definitions keep their order and meaning.

PATCH accepts `name`, `mappedDispositions`, or both. Omitted fields stay unchanged;
a supplied mapping array replaces the entire array in one transaction. These are
configuration endpoints: they do not save a call disposition or trigger CRM writes,
DNC changes, calls, or automation themselves.

## Compatibility and history

Existing personal definitions stay personal and remain available in the app. They
are not automatically merged, moved, deleted, or exposed through the shared API.
When a personal and shared label have the same name, that user's personal mapping
continues to win. Other workspace members use the shared definition.

Shared renames change future selections. Historical call labels remain as recorded;
`renamedCalls` is always zero for shared definitions. Deletes remove the definition
but preserve every historical label. `callsKeepingLabel` counts matching labels on
calls with verified workspace attribution; older unattributed calls are also
preserved but are not included in that count. Call responses and existing webhook
payloads retain their current format.

Legacy personal renames in the app retain their existing behavior: the owner's
historical labels are renamed together. Legacy add/remove mapping endpoints and
single-string `mappedDisposition` request bodies remain supported. Built-in name
collisions are now rejected instead of creating an unusable custom definition.

## Common errors

* `400 invalid_request`: correct the name, mapping values, ID, or request body.
* `403 insufficient_scope`: issue a key with the required disposition permission.
* `403 admin_required`: use a current administrator's personal key.
* `403 workspace_wide_key_required`: use an unrestricted workspace key.
* `404 not_found`: the definition is absent or belongs to another workspace.
* `409 disposition_name_conflict`: choose another shared name.
* `409 idempotency_conflict`: use the original request with its original key.

See the [API reference](/api-reference/custom-dispositions/list-custom-dispositions)
for schemas and examples, and [errors and retries](/guides/errors) for rate limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.