Endpoint
GET
/v1/stable/phone-number

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string

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

Minimum length: 1
workspaceID
string

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

Minimum length: 1

Response

200 - application/json

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

phoneNumbers
object[]
required

The matching phone numbers, each with the project, environment and version its voice and sms sides reach.

StablePhoneNumber — see its attributes above
Endpoint
POST
/v1/stable/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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Request body

Response

201 - application/json

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.

phoneNumber
object
required
StablePhoneNumber — see its attributes above
Endpoint
GET
/v1/stable/phone-number/{phoneNumberID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

phoneNumberID
string
required

The ID of the phone number to operate on.

Query parameters

workspaceID
string
required

The ID of the workspace the number belongs to.

Response

200 - application/json

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.

phoneNumber
object
required
StablePhoneNumber — see its attributes above
Endpoint
PATCH
/v1/stable/phone-number/{phoneNumberID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

phoneNumberID
string
required

The ID of the phone number to operate on.

Query parameters

workspaceID
string
required

The ID of the workspace the number belongs to.

Request body

name
string
required

The display name of the number within the workspace. Callers never see it.

Response

200 - application/json

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

message
string
required

A human-readable message confirming the update.

Endpoint
DELETE
/v1/stable/phone-number/{phoneNumberID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

phoneNumberID
string
required

The ID of the phone number to operate on.

Query parameters

workspaceID
string
required

The ID of the workspace the number belongs to.

Response

200 - application/json

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.

message
string
required

A human-readable message confirming the deletion.

Endpoint
PUT
/v1/stable/phone-number/{phoneNumberID}/assign

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

phoneNumberID
string
required

The ID of the phone number to operate on.

Query parameters

workspaceID
string
required

The ID of the workspace the number belongs to.

Request body

target
enum<string>
required

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.

Available options: sms, voice
version
enum<string>

Which version of the environment answers: published, the one serving live traffic, or draft, the working copy. Requires environmentAlias. Defaults to published.

Available options: draft, published
projectID
string
required

The ID of the project the number should reach.

environmentAlias
string

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.

Minimum length: 1

Response

200 - application/json

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.

message
string
required

A human-readable message confirming the update.

Endpoint
PUT
/v1/stable/phone-number/{phoneNumberID}/unassign

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

phoneNumberID
string
required

The ID of the phone number to operate on.

Query parameters

workspaceID
string
required

The ID of the workspace the number belongs to.

Request body

target
enum<string>

Which side of the number to clear: voice or sms. Omit it to clear both. Clearing a side that is not assigned is refused.

Available options: sms, voice

Response

200 - application/json

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

message
string
required

A human-readable message confirming the update.

Schemas

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.