Phone Numbers
Tags: communication, phone, sms
Endpoints
GET- ListPOST- CreateGET /linkable-phones- Linkable PhonesGET /{phone_number_id}- Get Phone Number IdPUT /{phone_number_id}- Update Phone Number IdPOST /{phone_number_id}/archive- ArchiveGET /{phone_number_id}/archive-blockers- Archive BlockersPOST /{phone_number_id}/link- Link
List
GET /api/v2/w/{workspace_uuid}/phone-numbers
Description:
Phone number and SMS management
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:
Phone number and SMS management
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:
Phone number and SMS management
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
Response: List of dict
Get Phone Number Id
GET /api/v2/w/{workspace_uuid}/phone-numbers/{phone_number_id}
Description:
Phone number and SMS management
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:
Phone number and SMS management
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:
Phone number and SMS management
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:
Phone number and SMS management
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:
Phone number and SMS management
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