Test Environment. You are currently using the Webex for Developers test environment. Apps created here will not be available for use with Webex Teams. Please visit Webex for Developers to manage your apps.
Overview
Platform Introduction Bots Integrations Widgets Guest Issuer
REST API
Getting Started Basics
Guides
Admin API Buttons and Cards Calling Compliance Devices Hybrid Services Meetings REST API Webhooks Webex for BroadWorks
API Reference
Admin Audit Events Attachment Actions BroadWorks Enterprises BroadWorks Subscribers Call Controls Device Configurations Devices Events Hybrid Clusters Hybrid Connectors Licenses Locations Meeting Invitees Meeting Participants Meeting Preferences Meeting Qualities Meetings Memberships Messages Organizations People Places Recordings Report Templates Reports Resource Group Memberships Resource Groups Roles Rooms Team Memberships Teams Webhooks Workspaces xAPI
API Changelog
SDKs
iOS Android Browser Node.js Java Community

Webex for BroadWorks

Cisco Webex for BroadWorks is an offer that integrates BroadWorks Calling in Webex. Learn how to use the Webex for BroadWorks Provisioning APIs.

anchorWhat's possible with Webex for BroadWorks Provisioning APIs
anchor

The Webex for BroadWorks Provisioning API is for BroadWorks Service Providers (SPs) who sign up for Cisco Webex for BroadWorks. The API enables those SPs to provision, update, and remove Cisco Webex services for their subscribers.

anchorUsing the Provisioning API
anchor

The Webex for BroadWorks Provisioning API is for BroadWorks Service Providers (SPs) who sign up for Cisco Webex for BroadWorks. The API enables those SPs to provision, update, and remove Cisco Webex services for their subscribers.

anchorMethods and Content Types
anchor

The Webex for BroadWorks Provisioning API is RESTful. In REST, a base URL represents each resource. You use the HTTP methods GET, POST, PUT, and DELETE to request data and perform actions on those resources.

For methods that accept request parameters, the platform accepts only application/json content types.

anchorAPI Error Codes
anchor

These APIs return standard HTTP status codes for request responses. For more information on standard HTTP status codes, please see Webex REST API Basics.

The following error codes may appear in API Error responses, or included in responses to subscriber Get/Search/List API requests.

In API Error responses, these are complementary to the overall HTTP Status codes and provide additional clarity on the reason for the error.

In Subscriber responses they indicate any errors that occurred during asynchronous or background subscriber provisioning.

Error CodeDetailHTTP Status CodePossible in Subscriber response?
1001Null Parameter
A mandatory parameter has not been specified in the API request. The description and fieldName attributes provide further detail on the missing parameter.		400No
1002Invalid Parameter Size
A parameter in the API request is outside the bounds of expected size. The description and fieldName attributes provide further detail on the invalid parameter and the size restrictions that apply.		400No
1003Invalid Parameter Format
A parameter in the API request is not correctly formatted. The description and fieldName attributes provide further detail on the invalid parameter.
Common Causes:
  • email or userId parameter in Provision Subscriber request are not in valid email address format. The specification of a valid email can be found in RFC 2822.
  • primaryPhoneNumber parameter in Provision/Update Subscriber is not a valid BroadWorks phone number.
  • language parameter in Provision Subscriber request is not in ISO 639-1 format.
  • The package type specified in the Provision/Update Subscriber request is not one of softphone, basic, standard or premium.
400No
1004Invalid Query Parameter
The query parameter specified in Subscriber or Enterprise Search/List API request is invalid.
Common Causes:
  • The email query parameter is not in valid email address format. The specification of a valid email can be found in RFC 2822.
  • The personId query parameter is not valid.
400No
2001Subscriber Not Found
The subscriberId specified in an API Request to Get, Update, Delete a Subscriber could not be found.
Common Causes:
  • The subscriber in question was previously deleted.
  • The subscriberId specified is invalid.
404No
2002Subscriber pre-exists in another Cisco Webex organization
Webex for BroadWorks has previously mapped the subscriber's Broadworks enterprise to a new or existing Webex organization. However, the email address associated with this subscriber has been found in a different Webex organization. Cisco cannot automatically move this subscriber to the desired organization and so provisioning fails.
Common Causes:
  • The subscriber in question already has free or paid Webex services using this email address in another Webex organization.
  • The email address supplied is incorrect

Possible Solutions:
  1. Validate that the supplied email is correct.
  2. Confirm with the customer/subscriber that their Broadworks enterprise has been mapped to the correct Webex organization.
  3. Work with the customer/subscriber to close their existing Cisco Webex account or change the email address associated with that account.
  4. Supply an alternate email address for the subscriber.
4001Yes1
2003Subscriber Update Not Allowed
The subscriber update operation is not allowed because of the current provisioning status of the subscriber.
Common Causes:
  • Subscriber Provisioning/Update is currently in progress - subscriber status is provisioning or updating.
  • Subscriber provisioning had previously failed and the subscriber status is error.

Possible Solutions:
  1. Check current Subscriber Status.
  2. If Subscriber Provisioning is in progress, wait until status transitions to a final status of (provisioned or error) before proceeding with appropriate next step.
  3. If subscriber is in error status, you will need to send a new Provision Subscriber API request instead to re-provision the subscriber.
403No
2004Webex Organization Mismatch
The subscriber Update API request failed as the subscriber is unexpectedly associated with a different Webex Organization to the one in which they were originally provisioned.
Common Causes:
Another Organization has claimed the subscriber, triggering an automated move of the subscriber into a new Webex organization.
Possible Solutions:
If the subscriber has been claimed by another organization, then they can no longer obtain Webex for BroadWorks services as part of their existing BroadWorks enterprise.
  1. Perform a Delete Subscriber operation to clean up Webex for BroadWorks provisioning for the subscriber.
  2. Then work with the customer/subscriber in question to determine next steps.
409No
2005Package Type Not Supported
The package type specified in the Provision/Update Subscriber request is not supported.
Note: This only applies where the associated Customer Template is configured with Automatically Create New Organizations in Control Hub disabled.
Cause:
The package type specified is syntactically valid (one of softphone, basic, standard or premium), however that specific package type is not currently supported in this mode of operation.
Solution:
Perform the API request again with a supported package type.		400No
2006Insufficient Privileges
You do not have sufficient privileges to perform update/delete operations on this subscriber.
Cause:
The Partner Organization associated with the access token specified in the API request does not match the Partner Organization with which the subscriber was originally provisioned.
Solution:
Check to ensure the application making this API request has been authorized by a full administrator within the correct Partner Organization.		403No
2007Broadworks Enterprise not mapped to Webex Organization
The Provision Subscriber API request could not be processed as the associated Broadworks Enterprise is not mapped to a pre-existing Webex Organization.
Note: This only applies where the associated Customer Template is configured with Automatically Create New Organizations in Control Hub disabled.
Causes:
  • The target Webex Organization has not been created and pre-existing in Control Hub.
  • The target Webex Organization has not been manually mapped to their Broadworks Enterprise by the Partner Administrator.
Solution:
  1. If Webex organization does not exist, you must place an order for the customer via Cisco Commerce for agreed Product SKUs to trigger the organization creation.
  2. On Control Hub, map the customer organization to their Broadworks enterprise as required.
404No
2008Subscriber Provisioning Request Already Being Processed
A Subscriber Provision or Update API request for the same subscriber is already in being processed by Cisco Webex.
Cause:
Two Subscriber Provision or Update API requests have been sent concurrently for the same subscriber. Cisco Webex will reject any subsequent Provision/Update requests until it has responded to the initial request.
Solution:
Wait until you have received a response to the initial API request before performing another operation for the same subscriber.		400No
2009BroadWorks UserId Already Provisioned
A subscriber with the same BroadWorks UserId and from the same BroadWorks Cluster has already been provisioned.
Cause:
The request has been rejected as BroadWorks UserID is unique to a BroadWorks Cluster and a subscriber with this userID from this BroadWorks Cluster has already been provisioned.
Possible Solutions:
  1. Validate the userId & provisioningId supplied in this request are correct. The provisioningId identifies the Customer Template and associated BroadWorks cluster.
  2. If necessary, remove the existing subscriber with the same BroadWorks UserId.
409Yes1
2010Email Address Already In Use
The email specified in the request to provision this subscriber is already being used by another provisioned BroadWorks subscriber
Cause:
  • A subscriber has previously been provisioned using the same email address.
  • Note that this existing subscriber may have been provisioned by a different BroadWorks Service Provider
Possible Solutions:
  1. Validate the correct email address has been specified in this attempt to provision a new subscriber.
  2. If so, use the subscriber search API to query your list of subscribers using the email address as a query parameter.
    • If you find a match, you can determine whether or not the existing subscriber has been provisioned incorrectly.
    • If no result is found, then the subscriber associated with the email address is likely managed by an alternate BroadWorks Service Provider; You will need to work with the subscriber and customer in question to determine next steps.
409Yes1
2011No Organization Administrator
The Subscriber Provision/Update operation could not be processed as the target customer organization on Cisco Webex does not have an administrator with Full Administrator role.
Cause:
  • All Customer Organizations on Cisco Webex should have an administrator with Full Administrator role. However, that was not the case for the customer organization associated with this BroadWorks subscriber.
  • The administrator may be been deleted prior to this operation being performed.
Possible Solutions:
  1. Assign the Full Administrator role to an existing user in this organization before trying again.
  2. If there are no users in the organization, manually create a new user via Control Hub and apply the Full Administrator role.
409Yes1
2012Subscriber is already entitled to Webex Calling
The subscriber cannot be provisioned for Webex for BroadWorks because they are already entitled to Webex Calling.
Possible Solutions:
  1. Remove the conflicting entitlement before provisioning the affected subscriber (the subscriber will use BroadWorks calling, instead of their previous option).
  2. Provision the subscriber with a different email address (the subscriber will have two distinct Webex user IDs).
409No
2013Unknown Provisioning ID
The supplied provisioning ID does not map to any of your configured Customer Templates
Cause:
The provisioning ID is an identifier for a specific Customer Template you have configured on Partner Hub. The Provisioning ID specified in this request does not map to any of your configured Customer Templates.
Possible Solutions:
  1. Check that your expected customer template exists in Partner Hub.
  2. Check that the provisioning ID displayed for that template matches what you used in the request.
404No
2014Provisioning ID Mismatch
The Provisioning ID specified in this request does not match the expected Provisioning ID for this subscriber’s enterprise.
Cause:
All subscribers within an enterprise must be provisioned with the same provisioning ID. The provisioning ID specified in this request does not match the provisioning ID used to provision previous subscribers in this enterprise.
Solution:
Ensure the Provisioning ID in your request matches the expected Provisioning ID for this enterprise.
  • You can determine this by performing a GET /enterprises request for the enterprise in question.
  • You may also determine this by performing a GET /subscribers request, supplying the BroadWorks userID of a previously provisioned subscriber from that enterprise.
  • Alternatively, you may manually determine this via Partner Hub & Control Hub by performing the following steps:
    1. As a Sales Full Administrator within your Partner organization, sign into Partner Hub and find the associated Customer in your Customers list.
    2. Click on the Customer and select "View Customer" to open the Customer's Control Hub view.
    3. From the Customer's Control Hub Overview page, click on "..." on the "Webex Services" card and select "Manage Services".
    4. On the "Services" page you should see a "BroadWorks Calling" card, where the Template name is listed.
    5. Return to Partner Hub and view the specified Customer Template to find the associated Provisioning ID.
400No
2015Enterprise ID Conflict
The spEnterpriseId specified in this request conflicts with a Service Provider or Enterprise already provisioned from this BroadWorks Cluster.
Common Causes:
This API enforces uniqueness validation for any BroadWorks Enterprise ID or Service Provider ID values specified in the spEnterpriseId parameter. This is to align with more general BroadWorks uniqueness constraints:
  • On the BroadWorks cluster, there cannot be a Service Provider ID and Enterprise ID with the same value.
  • Therefore Webex will reject a Subscriber Provisioning request with this error code if:
    • An Enterprise ID specified in spEnterpriseId matches a Service Provider ID included in a previous request from that BroadWorks Cluster.
    • A Service Provider ID specified in spEnterpriseId matches a Enterprise ID included in a previous request from that Cluster.
If you encounter this error, it is an indication of issue with how you have generated the spEnterpriseId in (this or previous) Subscriber Provision requests for this BroadWorks cluster:
  1. You may have incorrectly included the subscriber's Group ID where the enterprise is configured as an Enterprise on BroadWorks.
  2. You may have incorrectly omitted the subscriber's Group ID where the enterprise is configured as an Group under a Service Provider on BroadWorks.
See the Enterprise ID section below for more information on how to generate spEnterpriseId parameter.
The key point is that even though you encounter the error on this request, the root cause be be a misconfigured spEnterpriseId on a previous request from this cluster.
Possible Solutions:
Perform the following steps to identify and fix the issue:
  1. Ensure you have specified the correct spEnterpriseId in this request per the Enterprise ID rules defined below.
  2. If the spEnterpriseId in this request is correct, then it is likely that previous subscriber provisioning request(s) specified an invalid spEnterpriseId.
    • You will need to review all provisioned/pending subscribers and their associated spEnterpriseId.
    • If a misconfigured spEnterpriseId is found then a series of steps are required to clean up the subscribers/enterprises configured in error:
      1. Deprovision all subscribers with misconfigured spEnterpriseId using DELETE /broadworks/subscribers/{subscriberId}.
      2. For each misconfigured spEnterpriseId, use the Enterprise Search API (GET /broadworks/enterprises) to retrieve any associated orgId.
      3. For each associated orgId, you have two options to clean up those organizations:
        1. Permanently delete the organization from Webex using DELETE /organizations/{orgId} API.
          • This requires you to first fully delete all users from the organization using the DELETE /people/{personId}.
          • This option should only be used if this organization was newly created as part of provisioning the subscriber with an incorrect spEnterpriseId.
          • For organizations that pre-existed on Webex, proceed to the alternate option below.
        2. Manually clear any mapping between the organization and the misconfigured spEnterpriseId from Control Hub using the following steps.
          • As a Sales Full Administrator within your Partner organization, sign into Partner Hub and find the associated Customer in your Customers list.
          • Click on the Customer and select "View Customer" to open the Customer's Control Hub view.
          • From the Customer's Control Hub Overview page, click on "..." on the "Webex Services" card and select "Manage Services".
          • On the "Services" page you should see a "BroadWorks Calling" card.
          • Click on the "Clear Configuration" button (This button only appears once all subscribers have been deprovisioned above).
Once these deprovisioning steps have been completed, all subscribers can now be reprovisioned using the correct spEnterpriseId.
If you cannot identify the cause of the conflict, please raise a Support ticket.		409No
2016Customer and Partner Org Region Mismatch
Causes:
Partner is trying to onboard a pre existing user from a different region.
Solution:
Ensure the user and partner are in the same region (for example: a user in the EU cannot be provisioned into US region or vice versa).		409No
3001Missing Required Licenses
The target Webex Organization does not have the required licenses ordered to allow this subscriber to be provisioned or updated with this package.
Note: This only applies where the associated Customer Template is configured with Automatically Create New Organizations in Control Hub disabled.
Causes:
  • Subscription(s) have not been established via Cisco Commerce to ensure the target Webex Organization has the necessary licenses in place.
  • Pre-existing Subscription(s) were established with the appropriate licenses for the Organization - but have since been suspended or cancelled.
Solution:
  1. Check status of any existing active subscriptions for the Organization from Control Hub.
  2. Establish new subscription(s) as required via Cisco Commerce to meet the licensing requirements - using agreed Product SKUs.
400No
4001Invalid Service Provider Email Address
The Service Provider Email Address originally configured in the Customer Template is no longer owned by an existing administrator within the Partner Organization.
Possible Causes:
  • The Original Service Provider Admin in the Partner Organization has since lost administrative privileges and is no longer an Admin.
  • The Service Provider Admin in question has changed their email address on Cisco Webex.
  • The Service Provider Admin in question has left or been deleted from the organization.
Solution:
Reconfigure the Customer Template on Control Hub with a new Service Provider email address.		Not Applicable2Yes
5001Internal Server Error
An unexpected error has occurred while processing the API request or during subsequent subscriber provisioning in the background. The description will provide additional details.
Solution:
Please raise a Support Ticket if the issue persists.		500Yes

Notes:

  1. Where Trusted Email addresses are being used, Error Code 2002 will be returned early in a 400 Bad Request response. For Untrusted Email or Self Activation based Customer Templates however, this check happens in the during background subscriber provisioning once a valid email address has been obtained. In that case, the provisioning attempt will fail and the subscriber representation will show Error Code 2002 as the reason for the failure.
  2. Error Code 4001 is only generated during asynchronous subscriber provisioning. As such, It will not be returned during API request handling and never be associated with an HTTP status code.
anchorBackward Compatibility and Versioning
anchor

Our APIs change over time as we build new functionality. However, we are aware that API users need their applications to continue working as expected when the APIs change.

For that reason, our APIs follow a backward-compatibility and versioning strategy as follows:

When we add new API endpoints, new query parameters to existing endpoints, new optional fields in request bodies, and new data in response bodies, we do not necessarily create a new version of the API. Those kinds of changes should not affect the compatibility of the API with existing calls to the API, and we expect your applications to be robust to those kinds of improvements to the API.

When we need to change the API outside of the scope described above, we create a new version of the API. For example, if we added a new required field to the request body, your application would not be aware of that requirement. If we changed the original version, your application would experience an unexpected failure.

When we create a new version of an API, we continue to support the original version of the API for a reasonable period of time. This enables your application to continue working while you adapt it to using the new version of the API.

We have an API framework team that works across the Cisco collaboration portfolio to approve any API changes before they are rolled out, ensuring that our backwards compatibility requirements are met and avoiding unpleasant surprises for our developer community.

anchorAuthentication
anchor

When registering your application as an Integration, enable the following scopes to access all Webex for BroadWorks Provisioning APIs:

Scope
Usage
spark-admin:broadworks_enterprises_read
Read or List BroadWorks Enterprise, provisioned as part of Webex for BroadWorks Solution.
spark-admin:broadworks_subscribers_read
Read or List BroadWorks Subscribers, provisioned as part of Webex for BroadWorks Solution.
spark-admin:broadworks_subscribers_write
Provision, Update or Remove a BroadWorks Subscriber as part of Webex for BroadWorks Solution.

If a Refresh Token expires, then the application can no longer generate the necessary access tokens for this API. A Service Provider admin needs to reauthorize the application to gain access to the APIs again. So, it's important that your application maintains an active Refresh Token.

Handling 403s when creating and deleting users and organizations

If you attempt to delete an object that you have created less than 24 hours ago via the /people or /organizations API endpoints, the DELETE may return a 403.

The recommendation in this scenario is to refresh the access token on receiving the 403 error response and retry the DELETE operation.

anchorAsynchronous Provisioning Model
anchor

Subscriber provisioning on Cisco Webex can take considerable time. Therefore, the Webex for BroadWorks provisioning APIs don’t wait or block until subscriber is fully provisioned. Instead, the API responds quickly while initiating subscriber provisioning as a background task.

You can design your application to query the subscriber later to determine its provisioning status. All representations of the subscriber through the APIs include a “status” attribute to indicate the subscriber’s provisioning status:

  • On successful completion, the subscriber status changes to “provisioned”.
  • If any error occurs during provisioning, the user status transitions to “error”. The subscriber representation through these APIs also includes specific error codes and the reasons behind the provisioning error.
anchorEnterprise ID
anchor

When provisioning a BroadWorks subscriber for Webex for BroadWorks, one of the required parameters is the spEnterpriseId. This parameter defines a unique identifier for subscriber's enterprise on BroadWorks.

This table defines how to supply the spEnterpriseId value for your model:

Enterprise Configuration ModelLogicDescriptionExample enterpriseID
Enterprise ModelIndividual customers are configured as Enterprises on BroadWorks.The spEnterpriseId must be an exact match of the Enterprise ID on BroadWorks:
"<Enterprise ID>"		“Acme”
Service Provider ModelIndividual customers are configured as Groups under a Service Provider on BroadWorks.The spEnterpriseId must be a concatenation of Service Provider ID and Group ID on BroadWorks, separated by a plus, as follows:
"<Service Provider ID>" + "+" + "<Group ID>"		“SP1+Acme"
anchorSubscriber Deletion
anchor

Webex for APIs supports both a soft and hard deletion model for subscribers.

  • Soft Delete—The Webex for BroadWorks Subscriber Delete API removes all entitlements and capabilities from when the subscriber was first provisioned for Webex for BroadWorks. But, the subscriber remains provisioned within their Customer organization on Cisco Webex. The subscriber may continue to use Webex in line with their remaining capabilities.
  • Hard Delete—If you wish to remove the subscriber completely from Cisco Webex, perform a DELETE with the People APIs.

For more information about Webex for BroadWorks, please see the Webex for BroadWorks Solution Guide.

anchorWebex Meetings Site Timezone
anchor

If a specific Webex Meetings site timezone is required, please specify the timezone parameter in the provisioning request for:

  • the first subscriber provisioned for Standard package in the organization.
  • the first subscriber provisioned for Premium package in the organization.

The first subscriber for each package dictates the timezone for the Webex Meetings site for that package.

If no timezone is specified in the provisioning request for the first user of each package, the Webex Meetings site timezone for that package is set to a regional default based on the subscribers' organization.