Phone numbers¶

Use an API key or REST OAuth access token. Scopes and your current workspace permissions apply together. All examples are illustrative.

Assign to Agent phone numbers¶

PUT /api/external/v1/phone-numbers/{id}/assignment

Scope: phone-numbers:write

Read the resource first. Send its current ETag, including quotes, in If-Match. Changes live default routing only. Active overrides, Flow routes or an Agent already assigned another number can block with 409. Does not buy or release a number.

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`If-Match`	Header	`string`	Yes	ETag from the preceding read, including quotes. Example: `"revision-from-get"`

Request body · application/json

FieldsExample

Field	Type	Required	Description
`agentId`	`string` (uuid)	Yes	ID of the Agent.

{
  "agentId": "00000000-0000-0000-0000-000000000001"
}

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`number`	`string`	Phone number stored in the workspace.
`country`	`string`	Country code.
`routingTimezone`	`string`	Timezone used for routing schedules.
`maxAiCallDurationSeconds`	`integer` (int32)	Maximum AI call duration, in seconds.
`defaultRoute`	`object`	Default routing target, or null when no default is assigned.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.

defaultRoute — fields

Field	Type	Description
`type`	`string`	Type of default routing target. Values: `AGENT`, `AGENTIC_FLOW`
`id`	`string` (uuid)	Resource ID in your workspace.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "number": "string",
  "country": "string",
  "routingTimezone": "string",
  "maxAiCallDurationSeconds": 0,
  "defaultRoute": {
    "type": "AGENT",
    "id": "00000000-0000-0000-0000-000000000001"
  },
  "revision": "revision-from-get"
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Clear assignment phone numbers¶

DELETE /api/external/v1/phone-numbers/{id}/assignment

Scope: phone-numbers:write

Read the resource first. Send its current ETag, including quotes, in If-Match. Changes live default routing only. Active overrides, Flow routes or an Agent already assigned another number can block with 409. Does not buy or release a number.

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.
`If-Match`	Header	`string`	Yes	ETag from the preceding read, including quotes. Example: `"revision-from-get"`

Response 204

Deleted; no response body.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`409`	Missing/stale revision or dependency/routing conflict. Read again before retrying.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

Read phone number¶

GET /api/external/v1/phone-numbers/{id}

Scope: phone-numbers:read

Parameters

Name	Location	Type	Required	Description
`id`	Path	`string` (uuid)	Yes	Resource identifier in the bound workspace.

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`
`ETag`	`string`	Current revision. Send unchanged, including quotes, as If-Match when required. Example: `"revision-from-get"`

application/json

FieldsExample

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`number`	`string`	Phone number stored in the workspace.
`country`	`string`	Country code.
`routingTimezone`	`string`	Timezone used for routing schedules.
`maxAiCallDurationSeconds`	`integer` (int32)	Maximum AI call duration, in seconds.
`defaultRoute`	`object`	Default routing target, or null when no default is assigned.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.

defaultRoute — fields

Field	Type	Description
`type`	`string`	Type of default routing target. Values: `AGENT`, `AGENTIC_FLOW`
`id`	`string` (uuid)	Resource ID in your workspace.

{
  "id": "00000000-0000-0000-0000-000000000001",
  "number": "string",
  "country": "string",
  "routingTimezone": "string",
  "maxAiCallDurationSeconds": 0,
  "defaultRoute": {
    "type": "AGENT",
    "id": "00000000-0000-0000-0000-000000000001"
  },
  "revision": "revision-from-get"
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`404`	Resource is unavailable in the bound workspace.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.

List phone numbers¶

GET /api/external/v1/phone-numbers

Scope: phone-numbers:read

Parameters

Name	Location	Type	Required	Description
`page`	Query	`integer` (int32)	No	Page index, starting at 0. Rules: `0–100000` Default: `0`
`size`	Query	`integer` (int32)	No	Results per page. Rules: `1–100` Default: `25`

Response 200

Success.

Header	Type	Description
`Cache-Control`	`string`	The response must not be cached. Example: `no-store`

application/json

FieldsExample

Field	Type	Description
`items`	List of `object`	Results on this page.
`page`	`integer` (int32)	Current page index, starting at 0.
`size`	`integer` (int32)	Number of results requested per page.
`totalElements`	`integer` (int64)	Total number of matching results.
`totalPages`	`integer` (int32)	Total number of result pages.

items — fields

Field	Type	Description
`id`	`string` (uuid)	Resource ID in your workspace.
`number`	`string`	Phone number stored in the workspace.
`country`	`string`	Country code.
`routingTimezone`	`string`	Timezone used for routing schedules.
`maxAiCallDurationSeconds`	`integer` (int32)	Maximum AI call duration, in seconds.
`defaultRoute`	`object`	Default routing target, or null when no default is assigned.
`revision`	`string`	Current resource revision. Use the response ETag for If-Match when updating.

defaultRoute — fields

Field	Type	Description
`type`	`string`	Type of default routing target. Values: `AGENT`, `AGENTIC_FLOW`
`id`	`string` (uuid)	Resource ID in your workspace.

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "number": "string",
      "country": "string",
      "routingTimezone": "string",
      "maxAiCallDurationSeconds": 0,
      "defaultRoute": {
        "type": "AGENT",
        "id": "00000000-0000-0000-0000-000000000001"
      },
      "revision": "revision-from-get"
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}

Error responses

Status	Meaning
`400`	Invalid input, unsupported selection or time range.
`401`	Missing, expired or invalid credential. The body may be empty.
`403`	Required scope or current user permission missing. The body may be empty.
`429`	Shared workspace budget exceeded. Honor Retry-After; do not blindly replay uncertain writes.
`503`	Temporarily unavailable. Check uncertain writes before retrying.

Error body

Field	Type	Description
`status`	`integer`	HTTP status code.
`error`	`string`	Description of the error.
`details`	`any`	Additional error details, when available. Rules: `null` allowed
`code`	`string`	Machine-readable error code.
`params`	`object`	Additional values associated with the error code.
`fieldErrors`	`object`	Validation errors grouped by input field.

For 429 or 503, honor the Retry-After header (seconds). Check uncertain writes before retrying.