The Webex for BroadWorks Provisioning APIs are 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.

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

Provisioning Precheck API

The Webex for BroadWorks Provisioning Precheck APIs are for Partner Sales team to determine the likely success of provisioning a subscriber. The info codes used by the Provisioning Precheck API are defined in the Provisioning Precheck API Info Codes section. For more information, see Using the Provisioning Precheck API.

• Precheck a BroadWorks Subscriber Provisioning

Provisioning APIs

The Webex for BroadWorks Provisioning APIs allow BroadWorks Service Providers (SPs) to provision, update, and remove Cisco Webex services for their subscribers. Error codes used by the Provisioning API are defined in the API Error Codes section.

• List BroadWorks Enterprises
• List BroadWorks Subscribers
• Provision a BroadWorks Subscriber
• Get a BroadWorks Subscriber
• Update a BroadWorks Subscriber
• Remove a BroadWorks Subscriber

Billing Reports APIs

The BroadWorks Billing Reports Public APIs are for Service Providers, who sign up for Cisco Webex for BroadWorks. These APIs helps Service Provider to generate monthly billing reports with user billing data. Service Provider can use these reports to reconcile their monthly invoice.

• List BroadWorks Billing Reports
• Create a BroadWorks Billing Report
• Get a BroadWorks Billing Report
• Delete a BroadWorks Billing Report

anchorAPI Backward Compatibility

The APIs defined in this guide change over time as functionality is added, deprecated, or changed. The strategy defined below is followed for any changes, to minimise disruption to users and applications that implement the API.

• Any significant change to an API is announced in the API Changelog. This applies for breaking changes as well as new functionality and backward compatible changes.
• New API endpoints, new query parameters on existing endpoints, new optional fields in request bodies, and new data in response bodies should not affect the compatibility of the API with existing calls to the API. Applications that use the API should be robust to these improvements.
• When the API needs to change outside of the scope described above, a Breaking Change will be announced in the API Changelog, with details of the change and an expected implementation date.

anchorAuthentication

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

anchorUsing the Provisioning Precheck API

The Webex for BroadWorks Provisioning Precheck APIs are for Partner Sales team to determine the likely success of provisioning a subscriber who sign up for Cisco Webex for BroadWorks. The Prerequisite for using this API is to have at least one BroadWorks Cluster configured against partner using Partner Hub. The Precheck APIs supports two variants of BroadWorks Provisioning Precheck Requests.

The info codes used by the Provisioning Precheck API are defined in the Provisioning Precheck API Info Codes section.

With the first user provisioning request, the provisioning bridge service creates the customer along with user onboarding. So, for the first user provisioning precheck, you must provide the same email in both the customerInfo.primaryEmail and email fields.

For pre-checking a new subscriber provisioning request in an existing customer organization, you must provide the user email from the customer org for the customerInfo.primaryEmail field, and the new subscriber email for the email field. In this case the two fields will have different email addresses.

Sample partial provisioning request, with customerInfo.primaryEmail (email address of a user in the customer org that you want to provision) and email (the subscriber's email address) parameters:

{        
    "customerInfo" : {           
        "primaryEmail" : "john.anderson@acme.com"     
    },      
    "email" : "alice.anderson@acme.com"  
}

Sample full provisioning request, with provisioningId, userId, spEnterpriseId, firstName, lastName, package, primaryPhoneNumber, email, language, timezone parameters:

{
    "provisioningId" : "Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4",
    "userId" : "example.com",
    "spEnterpriseId" : "Reseller1+acme",
    "firstName" : "John",
    "lastName" : "Andersen",
    "package" : "standard",
    "primaryPhoneNumber" : "+ 1-240-555-1212",
    "email" : "john.anderson@acme.com",
    "language" : "en",
    "timezone" : "America/Los_Angeles"
}

anchorAsynchronous Provisioning Model

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.

anchorManaging your customer organizations

Once your Webex for BroadWorks customer has been provisioned, you may then use the broader set of administrative APIs documented on this portal to manage services for your customer.

To support customer management, your application must be authorized by a user with Partner full administrator role, since such users are entitled to manage all customers under your Partner organization.

In order to manage service for a specific customer, you must first request management access by calling the GET Organizations Details API. This will grant you temporary access to the customer organization. You may then proceed to manage the customer via the desired API.

If you find any attempt to manage your customer via API set returns a 403 Forbidden response, it may be that your temporary access to the customer has expired. In such cases, call the GET Organizations Details API again to re-establish the desired access before proceeding with your management operation.

Note: You can expect a short delay (5 seconds) after the above request before management access to the customer organization is fully established.

anchorImplementation Notes

Enterprise ID

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 Group ID

When provisioning a BroadWorks subscriber for Webex for BroadWorks, one of the optional parameters is the spEnterpriseGroupId. This parameter defines the subscriber's enterprise group on BroadWorks. Considered only for Enterprise model and ignored for Service Provider model.

This table defines how to supply the spEnterpriseGroupId value for your Enterprise only model:

Subscriber Deletion

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.

Organization Deletion

Follow the instructions below in order to delete an organization that has BroadWorks Directory Synchronization related users:

• Delete all the subscribers from the organization using the Delete a Person API.
• Disable Directory Synchronization for the given organization via Partner Hub or via the public API
• Update Directory Sync for a BroadWorks Enterprise. This deletes all the users related to BroadWorks Directory Synchronization for this organization.
• To disable Directory Synchronization via Partner Hub:
  1. Click on "Settings".
  2. Select correct template.
  3. Click "Show list of customers sync status" button in side pane that is opened.
  4. Click the overflow button for the relevant organization.
  5. Click the "Disable sync" button.
• The removal of users may take some time depending on quantity of users.
• The organization now can be deleted using the Delete Organization API.

Organization Deletion with BroadWorks directory synchronization opt out enhancements

Follow the instructions below in order to delete an organization that has BroadWorks Directory Synchronization related users:

• Delete all the subscribers from the organization using the Delete a Person API.
• To disable BroadWorks Directory Synchronization via Public API set enableDirSync to false using Update BroadWorks Directory Synchronization API.
• To disable BroadWorks Directory Synchronization via Partner Hub:
  1. Click on "Settings".
  2. Select correct template.
  3. Click "Show list of customers sync status" button in side pane that is opened.
  4. Click the overflow button for the relevant organization.
  5. Click the "Disable sync" button.

• The removal of broadworks external users, org contacts and user contacts may take some time depending on quantity of users and partner admin can check GET BroadWorks Directory Synchronization API to know cleanup progress.
• After succesfull synchronization cleanup process, the organization now can be deleted using the Delete Organization API.

anchorWebex Meetings Site Timezone

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 default based on the country assigned to the organization. In the case that a new organization is being created, the timezone is based on the country selected in the Customer Template referenced in the provisioning request.

Here are the default cities/timezones for each country:

In the event of a problem with converting the country to a Webex Meetings Site Timezone, the following default per cluster value will be used:

anchorProvisioning Precheck API Info Codes

This table defines the Info codes used by the BroadWorks Provisioning Precheck APIs.

anchorAPI Error Codes

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. 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.

Notes:

1. Where Trusted Email addresses are being used, Error Code 2002 will be returned early in a 409 Conflict 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.
3. This list of error codes is shared between Webex for BroadWorks and Webex for Wholesale; it contains codes common to both offerings, as well as offering-specific codes.