openapi: 3.2.0
info:
title: Webex Numbers API
version: 1.0.0
description: 'Operations tagged Numbers across 2 of this provider''s published API definitions: webex-cloud-calling-openapi.json,
webex-numbers-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: 11/11
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: Numbers
paths:
/telephony/config/locations/{locationId}/numbers:
post:
responses:
'201':
description: Created
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: Add Phone Numbers to a Location
operationId: Add Phone Numbers to a location
description: 'Adds a specified set of phone numbers to a location for an organization. Phone numbers must follow the
E.164 format.
Each location has a set of phone numbers that can be assigned to people, workspaces, or features. Active phone numbers
are in service.
Adding a phone number to a location requires a full administrator auth token with a scope of `spark-admin:telephony_config_write`.
Phone numbers included in the request that already exist in the location will simply be ignored.
<br/>
<div><Callout type="warning">This API is only supported for adding DID and Toll-free numbers to non-integrated PSTN
connection types such as Local Gateway (LGW) and Non-integrated CPP. It should never be used for locations with integrated
PSTN connection types like Cisco Calling Plans or Integrated CCP because backend data issues may occur.
</Callout></div>
<div><Callout type="warning">Mobile numbers can be added to any location that has PSTN connection setup. Only 20 mobile
numbers can be added per request.
</Callout></div>'
tags:
- Numbers
parameters:
- name: locationId
in: path
description: LocationId to which numbers should be added.
required: true
example: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzM2ZTFlM2Y1LWJhODEtNDRiNC05ZGQ1LWIyMmVlNGY1MDIyZA
schema:
type: string
- name: orgId
in: query
description: Organization of the Route Group.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
requestBody:
content:
application/json:
example:
phoneNumbers:
- '+19136748203'
- '+19136748204'
- '+19136748205'
numberType: TOLLFREE
numberUsageType: NONE
state: INACTIVE
carrierId: 123e4567-e89b-12d3-a456-426614174000
schema:
$ref: '#/components/schemas/NumbersPost'
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: Manage Number State in a Location
operationId: Manage Number State in a location
description: 'Activate or deactivate the specified set of phone numbers in a location for an organization.
Each location has a set of phone numbers that can be assigned to people, workspaces, or features. Phone numbers must
follow the E.164 format.
Active phone numbers are in service. A mobile number is activated when assigned to a user. This API will not activate
or deactivate mobile numbers.
Managing phone number state in a location requires a full administrator auth token with a scope of `spark-admin:telephony_config_write`.
<br/>
<div><Callout type="warning">This API is only supported for non-integrated PSTN connection types of Local Gateway
(LGW) and Non-integrated CCP.</Callout></div>'
tags:
- Numbers
parameters:
- name: locationId
in: path
description: '`LocationId` to which numbers should be added.'
required: true
example: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzM2ZTFlM2Y1LWJhODEtNDRiNC05ZGQ1LWIyMmVlNGY1MDIyZA
schema:
type: string
- name: orgId
in: query
description: Organization of the Route Group.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
requestBody:
content:
application/json:
example:
phoneNumbers:
- '+12145557861'
- '+12145551321'
action: DEACTIVATE
schema:
$ref: '#/components/schemas/NumbersRequest'
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: Remove Phone Numbers from a Location
operationId: Remove phone numbers from a location
description: 'Remove the specified set of phone numbers from a location for an organization.
Phone numbers must follow the E.164 format.
Removing a mobile number may require more time depending on mobile carrier capabilities.
Removing a phone number from a location requires a full administrator auth token with a scope of `spark-admin:telephony_config_write`.
A location''s main number cannot be removed.
<br/>
<div><Callout type="warning">This API is only supported for non-integrated PSTN connection types of Local Gateway
(LGW) and Non-integrated CPP. It should never be used for locations with integrated PSTN connection types like Cisco
Calling Plans or Integrated CCP because backend data issues may occur.</Callout></div>'
tags:
- Numbers
parameters:
- name: locationId
in: path
description: '`LocationId` to which numbers should be added.'
required: true
example: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzM2ZTFlM2Y1LWJhODEtNDRiNC05ZGQ1LWIyMmVlNGY1MDIyZA
schema:
type: string
- name: orgId
in: query
description: Organization of the Route Group.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
requestBody:
content:
application/json:
example:
phoneNumbers:
- '+12145557861'
- '+12145551321'
schema:
$ref: '#/components/schemas/NumbersDelete'
/telephony/config/actions/validateNumbers/invoke:
post:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateNumbersResponse'
examples:
example1:
value:
status: OK
numbers:
- number: '+12145557861'
state: Available
tollFreeNumber: false
example2:
value:
status: ERRORS
numbers:
- number: '+12145559000'
state: Unavailable
tollFreeNumber: false
detail:
- '[Error 8361] DN is unavailable : +12145559000'
- number: '+12145553567'
state: Available
tollFreeNumber: false
'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: Validate Phone Numbers
operationId: Validate phone numbers
description: 'Validate the list of phone numbers in an organization. Each phone number''s availability is indicated
in the response.
Each location has a set of phone numbers that can be assigned to people, workspaces, or features. Phone numbers must
follow the E.164 format for all countries, except for the United States, which can also follow the National format.
Active phone numbers are in service.
Validating a phone number in an organization requires a full administrator or location administrator auth token with
a scope of `spark-admin:telephony_config_write`.'
tags:
- Numbers
parameters:
- name: orgId
in: query
description: Organization of the Route Group.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
requestBody:
content:
application/json:
examples:
example1:
value:
phoneNumbers:
- '+12145557861'
example2:
value:
phoneNumbers:
- '+12145559000'
- '+12145553567'
schema:
$ref: '#/components/schemas/ValidateNumbersPostRequest'
/telephony/config/numbers:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/NumberListGetObject'
example:
count:
assigned: 33
unAssigned: 114
inActive: 12
extensionOnly: 692
tollFreeNumbers: 1
total: 839
mobileNumber: 6
serviceNumber: 1
reservedNumber: 1
phoneNumbers:
- phoneNumber: '+12056350001'
extension: '11'
routingPrefix: '1234'
esn: '123411'
state: ACTIVE
phoneNumberType: FAX
mainNumber: false
includedTelephonyTypes: MOBILE_NUMBER
mobileNetwork: mobileNetwork
routingProfile: AttRtPf
tollFreeNumber: false
isServiceNumber: false
location:
id: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OL2E4Mjg5NzIyLTFiODAtNDFiNy05Njc4LTBlNzdhZThjMTA5OA
name: Banglore
owner:
id: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9jODhiZGIwNC1jZjU5LTRjMjMtODQ4OC00NTNhOTE3ZDFlMjk
type: PEOPLE
firstName: sadiqhussain96
lastName: sadiqhussain96
isReservedNumber: false
- phoneNumber: ''
state: ACTIVE
phoneNumberType: ALTERNATE
extension: '568'
routingPrefix: '1234'
esn: '1234568'
mainNumber: false
includedTelephonyTypes: PSTN_NUMBER
tollFreeNumber: false
isServiceNumber: false
location:
id: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OL2M2MDliOGE1LTAxNmQtNDAwNy1hN2E0LTJhMThiZmZjY2FmNg
name: Richardson
owner:
id: Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNzVkMjI4Mi0yZjk1LTQ2MmMtYjFiNC1kYjRlZjU1OTk3MWE
type: PEOPLE
firstName: chandru_2
lastName: test_2
isReservedNumber: true
- phoneNumber: '+12026282002'
state: ACTIVE
phoneNumberType: PRIMARY
mainNumber: true
includedTelephonyTypes: PSTN_NUMBER
tollFreeNumber: false
isServiceNumber: true
location:
id: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzEwN2EzNTkwLWY3OWMtNGM0OS1iM2I2LWQ1MzhjYTA0YWU1MA
name: Washington
isReservedNumber: false
'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 Phone Numbers for an Organization with Given Criteria
operationId: Get Phone Numbers for an Organization with Given Criteria
description: 'List all the phone numbers for the given organization along with the status and owner (if any).
Numbers can be standard, service, or mobile. Both standard and service numbers are PSTN numbers.
Service numbers are considered high-utilization or high-concurrency phone numbers and can be assigned to features
like auto-attendants, call queues, and hunt groups.
Phone numbers can be linked to a specific location, be active or inactive, and be assigned or unassigned.
The owner of a number is the person, workspace, or feature to which the number is assigned.
Only a person can own a mobile number.
Retrieving this list requires a full or read-only administrator or location administrator auth token with a scope
of `spark-admin:telephony_config_read`.'
tags:
- Numbers
parameters:
- name: orgId
in: query
description: List numbers for this organization.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi85NmFiYzJhYS0zZGNjLTExZTUtYTE1Mi1mZTM0ODE5Y2RjOWE
schema:
type: string
- name: locationId
in: query
description: Return the list of phone numbers for this location within the given organization. The maximum length
is 36.
example: Y2lzY29zcGFyazovL3VzL0xPQ0FUSU9OLzEyMzQ1
schema:
type: string
- name: max
in: query
description: Limit the number of phone numbers returned to this maximum count. The default is 2000.
example: 5
schema:
type: integer
- name: start
in: query
description: Start at the zero-based offset in the list of matching phone numbers. The default is 0.
example: 0
schema:
type: integer
- name: phoneNumber
in: query
description: Search for this `phoneNumber`.
example: '+12056852221'
schema:
type: string
- name: available
in: query
description: Search among the available phone numbers. This parameter cannot be used along with `ownerType` parameter
when set to `true`.
example: true
schema:
type: boolean
- name: order
in: query
description: Sort the list of phone numbers based on the following:`lastName`,`dn`,`extension`. Sorted by number and
extension in ascending order.
example: lastName-asc
schema:
type: string
- name: ownerName
in: query
description: Return the list of phone numbers that are owned by the given `ownerName`. Maximum length is 255.
example: Mark
schema:
type: string
- name: ownerId
in: query
description: Returns only the matched number/extension entries assigned to the feature with the specified UUID or
`broadsoftId`.
example: Y2lzY29zcGFyazovL3VzL1BFT1BMRS80M2QzYjY4ZC04MjkwLTRmMzctOTM2NS03MmNhMTcxMzRiODM
schema:
type: string
- name: ownerType
in: query
description: 'Returns the list of phone numbers of the given `ownerType`. Possible input values:'
example: PEOPLE
schema:
type: string
enum:
- PEOPLE
- PLACE
- AUTO_ATTENDANT
- CALL_QUEUE
- PAGING_GROUP
- HUNT_GROUP
- VOICE_MESSAGING
- BROADWORKS_ANYWHERE
- CONTACT_CENTER_LINK
- ROUTE_LIST
- VOICEMAIL_GROUP
- VIRTUAL_LINE
- name: extension
in: query
description: Returns the list of phone numbers with the given extension.
example: '000'
schema:
type: string
- name: numberType
in: query
description: 'Returns the filtered list of phone numbers that contain a given type of number. `available` or `state`
query parameters cannot be used when `numberType=EXTENSION`. Possible input values:'
example: NUMBER
schema:
type: string
enum:
- NUMBER
- EXTENSION
- name: phoneNumberType
in: query
description: 'Returns the filtered list of phone numbers of the given `phoneNumberType`. Response excludes any extensions
without numbers. Possible input values:'
example: PRIMARY
schema:
type: string
enum:
- PRIMARY
- ALTERNATE
- FAX
- DNIS
- Default
- name: state
in: query
description: 'Returns the list of phone numbers with the matching state. Response excludes any extensions without
numbers. Possible input values:'
example: ACTIVE
schema:
type: string
enum:
- ACTIVE
- INACTIVE
- Default
- name: details
in: query
description: Returns the overall count of the phone numbers along with other details for a given organization.
example: true
schema:
type: boolean
- name: tollFreeNumbers
in: query
description: Returns the list of toll-free phone numbers.
example: true
schema:
type: boolean
- name: restrictedNonGeoNumbers
in: query
description: Returns the list of restricted non-geographical numbers.
example: true
schema:
type: boolean
- name: includedTelephonyTypes
in: query
description: Returns the list of phone numbers that are of given `includedTelephonyTypes`. By default, if this query
parameter is not provided, it will list both PSTN and Mobile Numbers. Possible input values are PSTN_NUMBER or MOBILE_NUMBER.
example: PSTN_NUMBER
schema:
type: string
- name: serviceNumber
in: query
description: Returns the list of service phone numbers.
example: true
schema:
type: boolean
- name: reservedNumber
in: query
description: Filters reserved phone numbers. When set to `true`, returns only reserved phone numbers. When set to
`false`, returns only non-reserved phone numbers. When omitted, no reserved-number filter is applied. Reserved numbers
cannot be assigned to people, features, or services. This parameter cannot be used along with the `available` filter,
whether `available` is set to `true` for available numbers or `false` for assigned numbers; using both returns a
`400` error. This parameter also cannot be used along with the `assigned` filter; using both returns a `400` error.
example: true
schema:
type: bo
# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webex/refs/heads/main/openapi/webex-numbers-api-openapi.yml