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

# Phone Numbers

API operations for phone numbers. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## List phone numbers

Returns every phone number of one workspace in one response, or only those assigned to one project, each with the `voice` and `sms` targets it answers as.

### Endpoint

```http
GET /v1/stable/phone-number
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Optional · string

List only the numbers assigned to this project, for either target. Mutually exclusive with `workspaceID`.

```json
{
  "description": "List only the numbers assigned to this project, for either target. Mutually exclusive with `workspaceID`.",
  "type": "string",
  "minLength": 1
}
```

#### `workspaceID`

Optional · string

List every number the workspace holds, assigned or not. Mutually exclusive with `projectID`.

```json
{
  "description": "List every number the workspace holds, assigned or not. Mutually exclusive with `projectID`.",
  "type": "string",
  "minLength": 1
}
```

### Responses

#### 200

Returns the phone numbers, each with its name, `value`, provider, and the `voice` and `sms` targets that name the project, environment, and version it is assigned to (null when a side is unassigned).

Schema:

```json
{
  "$ref": "#/components/schemas/StablePhoneNumberListResponse"
}
```

Example:

```json
{
  "phoneNumbers": [
    {
      "id": "<string>",
      "sms": "<StablePhoneNumberTarget>",
      "name": "<string>",
      "value": "<string>",
      "voice": "<StablePhoneNumberTarget>",
      "provider": "<PhoneNumberProvider>",
      "workspaceID": "<string>",
      "providerResourceID": "<string>",
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/phone-number?projectID=<projectID>&workspaceID=<workspaceID>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/phone-number?projectID=<projectID>&workspaceID=<workspaceID>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/phone-number?projectID=<projectID>&workspaceID=<workspaceID>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf phone-number list --project-id <projectID> --workspace-id <workspaceID>
```


## Create phone number

Adds a phone number to a workspace, either by buying one through Voiceflow or by connecting a number you already own with its provider credentials. A new number is assigned to nothing and answers nothing until you assign it.

### Endpoint

```http
POST /v1/stable/phone-number
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StablePhoneNumberCreateRequest"
      }
    }
  }
}
```

### Responses

#### 201

Returns the new phone number with its ID, `value`, and provider. Its `voice` and `sms` targets are null because it is not assigned to a project yet.

Schema:

```json
{
  "$ref": "#/components/schemas/StablePhoneNumberResponse"
}
```

Example:

```json
{
  "phoneNumber": {
    "id": "<string>",
    "sms": {
      "version": "draft",
      "projectID": "<string>",
      "environmentAlias": "<string>"
    },
    "name": "<string>",
    "value": "<string>",
    "voice": {
      "version": "draft",
      "projectID": "<string>",
      "environmentAlias": "<string>"
    },
    "provider": "twilio",
    "workspaceID": "<string>",
    "providerResourceID": "<string>",
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z"
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/phone-number' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "",
  "workspaceID": "<string>",
  "provider": "voiceflow-telnyx",
  "areaCode": 0,
  "country": "CA"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/phone-number', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "",
    "workspaceID": "<string>",
    "provider": "voiceflow-telnyx",
    "areaCode": 0,
    "country": "CA"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/phone-number',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "",
      "workspaceID": "<string>",
      "provider": "voiceflow-telnyx",
      "areaCode": 0,
      "country": "CA"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf phone-number create <<'JSON'
{
  "name": "",
  "workspaceID": "<string>",
  "provider": "voiceflow-telnyx",
  "areaCode": 0,
  "country": "CA"
}
JSON
```


## Get phone number

Returns one phone number with its provider and the targets each side answers as. The `phoneNumberID` is the ID Voiceflow gives the number, not the number itself.

### Endpoint

```http
GET /v1/stable/phone-number/{phoneNumberID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `phoneNumberID`

Required · string

The ID of the phone number to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `workspaceID`

Required · string

The ID of the workspace the number belongs to.

```json
{
  "type": "string",
  "description": "The ID of the workspace the number belongs to."
}
```

### Responses

#### 200

Returns the phone number with its name, `value`, provider, and the `voice` and `sms` targets naming the project, environment, and version each side answers as.

Schema:

```json
{
  "$ref": "#/components/schemas/StablePhoneNumberResponse"
}
```

Example:

```json
{
  "phoneNumber": {
    "id": "<string>",
    "sms": {
      "version": "draft",
      "projectID": "<string>",
      "environmentAlias": "<string>"
    },
    "name": "<string>",
    "value": "<string>",
    "voice": {
      "version": "draft",
      "projectID": "<string>",
      "environmentAlias": "<string>"
    },
    "provider": "twilio",
    "workspaceID": "<string>",
    "providerResourceID": "<string>",
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z"
  }
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>?workspaceID=<workspaceID>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>?workspaceID=<workspaceID>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>?workspaceID=<workspaceID>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf phone-number get --phone-number-id <phoneNumberID> --workspace-id <workspaceID>
```


## Update phone number

Renames a phone number. The name is a label shown in the workspace; it does not change the number, its provider, or where it routes.

### Endpoint

```http
PATCH /v1/stable/phone-number/{phoneNumberID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `phoneNumberID`

Required · string

The ID of the phone number to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `workspaceID`

Required · string

The ID of the workspace the number belongs to.

```json
{
  "type": "string",
  "description": "The ID of the workspace the number belongs to."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StablePhoneNumberUpdateRequest"
      }
    }
  }
}
```

### Responses

#### 200

Confirms the phone number was updated. The body is a message only, so refetch the phone number to see its new name.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>?workspaceID=<workspaceID>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>?workspaceID=<workspaceID>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>?workspaceID=<workspaceID>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf phone-number update --phone-number-id <phoneNumberID> --workspace-id <workspaceID> <<'JSON'
{
  "name": "<string>"
}
JSON
```


## Delete phone number

Removes a phone number from the workspace, so it stops answering calls and messages; unassign it instead to keep the number. The response carries only a confirmation message, so refetch the phone numbers to see what is left.

### Endpoint

```http
DELETE /v1/stable/phone-number/{phoneNumberID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `phoneNumberID`

Required · string

The ID of the phone number to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `workspaceID`

Required · string

The ID of the workspace the number belongs to.

```json
{
  "type": "string",
  "description": "The ID of the workspace the number belongs to."
}
```

### Responses

#### 200

Confirms the phone number was deleted. The body is a message only, so list the workspace's phone numbers to see the ones you still hold.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDeleteResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request DELETE \
  --url 'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>?workspaceID=<workspaceID>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>?workspaceID=<workspaceID>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.delete(
    'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>?workspaceID=<workspaceID>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf phone-number delete --phone-number-id <phoneNumberID> --workspace-id <workspaceID>
```


## Assign phone number

Points the voice side or the SMS side of a phone number at a project, optionally pinning an environment and a version. Only the side named by `target` changes, so moving a number that uses both sides takes one call per side.

### Endpoint

```http
PUT /v1/stable/phone-number/{phoneNumberID}/assign
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `phoneNumberID`

Required · string

The ID of the phone number to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `workspaceID`

Required · string

The ID of the workspace the number belongs to.

```json
{
  "type": "string",
  "description": "The ID of the workspace the number belongs to."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StablePhoneNumberAssignRequest"
      }
    }
  }
}
```

### Responses

#### 200

Confirms the phone number was assigned. The body is a message only, so refetch the phone number to see the `voice` or `sms` target it now answers as.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PUT \
  --url 'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>/assign?workspaceID=<workspaceID>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "target": "sms",
  "version": "draft",
  "projectID": "<string>",
  "environmentAlias": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>/assign?workspaceID=<workspaceID>', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "target": "sms",
    "version": "draft",
    "projectID": "<string>",
    "environmentAlias": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.put(
    'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>/assign?workspaceID=<workspaceID>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "target": "sms",
      "version": "draft",
      "projectID": "<string>",
      "environmentAlias": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf phone-number assign --phone-number-id <phoneNumberID> --workspace-id <workspaceID> <<'JSON'
{
  "target": "sms",
  "version": "draft",
  "projectID": "<string>",
  "environmentAlias": "<string>"
}
JSON
```


## Unassign phone number

Clears the assignment of a phone number so it stops reaching an agent, while the number stays on the workspace. Naming a `target` clears that side, and leaving it out clears both.

### Endpoint

```http
PUT /v1/stable/phone-number/{phoneNumberID}/unassign
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `phoneNumberID`

Required · string

The ID of the phone number to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `workspaceID`

Required · string

The ID of the workspace the number belongs to.

```json
{
  "type": "string",
  "description": "The ID of the workspace the number belongs to."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StablePhoneNumberUnassignRequest"
      }
    }
  }
}
```

### Responses

#### 200

Confirms the assignment was cleared. The body is a message only, so refetch the phone number to see which sides are now unassigned.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PUT \
  --url 'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>/unassign?workspaceID=<workspaceID>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "target": "sms"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>/unassign?workspaceID=<workspaceID>', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "target": "sms"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.put(
    'https://realtime-api.voiceflow.com/v1/stable/phone-number/<phoneNumberID>/unassign?workspaceID=<workspaceID>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "target": "sms"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf phone-number unassign --phone-number-id <phoneNumberID> --workspace-id <workspaceID> <<'JSON'
{
  "target": "sms"
}
JSON
```


## Schema definitions

### PhoneNumberProvider

```json
{
  "type": "string",
  "enum": [
    "twilio",
    "vonage",
    "telnyx",
    "voiceflow-telnyx",
    "voiceflow-sip",
    "byo-sip"
  ],
  "x-enumNames": [
    "TWILIO",
    "VONAGE",
    "TELNYX",
    "VOICEFLOW_TELNYX",
    "VOICEFLOW_SIP",
    "BYO_SIP"
  ]
}
```

### StableDeleteResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the deletion."
    }
  },
  "required": [
    "message"
  ]
}
```

### StablePhoneNumber

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the phone number, used to assign, update and delete it. Not the number itself."
    },
    "sms": {
      "nullable": true,
      "description": "Where incoming SMS go, or null when nothing handles SMS on this number.",
      "allOf": [
        {
          "$ref": "#/components/schemas/StablePhoneNumberTarget"
        }
      ]
    },
    "name": {
      "type": "string",
      "description": "The display name of the number within the workspace. Callers never see it."
    },
    "value": {
      "type": "string",
      "description": "The number itself, in E.164 (e.g. `+14155552671`)."
    },
    "voice": {
      "nullable": true,
      "description": "Where incoming calls go, or null when nothing handles calls on this number.",
      "allOf": [
        {
          "$ref": "#/components/schemas/StablePhoneNumberTarget"
        }
      ]
    },
    "provider": {
      "description": "Who the number is held with. `voiceflow-telnyx` is a number bought through Voiceflow; the rest are numbers connected from your own carrier account. Fixed at creation.",
      "allOf": [
        {
          "$ref": "#/components/schemas/PhoneNumberProvider"
        }
      ],
      "enum": [
        "twilio",
        "vonage",
        "telnyx",
        "voiceflow-telnyx",
        "voiceflow-sip",
        "byo-sip"
      ],
      "x-enumNames": [
        "TWILIO",
        "VONAGE",
        "TELNYX",
        "VOICEFLOW_TELNYX",
        "VOICEFLOW_SIP",
        "BYO_SIP"
      ]
    },
    "workspaceID": {
      "type": "string",
      "description": "The ID of the workspace the number belongs to."
    },
    "providerResourceID": {
      "type": "string",
      "description": "The number's ID with the provider, for reconciling against it."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    }
  },
  "required": [
    "id",
    "sms",
    "name",
    "value",
    "voice",
    "provider",
    "workspaceID",
    "providerResourceID",
    "createdAt",
    "updatedAt"
  ]
}
```

### StablePhoneNumberAssignRequest

```json
{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "enum": [
        "sms",
        "voice"
      ],
      "description": "Which side of the number to point at the project: `voice` for incoming calls, `sms` for incoming SMS. The other side is left as it was.",
      "x-enumNames": [
        "SMS",
        "VOICE"
      ]
    },
    "version": {
      "description": "Which version of the environment answers: `published`, the one serving live traffic, or `draft`, the working copy. Requires `environmentAlias`. Defaults to `published`.",
      "type": "string",
      "enum": [
        "draft",
        "published"
      ],
      "x-enumNames": [
        "DRAFT",
        "PUBLISHED"
      ]
    },
    "projectID": {
      "type": "string",
      "description": "The ID of the project the number should reach."
    },
    "environmentAlias": {
      "description": "The alias of the environment that should answer (e.g. `main`). Omit it to assign the number to the project without pinning an environment, which also clears a pin a previous assign set.",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "target",
    "projectID"
  ],
  "additionalProperties": false
}
```

### StablePhoneNumberCreateRequest

```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "name": {
          "default": "",
          "description": "The display name of the number within the workspace. Callers never see it. Defaults to empty.",
          "type": "string"
        },
        "workspaceID": {
          "type": "string",
          "description": "The ID of the workspace to add the number to."
        },
        "provider": {
          "type": "string",
          "enum": [
            "voiceflow-telnyx"
          ],
          "description": "Buy a number through Voiceflow. The carrier picks the digits, so no `value` is sent.",
          "x-enumNames": [
            "VOICEFLOW_TELNYX"
          ]
        },
        "areaCode": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "The area code to buy in (e.g. `415`). The carrier picks the rest of the digits."
        },
        "country": {
          "type": "string",
          "enum": [
            "CA",
            "US"
          ],
          "description": "The country to buy in.",
          "x-enumNames": [
            "CA",
            "US"
          ]
        }
      },
      "required": [
        "workspaceID",
        "provider",
        "areaCode",
        "country"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "name": {
          "default": "",
          "description": "The display name of the number within the workspace. Callers never see it. Defaults to empty.",
          "type": "string"
        },
        "workspaceID": {
          "type": "string",
          "description": "The ID of the workspace to add the number to."
        },
        "provider": {
          "type": "string",
          "enum": [
            "twilio"
          ],
          "description": "Connect a number held in your own Twilio account.",
          "x-enumNames": [
            "TWILIO"
          ]
        },
        "value": {
          "type": "string",
          "pattern": "^\\+\\d+$",
          "description": "The number you already hold, in E.164: a leading `+`, country code, then digits (e.g. `+14155552671`)."
        },
        "twilioAccountSID": {
          "type": "string",
          "minLength": 34,
          "maxLength": 34,
          "description": "The Account SID of the Twilio account holding the number. 34 characters."
        },
        "twilioAuthToken": {
          "type": "string",
          "minLength": 32,
          "maxLength": 32,
          "description": "The Twilio auth token. 32 characters. Write-only — it is never returned."
        }
      },
      "required": [
        "workspaceID",
        "provider",
        "value",
        "twilioAccountSID",
        "twilioAuthToken"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "name": {
          "default": "",
          "description": "The display name of the number within the workspace. Callers never see it. Defaults to empty.",
          "type": "string"
        },
        "workspaceID": {
          "type": "string",
          "description": "The ID of the workspace to add the number to."
        },
        "provider": {
          "type": "string",
          "enum": [
            "vonage"
          ],
          "description": "Connect a number held in your own Vonage account.",
          "x-enumNames": [
            "VONAGE"
          ]
        },
        "value": {
          "type": "string",
          "pattern": "^\\+\\d+$",
          "description": "The number you already hold, in E.164: a leading `+`, country code, then digits (e.g. `+14155552671`)."
        },
        "vonageAPIKey": {
          "type": "string",
          "minLength": 8,
          "maxLength": 8,
          "description": "The API key of the Vonage account holding the number. 8 characters."
        },
        "vonageAPISecret": {
          "type": "string",
          "minLength": 1,
          "description": "The Vonage API secret. Write-only — it is never returned."
        },
        "vonageSignatureSecret": {
          "type": "string",
          "minLength": 1,
          "description": "The Vonage signature secret, used to verify inbound webhooks. Write-only — it is never returned."
        }
      },
      "required": [
        "workspaceID",
        "provider",
        "value",
        "vonageAPIKey",
        "vonageAPISecret",
        "vonageSignatureSecret"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "name": {
          "default": "",
          "description": "The display name of the number within the workspace. Callers never see it. Defaults to empty.",
          "type": "string"
        },
        "workspaceID": {
          "type": "string",
          "description": "The ID of the workspace to add the number to."
        },
        "provider": {
          "type": "string",
          "enum": [
            "telnyx"
          ],
          "description": "Connect a number held in your own Telnyx account.",
          "x-enumNames": [
            "TELNYX"
          ]
        },
        "value": {
          "type": "string",
          "pattern": "^\\+\\d+$",
          "description": "The number you already hold, in E.164: a leading `+`, country code, then digits (e.g. `+14155552671`)."
        },
        "telnyxAPIKey": {
          "type": "string",
          "minLength": 1,
          "description": "The API key of the Telnyx account holding the number. Write-only — it is never returned."
        },
        "telnyxPublicKey": {
          "type": "string",
          "minLength": 1,
          "description": "The Telnyx public key, used to verify inbound webhooks. Base64 Ed25519, 32 bytes decoded."
        }
      },
      "required": [
        "workspaceID",
        "provider",
        "value",
        "telnyxAPIKey",
        "telnyxPublicKey"
      ],
      "additionalProperties": false
    }
  ]
}
```

### StablePhoneNumberListResponse

```json
{
  "type": "object",
  "properties": {
    "phoneNumbers": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StablePhoneNumber"
      },
      "description": "The matching phone numbers, each with the project, environment and version its `voice` and `sms` sides reach."
    }
  },
  "required": [
    "phoneNumbers"
  ]
}
```

### StablePhoneNumberResponse

```json
{
  "type": "object",
  "properties": {
    "phoneNumber": {
      "$ref": "#/components/schemas/StablePhoneNumber"
    }
  },
  "required": [
    "phoneNumber"
  ]
}
```

### StablePhoneNumberTarget

```json
{
  "type": "object",
  "properties": {
    "version": {
      "nullable": true,
      "description": "Which version of the environment answers: `published`, the one serving live traffic, or `draft`, the working copy. Null when no environment is pinned.",
      "type": "string",
      "enum": [
        "draft",
        "published"
      ],
      "x-enumNames": [
        "DRAFT",
        "PUBLISHED"
      ]
    },
    "projectID": {
      "type": "string",
      "description": "The ID of the project this side of the number reaches."
    },
    "environmentAlias": {
      "nullable": true,
      "description": "The alias of the environment this side of the number reaches (e.g. `main`). Null in two cases: the number is assigned to the project with no environment pinned, or the environment it was pinned to has since been deleted — `version` is still whatever the pin asked for, so a null alias beside a non-null `version` is the second case.",
      "type": "string"
    }
  },
  "required": [
    "version",
    "projectID",
    "environmentAlias"
  ]
}
```

### StablePhoneNumberUnassignRequest

```json
{
  "type": "object",
  "properties": {
    "target": {
      "description": "Which side of the number to clear: `voice` or `sms`. Omit it to clear both. Clearing a side that is not assigned is refused.",
      "type": "string",
      "enum": [
        "sms",
        "voice"
      ],
      "x-enumNames": [
        "SMS",
        "VOICE"
      ]
    }
  },
  "additionalProperties": false
}
```

### StablePhoneNumberUpdateRequest

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The display name of the number within the workspace. Callers never see it."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
```

### StableUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    }
  },
  "required": [
    "message"
  ]
}
```
