The Webex for Wholesale Provisioning API is for the Service Providers (SPs) who sign up for Cisco Webex for Wholesale. The API enables those SPs to provision, update, and remove wholesale customer/subscribers.

For more information about Webex for Wholesale, please see the Webex for Wholesale Route-to-Market Solution Guide.

Provisioning Precheck APIs

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

• Precheck a Wholesale Customer Provisioning
• Precheck a Wholesale Subscriber Provisioning

Provisioning APIs

The Webex for Wholesale Provisioning API is for the Service Providers (SPs) who sign up for Cisco Webex for Wholesale. The API enables those SPs to provision, update, and remove wholesale customer/subscribers. Error codes used by the Provisioning API are defined in the API Error Codes section.

Wholesale Customer Provisioning APIs

• View Wholesale Customers
• Provision a Wholesale Customer
• View a Wholesale Customer
• Update a Wholesale Customer
• Delete a Wholesale Customer

Wholesale Subscriber Provisioning APIs

• View Wholesale Subscribers
• Provision a Wholesale Subscriber
• View a Wholesale Subscriber
• Update a Wholesale Subscriber
• Delete a Wholesale Subscriber

Billing Reports APIs

The Wholesale Billing Reports Public APIs are a set of APIs that are targeted at Service Providers who sign up to the Webex for Wholesale solution. These APIs provides partner, customer and user breakdown reports to the Service Providers or Partners. Service Providers can use these reports to reconcile their monthly invoice.

If partner has sub-partner relationships created, then partner can use an additional parameter subPartnerOrgId in Create a Wholesale Billing Report to generate individual sub-partner reports to reconcile their monthly invoice.

• List Wholesale Billing Reports
• Create a Wholesale Billing Report
• Get a Wholesale Billing Report
• Delete a Wholesale 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 Wholesale APIs:

anchorAsynchronous Provisioning Model

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

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

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

anchorUsing the Provisioning Precheck API

The Webex for Wholesale Provisioning Precheck APIs are for Partner Sales team to determine the likely success of a customer or subscriber provisioning who sign up for Cisco Webex for Wholesale. The Precheck APIs supports two variants of Wholesale Customer Provisioning Precheck Requests and three variants of Wholesale Subscriber Provisioning Precheck Requests.

Wholesale Customer Provisioning Precheck API

Sample partial provisioning request with customerInfo.primaryEmail and address parameters:

{        
    "customerInfo" : {           
        "primaryEmail" : "john.anderson@acme.com"     
    },      
    "address": {
        "addressLine1": "771 Alder Drive",
        "addressLine2": "Cisco Site 5",
        "city": "Milpitas",
        "stateOrProvince": "CA",
        "zipOrPostalCode": "95035",
        "country": "US"
    }
}

Sample full provisioning request with provisioningId, packages, orgId, externalId, address, customerInfo and provisioningParameters parameters:

{
    "provisioningId": "Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4",
    "packages": [
        "common_area_calling",
        "webex_calling",
        "webex_meetings",
        "webex_suite"
    ],
    "orgId": "Y2lzY29zcGFyazovL3VzL09SRtR",
    "externalId": "c1677a16-557a-…",
    "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"
    },
    "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"
        }
    }
}

Wholesale Subscriber Provisioning Precheck API

Sample partial provisioning request with customerInfo.primaryEmail and email parameters:

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

Sample partial provisioning request with customerId and email parameters:

{
    "customerId": "Y2lzY29zcGFyazovL3VzL09vL3VzL0VOVEVSUFJJU0UvNTJSRtR"
    "email": "alice.anderson@acme.com"
}

Sample full provisioning request with customerId, provisioningId, email, package, provisioningParameters parameters:

{
  "customerId" : "Y2lzY29zcGFyazovL3VzL09vL3VzL0VOVEVSUFJJU0UvNTJSRtR",
  “provisioningId” : “Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4”,
  “email” : “john.anderson@acme.com”,
  "package" : "webex_suite",
  “provisioningParameters” : {
      "firstName" : "John",
      "lastName" : "Anderson",
      "primaryPhoneNumber" : "+ 1-240-555-1212",
      "extension" : "51212",
      "locationId" : "Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtIyMmMtNDY3YzUxNTkxOTA4"
  }
}

Sample full provisioning request with customerId, provisioningId, email, packages, provisioningParameters parameters:

{
  "customerId" : "Y2lzY29zcGFyazovL3VzL09vL3VzL0VOVEVSUFJJU0UvNTJSRtR",
  “provisioningId” : “Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4”,
  “email” : “john.anderson@acme.com”,
  "packages" : [
    "webex_suite",
  ],
  “provisioningParameters” : {
      "firstName" : "John",
      "lastName" : "Anderson",
      "primaryPhoneNumber" : "+ 1-240-555-1212",
      "extension" : "51212",
      "locationId" : "Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtIyMmMtNDY3YzUxNTkxOTA4"
  }
}

anchorWholesale Customer Identities

Wholesale Customers are referenced by different identities across the Webex platform. This section describes these identities and how integrations should transition between each identity depending on what Webex API you are integrating with.

Common Identity Organization ID

This is the identifier for the Customer on core internal services such as Common Identity. This is a Universal Unique Identifier (UUID). It is leveraged primarily by Identity specific APIs.

Webex Organization ID

This is the public identifier for all Webex Customer Organizations. It is used across the majority of Webex APIs.

It is a base64Url encoding of the following string: ciscospark://us/ORGANIZATION/{IdentityOrgUUID} where IdentityOrgUUID represents the Common Identity Organization ID.

A sample string to be encoded would look as follows: ciscospark//us/ORGANIZATION/03b4d559-9bfd-4066-a692-d1faefd0c599.

Wholesale Customer ID

Wholesale Customers can exist and be referenced via Wholesale APIs prior to full provisioning on the Webex Platform. As such a distinct identifier is needed to represent such customers. The Wholesale Customer ID represents that distinct identifier.

Once the customer is fully provisioned, their associated Webex Organization ID is returned in response to any Wholesale Customer API.

Transition between Wholesale Customer ID and Webex Organization ID

Wholesale Customer API payload includes both the Wholesale Customer ID and the Webex Organization ID.

See sample response from GET /wholesale/customers/{id} below, with Wholesale Customer ID id and Webex Organization ID orgId.

{
  "id": "Y2lzY29zcGFyazovL3VzL0VOVEVSUFJJU0UvNTJjZjU3NmQtNjBhOC00MDdhLWIyMmMtNDY3YzUxNTkxOTA4",
  "orgId": "Y2lzY29zcGFyay8vdXMvT1JHQU5JWkFUSU9OLzAzYjRkNTU5LTliZmQtNDA2Ni1hNjkyLWQxZmFlZmQwYzU5OQ==",
  "externalId": "c100012",
  "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"
      }]
  }
}

The orgId attribute is included as soon as the customer has been provisioned on the Webex platform. As required, this attribute can be used directly as customer org identifier to for the majority of other Webex APIs.

Additionally, the Wholesale Customer List/Search API allows searching by orgId: GET /wholesale/customers?orgId=xxxxx. This allows developers to discover the associated Wholesale Customer and transition back to Wholesale Customer ID as needed.

Transition between Webex Organization ID and Common Identity Organization ID

The Webex Organization ID is a base64-encoded string that includes the underlying Common Identity Organization ID. It is straightforward to transition between either format as required. Below are high level steps needed to perform the transitions.

Retrieve the Common Identity Organization ID from the Webex Organization ID:

1. Base64Url decode the Webex Organization ID. The decoded string will be formatted as follows: ciscospark://us/ORGANIZATION/{IdentityOrgUUID}.
2. Remove the ciscospark://us/ORGANIZATION/ prefix from the decoded string to leave the Common Identity Org UUID.

Generate a Webex Organization ID from Common Identity Organization ID:

1. Concatenate the ciscospark://us/ORGANIZATION/ prefix plus the Common Identity Organization ID into a single string: ciscospark//us/ORGANIZATION/{IdentityOrgUUID}.
2. Base64Url encode this string to generate the Webex Organization ID.

For example:

• Common Identity Organization ID: 03b4d559-9bfd-4066-a692-d1faefd0c599.
• Concatenated String: ciscospark://us/ORGANIZATION/03b4d559-9bfd-4066-a692-d1faefd0c599.
• Base64Url Encoded Webex Organization ID: Y2lzY29zcGFyay8vdXMvT1JHQU5JWkFUSU9OLzAzYjRkNTU5LTliZmQtNDA2Ni1hNjkyLWQxZmFlZmQwYzU5OQ==.

anchorManaging your customer organizations

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

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

Wholesale Customer Address Requirement

The billing address and calling address of the customer should be provided per the below guidelines:

Subscriber Deletion

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

• Soft Delete: The Webex for Wholesale Delete a Wholesale Subscriber removes all entitlements and capabilities from when the subscriber was first provisioned for Webex for Wholesale. 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.

• Delete all subscribers from the organization using the Delete a Person API.
• The removal of users may take some time depending on quantity of users.
• Delete all workspace from the organization.
• Soft Delete—The Webex for Wholesale Delete a wholesale customer removes entitlements and Webex calling capabilities from the organization from when the customer was first provisioned for Webex for Wholesale. But, the customer remains provisioned within their Partner organization on Cisco Webex.
• Hard Delete—If you wish to remove the Organization completely from Cisco Webex, perform a DELETE with the Delete Organization.
• Using Delete a wholesale customer API.
• 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 meeting timezone parameter in the organization provisioning request for packages webex_suite, webex_meetings, webex_calling.

If no timezone is specified in the provisioning request, 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 specified 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 Wholesale 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 Wholesale Get/Create/List API requests. These are complementary to the overall HTTP Status codes and provide additional clarity on the reason for the error.

Note: This list of error codes is shared between Webex for Wholesale and Webex for BroadWorks; it contains codes common to both offerings, as well as offering-specific codes.