Phone Numbers

Tags: communication, phone, sms

Phone number and SMS management

In the product: Phone & Voice

Resources

Request and response models used by the endpoints on this page.

ArchiveBlockersResponse

Field	Type	Required	Description
canArchive	Boolean	✓
workflowBlockers	Array	✓

Example:

{
  "canArchive": false  // Boolean,
  "workflowBlockers": []  // Array<WorkflowBlockerResponse>
}

PhoneNumberResponse

Field	Type	Required	Description
a2pStatus	String
allowAnonymous	Boolean	✓
allowSignup	Boolean	✓
anonymousMemberRoleId	Integer
anonymousRejectionMessage	String
assistantEnabled	Boolean	✓
brandDescription	String	✓
brandName	String	✓
brandWebsite	String	✓
createdAt	DateTime	✓
defaultWorkflowId	Integer
enableSms	Boolean	✓
enableVoice	Boolean	✓
enableWhatsApp	Boolean	✓
id	Integer	✓
inboundCallHandling	String	✓
isArchived	Boolean	✓
isMapped	Boolean	✓
name	String	✓
number	String	✓
operatorGroupId	Integer
operatorNoAnswerAction	String	✓
operatorNoAnswerMessage	String
operatorRingTimeoutSeconds	Integer
providerPhoneUuid	String
restartDelay	Integer
restartPrompt	String
signupMemberRoleId	Integer
smsForwardNumber	String
smsOffHoursMessage	String
smsUnavailableMessage	String
smsWorkMode	String
twilioInboundReady	Boolean	✓
twilioNumberSid	String
updatedAt	DateTime	✓
uuid	String	✓
voiceForwardNumber	String
voiceGreetingMessage	String
voiceOffHoursMessage	String
voiceRequireConsent	Boolean		Default: False
voiceUnavailableMessage	String
voicemailGreeting	String
webhookWarning	String

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "number": "string"  // String,
  "name": "string"  // String,
  "brandName": "string"  // String,
  "brandDescription": "string"  // String,
  "brandWebsite": "string"  // String,
  "createdAt": "2024-01-01T00:00:00Z"  // DateTime,
  "updatedAt": "2024-01-01T00:00:00Z"  // DateTime,
  "allowSignup": false  // Boolean,
  "allowAnonymous": false  // Boolean,
  "signupMemberRoleId": 0  // Integer, optional,
  "anonymousMemberRoleId": 0  // Integer, optional,
  "defaultWorkflowId": 0  // Integer, optional,
  "restartPrompt": "string"  // String, optional,
  "restartDelay": 0  // Integer, optional,
  "enableSms": false  // Boolean,
  "enableVoice": false  // Boolean,
  "enableWhatsApp": false  // Boolean,
  "voiceUnavailableMessage": "string"  // String, optional,
  "voiceGreetingMessage": "string"  // String, optional,
  "voiceRequireConsent": false  // Boolean, optional, default: False,
  "assistantEnabled": false  // Boolean,
  "smsWorkMode": "string"  // String, optional,
  "smsOffHoursMessage": "string"  // String, optional,
  "smsForwardNumber": "string"  // String, optional,
  "smsUnavailableMessage": "string"  // String, optional,
  "inboundCallHandling": "string"  // String,
  "voiceOffHoursMessage": "string"  // String, optional,
  "voiceForwardNumber": "string"  // String, optional,
  "anonymousRejectionMessage": "string"  // String, optional,
  "voicemailGreeting": "string"  // String, optional,
  "isArchived": false  // Boolean,
  "isMapped": false  // Boolean,
  "twilioInboundReady": false  // Boolean,
  "providerPhoneUuid": "string"  // String, optional,
  "operatorGroupId": 0  // Integer, optional,
  "operatorRingTimeoutSeconds": 0  // Integer, optional,
  "operatorNoAnswerMessage": "string"  // String, optional,
  "operatorNoAnswerAction": "string"  // String,
  "twilioNumberSid": "string"  // String, optional,
  "a2pStatus": "string"  // String, optional,
  "webhookWarning": "string"  // String, optional
}

WorkflowBlockerResponse

Field	Type	Required	Description
id	Integer	✓
name	String	✓
uuid	String	✓

Example:

{
  "id": 0  // Integer,
  "uuid": "string"  // String,
  "name": "string"  // String
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/phone-numbers - List
• POST /api/v2/w/{workspace_uuid}/phone-numbers - Create
• GET /api/v2/w/{workspace_uuid}/phone-numbers/linkable-phones - Linkable Phones
• GET /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id} - Get Phone Number Id
• PUT /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id} - Update Phone Number Id
• POST /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id}/archive - Archive
• GET /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id}/archive-blockers - Archive Blockers
• POST /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id}/link - Link

List

GET /api/v2/w/{workspace_uuid}/phone-numbers

Description:

List phone numbers for the workspace, filtered by archive status.

Access: All workspace members can view phone numbers (workspace-scoped resource).

Authorization: Requires phones:read scope

Parameters:

• is_archived (Boolean)

Response: List of PhoneNumberResponse

---

Create

POST /api/v2/w/{workspace_uuid}/phone-numbers

Description:

Create a new phone number for the authenticated user. Requires phones:write scope.

If providerPhoneUuid is provided, looks up the provider phone, verifies org ownership, and sets bidirectional references. Otherwise falls back to looking up by number string in the global pool.

Authorization: Requires phones:write scope

Parameters:

• phone (CreatePhoneNumberRequest)

Response: See PhoneNumberResponse

---

Linkable Phones

GET /api/v2/w/{workspace_uuid}/phone-numbers/linkable-phones

Description:

List provider phones available for linking to workspace phone numbers.

Returns org-owned provider phones that are either:

• Unassigned (available to any workspace in the org)
• Already assigned to this workspace (for re-linking or viewing)

Requires PHONES_WRITE scope.

Authorization: Requires phones:write scope

---

Get Phone Number Id

GET /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id}

Description:

Get a specific phone number by ID or UUID.

Authorization: Requires phones:read scope

Parameters:

• phone_number_id (String)

Response: See PhoneNumberResponse

---

Update Phone Number Id

PUT /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id}

Description:

Update an existing phone number by ID or UUID. Requires phones:write scope.

Authorization: Requires phones:write scope

Parameters:

• phone_number_id (String)
• phone_update (UpdatePhoneNumberRequest)

Response: See PhoneNumberResponse

---

Archive

POST /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id}/archive

Description:

Archive a phone number, releasing the Twilio number back to the pool.

Call and SMS history is preserved. This action cannot be undone.

Authorization: Requires phones:admin scope

Parameters:

• phone_number_id (String)

Response: See PhoneNumberResponse

---

Archive Blockers

GET /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id}/archive-blockers

Description:

Return workflow blockers that prevent archiving this phone number.

Authorization: Requires phones:admin scope

Parameters:

• phone_number_id (String)

Response: See ArchiveBlockersResponse

---

Link

POST /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id}/link

Description:

Link or unlink a workspace phone number to/from a provider phone.

If providerPhoneUuid is provided, sets bidirectional references between the workspace phone and the GLB provider phone. If null, clears the link.

Requires PHONES_WRITE scope.

Authorization: Requires phones:write scope

Parameters:

• phone_number_id (String)
• request - See LinkPhoneRequest

Response: See PhoneNumberResponse

---