openapi: 3.2.0
info:
title: 'Webex Features: Virtual Extensions API'
version: 1.0.0
description: 'Operations tagged Features: Virtual Extensions across 2 of this provider''s published API definitions: webex-cloud-calling-openapi.json,
webex-features-virtual-extensions-api-openapi.yml. Each path carries the servers of the definition it was published in.'
x-provenance:
method: harvested
authored_by: Cisco Webex
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
note: Published by Cisco. Retrieved unmodified except for this x-provenance block.
provider_published: true
derived_view: Per-tag view of webex-cloud-calling-openapi.json, the provider's source document. Operations and schemas
are the provider's, unmodified; only the partition is ours.
derived_from: webex-cloud-calling-openapi.json
operation_coverage: 14/15
x-evidence:
- type: source
url: https://github.com/webex/webex-openapi-specs/blob/main/public-spec/webex-cloud-calling.json
- type: raw
url: https://raw.githubusercontent.com/webex/webex-openapi-specs/main/public-spec/webex-cloud-calling.json
tags:
- name: 'Features: Virtual Extensions'
paths:
/telephony/config/virtualExtensions:
post:
responses:
'201':
description: Created
headers: {}
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: string
description: ID of the newly created virtual extension.
example:
id: Y2lzY29zcGFyazovL3VzL1ZJUlRVQUxfRVhURU5TSU9OLzk0OThkMTE0LWMwMGMtNGZkNC1iMTk5LWU4ODQ2N2UwNzVkNw
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message
will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist.
Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the
system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used
a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that
specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has
been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before
a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact
the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the
request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please
try to reduce it.'
summary: Create a Virtual Extension
operationId: Create a Virtual Extension
description: 'Create new Virtual Extension for the given organization or location.
You can set up virtual extensions at the organization or location level. The organization level enables everyone across
your organization to dial the same extension number to reach someone.
You can use the location level virtual extension like any other extension assigned to the specific location.
Users at the specific location can dial the extension. However, users at other locations can reach the virtual extension
by dialing the ESN.
Creating a virtual extension requires a full administrator or location administrator auth token with a scope of `spark-admin:telephony_config_write`
and `identity:contacts_rw`.'
tags:
- 'Features: Virtual Extensions'
parameters:
- name: orgId
in: query
description: Unique identifier for the organization.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
requestBody:
content:
application/json:
example:
firstName: John
lastName: Smith
displayName: JohnSmith
phoneNumber: '+17011558169'
extension: '9133'
locationId: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OL2E4Mjg5NzIyLTFiODAtNDFiNy05Njc4LTBlNzdhZThjMTA5OA
schema:
$ref: '#/components/schemas/PostVirtualExtensionObject'
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/GetVirtualExtensionListObject'
example:
virtualExtensions:
- id: Y2lzY29zcGFyazovL3VzL1ZJUlRVQUxfRVhURU5TSU9OLzZkNmYwNmVlLTdkNDEtNDQ4Yy05MjgwLWZkM2ZiMDhmOGUyMA
extension: '5001'
routingPrefix: '4321'
esn: '43215001'
phoneNumber: '+16692515287'
firstName: Bob
level: LOCATION
locationId: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OL2QzYjA4MGMwLWU1MjctNDQ1Zi04NTk5LTU5OWJmNzQ2MjViNg
locationName: TestLocation
displayName: Bob Smith
- id: Y2lzY29zcGFyazovL3VzL1ZJUlRVQUxfRVhURU5TSU9OL2JhNTE0MGExLWM0MjItNDRhMC05MmUyLTRkNDQ0ZTg1NDc5NQ
extension: '5001'
esn: '5001'
phoneNumber: '+12135536387'
firstName: John
lastName: Smith
level: ORGANIZATION
displayName: John Smith
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message
will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist.
Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the
system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used
a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that
specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has
been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before
a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact
the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the
request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please
try to reduce it.'
summary: Read the List of Virtual Extensions
operationId: Read the List of Virtual Extensions
description: 'Retrieve virtual extensions associated with a specific customer.
The GET Virtual Extensions API allows administrators to retrieve a list of virtual extensions configured within their
organization. Virtual extensions enable users to dial extension numbers that route to external phone numbers, such
as those of remote workers or frequently contacted clients.
This API returns key information including the extension, associated phone number (in E.164 format), display name,
and the location to which the virtual extension belongs
The API supports filtering by various parameters, such as extension number, phone number, and location name. The results
can be paginated using the `max` and `start` parameters, and the order of the results can be specified using the `order`
parameter.
Retrieving a Virtual Extension requires a full or read-only administrator auth token with a scope of `spark-admin:telephony_config_read`.'
tags:
- 'Features: Virtual Extensions'
parameters:
- name: orgId
in: query
description: Unique identifier for the organization.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
- name: max
in: query
description: Limit the number of virtual extensions returned to this maximum count. Default is 10.
example: '10'
schema:
type: number
- name: start
in: query
description: Start at the zero-based offset in the list of matching virtual extensions. Default is 0.
example: '0'
schema:
type: number
- name: order
in: query
description: Order the list of virtual extensions in ascending or descending order. Default is ascending.
example: ASC
schema:
type: string
- name: extension
in: query
description: Filter the list of virtual extensions by extension number.
example: '5001'
schema:
type: string
- name: phoneNumber
in: query
description: Filter the list of virtual extensions by phone number.
example: '+17011558169'
schema:
type: string
- name: name
in: query
description: Filter the list of virtual extensions by name. This can be either first name or last name.
example: John
schema:
type: string
- name: locationName
in: query
description: Filter the list of virtual extensions by location name.(Only one of the locationName, locationId, and
OrgLevelOnly query parameters is allowed at the same time.)
example: Test1
schema:
type: string
- name: locationId
in: query
description: Filter the list of virtual extensions by location ID.
example: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OL2E4Mjg5NzIyLTFiODAtNDFiNy05Njc4LTBlNzdhZThjMTA5OA
schema:
type: string
- name: orgLevelOnly
in: query
description: Filter the list of virtual extensions by organization level. If orgLevelOnly is true, return only the
organization level virtual extensions.
example: 'true'
schema:
type: boolean
/telephony/config/virtualExtensions/{extensionId}:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/GetVirtualExtensionObject'
example:
id: Y2lzY29zcGFyazovL3VzL1ZJUlRVQUxfRVhURU5TSU9OLzZkNmYwNmVlLTdkNDEtNDQ4Yy05MjgwLWZkM2ZiMDhmOGUyMA
extension: '5001'
routingPrefix: '4321'
esn: '43215001'
phoneNumber: '+6692515287'
firstName: John
level: LOCATION
locationId: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OL2QzYjA4MGMwLWU1MjctNDQ1Zi04NTk5LTU5OWJmNzQ2MjViNg
locationName: Test1
displayName: JohnSmith
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message
will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist.
Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the
system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used
a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that
specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has
been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before
a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact
the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the
request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please
try to reduce it.'
summary: Get a Virtual Extension
operationId: Get a Virtual Extension
description: 'Retrieve Virtual Extension details for the given extension ID.
Virtual extensions integrate remote workers on separate telephony systems into Webex Calling, enabling users to reach
them via extension dialing.
This endpoint allows administrators to retrieve configuration details for a specific virtual extension, ensuring visibility
into the mapping between extensions and external phone numbers.
Retrieving a Virtual Extension requires a full or read-only administrator auth token with a scope of `spark-admin:telephony_config_read`.'
tags:
- 'Features: Virtual Extensions'
parameters:
- name: extensionId
in: path
description: ID of the virtual extension.
required: true
example: Y2lzY29zcGFyazovL3VzL1ZJUlRVQUxfRVhURU5TSU9OLzZkNmYwNmVlLTdkNDEtNDQ4Yy05MjgwLWZkM2ZiMDhmOGUyMA
schema:
type: string
- name: orgId
in: query
description: Unique identifier for the organization.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
put:
responses:
'204':
description: No Content
headers: {}
content: {}
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message
will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist.
Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the
system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used
a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that
specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has
been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before
a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact
the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the
request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please
try to reduce it.'
summary: Update a Virtual Extension
operationId: Update a Virtual Extension
description: 'Update Virtual Extension details for the given extension ID.
This API updates the configuration of an existing virtual extension identified by its unique extension ID. Administrators
can modify fields such as the extension, associated phone number (in E.164 format), display name, and location etc.
Updating a Virtual Extension requires a full administrator or location administrator auth token with a scope of `spark-admin:telephony_config_write`
and `identity:contacts_rw`.'
tags:
- 'Features: Virtual Extensions'
parameters:
- name: extensionId
in: path
description: ID of the virtual extension.
required: true
example: Y2lzY29zcGFyazovL3VzL1ZJUlRVQUxfRVhURU5TSU9OLzZkNmYwNmVlLTdkNDEtNDQ4Yy05MjgwLWZkM2ZiMDhmOGUyMA
schema:
type: string
- name: orgId
in: query
description: Unique identifier for the organization.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
requestBody:
content:
application/json:
example:
firstName: test
lastName: abc
displayName: abc test
phoneNumber: '+1022997098'
extension: '1126'
schema:
$ref: '#/components/schemas/VirtualExtensionPatchRequestObject'
delete:
responses:
'204':
description: No Content
headers: {}
content: {}
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message
will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist.
Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the
system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used
a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that
specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has
been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before
a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact
the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the
request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please
try to reduce it.'
summary: Delete a Virtual Extension
operationId: Delete a Virtual Extension
description: 'Delete Virtual Extension using the extension ID.
This API permanently deletes a virtual extension from the organization. Once deleted, the extension will no longer
route calls to the external phone number, and users won’t be able to reach it via the assigned extension.
Deleting a Virtual Extension requires a full administrator or location administrator auth token with a scope of `spark-admin:telephony_config_write`
and `identity:contacts_rw`.'
tags:
- 'Features: Virtual Extensions'
parameters:
- name: extensionId
in: path
description: ID of the virtual extension.
required: true
example: Y2lzY29zcGFyazovL3VzL1ZJUlRVQUxfRVhURU5TSU9OLzZkNmYwNmVlLTdkNDEtNDQ4Yy05MjgwLWZkM2ZiMDhmOGUyMA
schema:
type: string
- name: orgId
in: query
description: Unique identifier for the organization.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
/telephony/config/virtualExtensions/settings:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/GetVirtualExtensionSettingsObject'
example:
mode: STANDARD
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message
will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist.
Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the
system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used
a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that
specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has
been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before
a successful request can be made.'
'500':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact
the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the
request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please
try to reduce it.'
summary: Get Virtual extension settings
operationId: Get Virtual extension settings
description: 'Retrieve Virtual Extension settings for the given Org.
This API retrieves the virtual extension mode settings configured for a given organization. Virtual extensions can
operate in two modes: STANDARD and ENHANCED. The selected mode determines how the system handles routing and signaling
for virtual extensions.
By default, the virtual extensions that you create use the Standard mode. Another mode, enhanced signaling mode, is
available to all customers, however, virtual extensions won''t function properly in this mode unless your PSTN provider
supports special network signaling extensions and there aren''t many PSTN providers that do.
Retrieving a Virtual Extension settings requires a full or read-only administrator auth token with a scope of `spark-admin:telephony_config_read`.'
tags:
- 'Features: Virtual Extensions'
parameters:
- name: orgId
in: query
description: Unique identifier for the organization.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
put:
responses:
'204':
description: No Content
headers: {}
content: {}
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message
will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist.
Also returned when the requested format is not supported by the requested method.'
'405':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: 'Conflict: The request could not be processed because it conflicts with some established rule of the
system. For example, a person may not be added to a room more than once.'
'410':
description: 'Gone: The requested resource is no longer available.'
'415':
description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used
a media type that is not supported.'
'423':
description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that
specifies how many seconds you need to wait before attempting the request again.'
'428':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has
been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before
a successful request can be made.'
'500':
description: 'Inter
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webex/refs/heads/main/openapi/webex-features-virtual-extensions-api-openapi.yml