openapi: 3.0.0
info:
title: Webex Admin Address Book Wholesale Provisioning API
version: 1.0.0
description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling.
tags:
- name: Wholesale Provisioning
paths:
/wholesale/customers:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerListResponse'
example:
items:
- id: Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4
orgId: Y2lzY29zcGFyazovL3VzL09yZ2FuaXphdGlvbi81MmNmNTc2ZC02MGE4LTQwN2EtYjIyYy00NjdjNTE1OTE5MDk
externalId: c1677a16-557a-4fb4-b48f-24adde57ec99
address:
addressLine1: 771 Alder Drive
addressLine2: Cisco Site 5
city: Milpitas
stateOrProvince: CA
zipOrPostalCode: '95035'
country: US
status: provisioned_with_errors
packages:
- common_area_calling
- webex_calling
- webex_meetings
- webex_suite
- webex_voice
- cx_essentials
- webex_calling_standard
resourceDetails:
packages:
- name: common_area_calling
status: provisioned
- name: webex_calling
status: error
warnings:
- errorCode: 2560
description: One or more Webex Calling services are unavailable due to maintenance, unable to start provisioning. Consult status.webex.com and retry later.
- name: webex_meetings
status: provisioned
- name: webex_suite
status: provisioned
- name: webex_voice
status: provisioned
- name: cx_essentials
status: provisioned
- name: webex_calling_standard
status: provisioned
'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: List Wholesale Customers
operationId: List Wholesale Customers
description: Return a list of wholesale customers. There are a number of filter options, which can be combined in a single request.
tags:
- Wholesale Provisioning
parameters:
- name: externalId
in: query
description: Customer external ID.
example: c1677a16-557a-4fb4-b48f-24adde57ec99
schema:
type: string
- name: orgId
in: query
description: The encoded Organization ID for the customer.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi81MmNmNTc2ZC02MGE4LTQwN2EtYjIyYy00NjdjNTE1OTE5MDg
schema:
type: string
- name: status
in: query
description: Customer API status.
example: provisioned_with_errors
schema:
type: array
items:
type: string
example: provisioned_with_errors
description: Customer API status.
- name: offset
in: query
description: Offset value for implementing pagination.
example: '10'
schema:
type: string
- name: max
in: query
description: The maximum number of customers returned in the response.
example: '10'
schema:
type: string
- name: onBehalfOfSubPartnerOrgId
in: query
description: The encoded organization ID for the sub partner.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wZTE4MmUxNS05ZmNhLTQ0NzgtYmEzOC1jNGFiMmUyN2FlZDA=
schema:
type: string
post:
responses:
'202':
description: Accepted
headers:
Location:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceURL'
example:
url: https://webexapis.com/v1/wholesale/customers/Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4
'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: Provision a Wholesale Customer
operationId: Provision a Wholesale Customer
description: "Provision a Wholesale customer for Cisco Webex services.\n\nThis API will allow a Service Provider to map the Wholesale customer and assign the required licenses and entitlements for Webex, Calling and Meetings.\n\nThe Wholesale customer provisioning is asynchronous and thus a background task is created when this endpoint is invoked.\n\n**packages Note:**\n\n* `cisco_calling_plan` is dependent on: `common_area_calling`, `webex_calling`, `webex_suite`, `webex_voice`, `cx_essentials`, `webex_calling_standard`\n\n* `attendant_console` is dependent on: `webex_calling`, `webex_suite`, `cx_essentials`\n\n<div>\n <Callout type='info'>After successful invocation of this endpoint a URL will be returned in the `Location` header, which will point to the [Get a Wholesale Customer](/docs/api/v1/wholesale-provisioning/get-a-wholesale-customer) endpoint for this customer.</Callout>\n</div>"
tags:
- Wholesale Provisioning
parameters:
- name: onBehalfOfSubPartnerOrgId
in: query
description: The encoded organization ID for the sub partner.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wZTE4MmUxNS05ZmNhLTQ0NzgtYmEzOC1jNGFiMmUyN2FlZDA=
schema:
type: string
requestBody:
content:
application/json:
example:
provisioningId: ZjViMzYxODctYzhkZC00NzI3LThiMmYtZjljNDQ3ZjI5MDQ2
packages:
- common_area_calling
orgId: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi81MmNmNTc2ZC02MGE4LTQwN2EtYjIyYy00NjdjNTE1OTE5MDg
externalId: c1677a16-557a-4fb4-b48f-24adde57ec99
address:
addressLine1: '"771 Alder Drive"'
addressLine2: '"Cisco Site 5"'
city: '"Milpitas"'
stateOrProvince: '"CA"'
zipOrPostalCode: '"95035"'
country: '"US"'
customerInfo:
name: '"John''s Pizza"'
primaryEmail: '"john.anderson@acme.com"'
language: '''en'''
provisioningParameters:
calling:
location:
name: '"Head Office"'
address:
addressLine1: '"771 Alder Drive"'
addressLine2: '"Cisco Site 5"'
city: '"Milpitas"'
stateOrProvince: '"CA"'
zipOrPostalCode: '"95035"'
country: '"US"'
timezone: '"America/Los_Angeles"'
language: '"en_us"'
emergencyLocationIdentifier: '"95547321"'
meetings:
timezone: '"America/Los_Angeles"'
packages:
limits:
webex_calling: 50
common_area_calling: 50
webex_meetings: 50
webex_suite: 50
webex_voice: 50
cx_essentials: 50
webex_calling_standard: 50
attendant_console: 50
subPartnerAdminEmail: admin@subpartnerorg.com
schema:
type: object
required:
- provisioningId
- packages
- externalId
- address
properties:
provisioningId:
type: string
example: ZjViMzYxODctYzhkZC00NzI3LThiMmYtZjljNDQ3ZjI5MDQ2
description: 'This Provisioning ID defines how this customer is to be provisioned for Webex Services.
Each Customer Template will have their own unique Provisioning ID. This ID will be displayed under the chosen Customer Template
on [Webex Control Hub](https://admin.webex.com).'
packages:
type: array
items:
$ref: '#/components/schemas/WholesalePackagesCustomer'
description: The complete list of Webex Wholesale packages to be assigned to the customer.
orgId:
type: string
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi81MmNmNTc2ZC02MGE4LTQwN2EtYjIyYy00NjdjNTE1OTE5MDg
description: The organization ID of the enterprise in Webex. Mandatory for existing customers.
externalId:
type: string
example: c1677a16-557a-4fb4-b48f-24adde57ec99
description: External ID of the Wholesale customer.
address:
type: object
required:
- addressLine1
- city
- country
properties:
addressLine1:
type: string
example: '"771 Alder Drive"'
description: Address line 1.
addressLine2:
type: string
example: '"Cisco Site 5"'
description: Address line 2.
city:
type: string
example: '"Milpitas"'
description: Customer's city.
stateOrProvince:
type: string
example: '"CA"'
description: State or Province of the customer. This attribute may be required in specific geographies, please refer to address section in the admin guide for more information.
zipOrPostalCode:
type: string
example: '"95035"'
description: Postal/Zip code of the customer. This attribute may be required in specific geographies, please refer to address section in the admin guide for more information.
country:
type: string
example: '"US"'
description: ISO2 country code of the customer size = 2. This attribute is used to determine the default Dial In number for the Webex Meeting Sites. Refer to the Address section of [help page](https://www.cisco.com/c/en/us/td/docs/voice_ip_comm/cloudCollaboration/wholesale_rtm/wbxbw_b_wholesale-rtm-solution-guide/wbxbw_m_overview-of-webex-wholesale.html#Cisco_Reference.dita_7875bb3e-10c0-4214-8173-7845db31c7a6) for more information.
description: Billing Address of the customer. (There is a 50 character limit on each address line)
customerInfo:
type: object
required:
- name
- primaryEmail
properties:
name:
type: string
example: '"John''s Pizza"'
description: The name of the Wholesale customer. Name cannot include the "%" character.
primaryEmail:
type: string
example: '"john.anderson@acme.com"'
description: The primary email address of the customer.
language:
type: string
example: '''en'''
description: The {ISO-639-1}_{ISO-3166} or {ISO-639-1} locale or language code used as preferred language for organization and Webex Meeting Sites. Refer to the [help page](https://www.cisco.com/c/en/us/td/docs/voice_ip_comm/cloudCollaboration/wholesale_rtm/wbxbw_b_wholesale-rtm-solution-guide/wbxbw_m_overview-of-webex-wholesale.html#Cisco_Reference.dita_deb994cb-9c48-4488-b352-54495c54ba1e) for more information.
description: Mandatory for new customer. Optional if Organization ID is provided.
provisioningParameters:
type: object
properties:
calling:
type: object
required:
- location
properties:
location:
type: object
required:
- name
- address
- timezone
- language
properties:
name:
type: string
example: '"Head Office"'
description: Name of the wholesale customer office.
address:
type: object
required:
- addressLine1
- city
- country
properties:
addressLine1:
type: string
example: '"771 Alder Drive"'
addressLine2:
type: string
example: '"Cisco Site 5"'
city:
type: string
example: '"Milpitas"'
stateOrProvince:
type: string
example: '"CA"'
description: State or Province of the customer in ISO 3166 format. This attribute may be required in specific geographies, please refer to address section in the admin guide for more information.
zipOrPostalCode:
type: string
example: '"95035"'
description: Postal/Zip code of the customer. This attribute may be required in specific geographies, please refer to address section in the admin guide for more information.
country:
type: string
example: '"US"'
description: Address of the wholesale customer. (There is a 50 character limit on each address line)
timezone:
type: string
example: '"America/Los_Angeles"'
description: Customer timezone for calling package. The full list of supported timezones can be found at [List of Time Zones for Wholesale Provisioning](https://help.webex.com/en-us/article/nuh0amab/List-of-Time-Zones-for-Wholesale-Provisioning).
language:
type: string
example: '"en_us"'
description: Determine language for all generated emails and voice announcements.
emergencyLocationIdentifier:
type: string
example: '"95547321"'
description: SIP Header for any emergency calls from this location.
description: Mandatory when provisioning calling packages.
meetings:
type: object
properties:
timezone:
type: string
example: '"America/Los_Angeles"'
description: Customer timezone for meetings package.
packages:
type: object
properties:
limits:
type: object
properties:
webex_calling:
type: number
example: 50
common_area_calling:
type: number
example: 50
webex_meetings:
type: number
example: 50
webex_suite:
type: number
example: 50
webex_voice:
type: number
example: 50
cx_essentials:
type: number
example: 50
webex_calling_standard:
type: number
example: 50
attendant_console:
type: number
example: 50
description: Packages followed by their respective limits.
subPartnerAdminEmail:
type: string
example: admin@subpartnerorg.com
description: The email of the sub partner organization admin.
/wholesale/customers/{customerId}:
get:
responses:
'200':
description: OK
headers:
Location:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
example:
id: Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4
orgId: Y2lzY29zcGFyazovL3VzL09yZ2FuaXphdGlvbi81MmNmNTc2ZC02MGE4LTQwN2EtYjIyYy00NjdjNTE1OTE5MDk
externalId: c1677a16-557a-4fb4-b48f-24adde57ec99
address:
addressLine1: 771 Alder Drive
addressLine2: Cisco Site 5
city: Milpitas
stateOrProvince: CA
zipOrPostalCode: '95035'
country: US
status: provisioned
packages:
- webex_calling
resourceDetails:
packages:
- name: webex_calling
status: provisioned
warnings:
- errorCode: 2560
description: One or more Webex Calling services are unavailable due to maintenance, unable to start provisioning. Consult status.webex.com and retry later.
licenseIds:
- Y2lzY29zcGFyazovL3VzL0xJQ0VOU0UvYjdjNGRlZTgtODZmNi00YzAxLWJkYjMtMTM3MjM2ZWY3NGRmOlNMV0NBXzdmYTBkZjhjLTlmNTEtNGE1Zi05YzY4LTU1ODRlNWM2N2E0Yg
'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 Wholesale Customer
operationId: Get a Wholesale Customer
description: Retrieves details of a provisioned Wholesale customer on Cisco Webex.
tags:
- Wholesale Provisioning
parameters:
- name: customerId
in: path
description: A unique identifier for the customer in question.
required: true
example: Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4
schema:
type: string
- name: onBehalfOfSubPartnerOrgId
in: query
description: The encoded organization ID for the sub partner.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wZTE4MmUxNS05ZmNhLTQ0NzgtYmEzOC1jNGFiMmUyN2FlZDA=
schema:
type: string
- name: includePackageLicenseInfo
in: query
description: If specified as true, a list of licenseIds will be returned for all provisioned packages
example: 'true'
schema:
type: boolean
put:
responses:
'202':
description: Accepted
headers:
Location:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceURL'
example:
url: https://webexapis.com/v1/wholesale/customers/Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4
'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 Wholesale Customer
operationId: Update a Wholesale Customer
description: "Updates certain details of a provisioned Wholesale customer for Cisco Webex services.\n\nThe Wholesale customer provisioning is asynchronous and thus a background task is created when this endpoint is invoked.\n\n**packages Note:**\n\n* `cisco_calling_plan` is dependent on: `common_area_calling`, `webex_calling`, `webex_suite`, `webex_voice`, `cx_essentials`, `webex_calling_standard`\n\n* `attendant_console` is dependent on: `webex_calling`, `webex_suite`, `cx_essentials`\n\n<div>\n <Callout type='info'>After successful invocation of this endpoint a URL will be returned in the `Location` header, which will point to the [Get a Wholesale Customer](/docs/api/v1/wholesale-provisioning/get-a-wholesale-customer) endpoint for this customer.</Callout>\n</div>"
tags:
- Wholesale Provisioning
parameters:
- name: customerId
in: path
description: A unique identifier for the customer to be updated.
required: true
example: Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4
schema:
type: string
- name: onBehalfOfSubPartnerOrgId
in: query
description: The encoded organization ID for the sub partner.
example: Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8wZTE4MmUxNS05ZmNhLTQ0NzgtYmEzOC1jN
# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webex/refs/heads/main/openapi/webex-wholesale-provisioning-api-openapi.yml