Skip to main content
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

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.
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 for schemas and examples, and errors and retries for rate limits.