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
anchorThe 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
anchorThe 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
anchorThe 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
anchorThese 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 Code | Detail | HTTP Status Code | Possible in Subscriber response? |
---|---|---|---|
1001 | Null Parameter A mandatory parameter has not been specified in the API request. The description and fieldName attributes provide further detail on the missing parameter. | 400 | No |
1002 | Invalid 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. | 400 | No |
1003 | Invalid 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:
| 400 | No |
1004 | Invalid Query Parameter The query parameter specified in Subscriber or Enterprise Search/List API request is invalid. Common Causes:
| 400 | No |
2001 | Subscriber Not Found The subscriberId specified in an API Request to Get, Update, Delete a Subscriber could not be found.Common Causes:
| 404 | No |
2002 | Subscriber 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:
Possible Solutions:
| 4001 | Yes1 |
2003 | Subscriber Update Not Allowed The subscriber update operation is not allowed because of the current provisioning status of the subscriber. Common Causes:
Possible Solutions:
| 403 | No |
2004 | Webex 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.
| 409 | No |
2005 | Package 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. | 400 | No |
2006 | Insufficient 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. | 403 | No |
2007 | Broadworks 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:
| 404 | No |
2008 | Subscriber 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. | 400 | No |
2009 | BroadWorks 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:
| 409 | Yes1 |
2010 | Email Address Already In Use The email specified in the request to provision this subscriber is already being used by another provisioned BroadWorks subscriberCause:
| 409 | Yes1 |
2011 | No 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:
| 409 | Yes1 |
2012 | Subscriber 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:
| 409 | No |
2013 | Unknown 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:
| 404 | No |
2014 | Provisioning 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.
| 400 | No |
2015 | Enterprise 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:
spEnterpriseId in (this or previous) Subscriber Provision requests for this BroadWorks cluster:
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:
If you cannot identify the cause of the conflict, please raise a Support ticket. | 409 | No |
2016 | Customer 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). | 409 | No |
3001 | Missing 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:
| 400 | No |
4001 | Invalid 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:
Reconfigure the Customer Template on Control Hub with a new Service Provider email address. | Not Applicable2 | Yes |
5001 | Internal 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. | 500 | Yes |
Notes:
- 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.
- 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
anchorOur 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
anchorWhen registering your application as an Integration, enable the following scopes to access all Webex for BroadWorks Provisioning APIs:
spark-admin:broadworks_enterprises_read
spark-admin:broadworks_subscribers_read
spark-admin:broadworks_subscribers_write
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
anchorSubscriber 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
anchorWhen 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 Model | Logic | Description | Example enterpriseID |
---|---|---|---|
Enterprise Model | Individual 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 Model | Individual 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
anchorWebex 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
anchorIf 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.