8x8 Tenant Provisioning API

Overview

The 8x8 Tenant Provisioning API is composed of set of URIs to allow the tenants to download the information related to daily schedules/exceptions. Tenant has a choice of adding/modifying schedules at configuration manager user interface. This style of API makes it very easy to compose and send a query, which is always done using an HTTP GET request.

The Tenant schedule Reporting database contains data, related to all or individual schedule(s).

All API requests are authenticated using a token that is issued to a valid 8x8 tenant. Responses are sent in either XML or JSON format.

For security reasons, the Tenant provisioning API only accepts request using HTTPS, so that request headers and response data are encrypted.

For compatibility reasons,8x8 Tenant provisioning API does not give CSV type of response.

Testing Using A Browser

The Tenant provisioning API makes it easy to submit a query, for experimentation, testing or debugging purposes. From a web browser, simply enter the URL. You will be prompted to enter a username and password. Enter your tenant name as the username, and your authentication token as the password. Then, the query result will be displayed in your browser. For example,

https://vcc-na4.8x8.com/api/provisioning/schedules

will return the all schedules information. Response will give all schedules; each schedule will have weekday information along with exception(s).

Revise your query URL based on the login URL of your Tenant. (Refer to the Platform URL Guide to retrieve your login URL)

<?xml version='1.0'  encoding='UTF-8' ?>
<schedules>
    <schedule>
        <id>122</id>
        <name>myschedule</name>
        <time-zone>PST8DT</time-zone>
        <week-days>
           <week-day>
              <day>0</day>
              <properties>
                 <status>-1</status>
                 <start-time>08:00</start-time>
                 <end-time>09:00</end-time>
              </properties>
           </week-day>            ... 

    <schedule>
      ... 
</schedules>

Some other examples for finding schedule information

  https://vcc-na4.8x8.com/api/provisioning/schedulesbyname/{schedule-name}

will return specific schedule with name matching {schedule-name}, provided in request. To find the id of a specific schedule; you can query schedule by name and get the schedule id from response.

  https://vcc-na4.8x8.com/api/provisioning/schedules/{schedule-id}

will return specific schedule with id matching {schedule-id}, provided in request.

Examples for finding schedule status information

  https://vcc-na4.8x8.com/api/provisioning/schedules/{schedule-id}/status

will return specific schedule status with id matching {schedule-id}, provided in request. To find the id of a specific schedule; you can query schedule by name and get the schedule id from response.

Schedule status will be calculated at current time in time zone of specific schedule. If schedule does not have a time zone; status will be calculated at current time in time zone of tenant.

  https://vcc-na4.8x8.com/api/provisioning/schedules/{schedule-id}/status?utctime=1360821949898

will return specific schedule status with id matching {schedule-id}, provided in request.

Schedule status will be calculated at user provided time in time zone of specific schedule. If schedule does not have a time zone; status will be calculated at user provided time in time zone of tenant.

  https://vcc-na4.8x8.com/api/provisioning/schedules/{schedule-id}/status?offset=600

Current schedule status will be calculated at current time with additional offset seconds in time zone of specific schedule. If schedule does not have a time zone; status will be calculated in time zone of tenant.

  https://vcc-na4.8x8.com/api/provisioning/schedules/{schedule-id}/status?utctime=1360821949898offset=600

Current schedule status will be calculated at user given time with additional offset seconds in time zone of specific schedule. If schedule does not have a time zone; status will be calculated in time zone of tenant.

  https://vcc-na4.8x8.com/api/provisioning/schedules/{schedule-id}/nextstatus

Next schedule status along with current schedule status will be calculated at current time in time zone of specific schedule. If schedule does not have a time zone; status will be calculated at current time in time zone of tenant.

  https://vcc-na4.8x8.com/api/provisioning/schedules/{schedule-id}/nextstatus?utctime=1360821949898

Next schedule status along with current schedule status will be calculated at user provided time in time zone of specific schedule. If schedule does not have a time zone; status will be calculated at user provided time in time zone of tenant.

Testing Using curl

In a Linux environment, the curl utility will submit an HTTP request, and allow you to view the result.

  curl -u acme:ac12343934687a839cf https://vcc.na4.8x8.com/api/provisioning/schedules/{schedule-id}  -o {filename}

will return either a XML or JSON output as a file for the schedule. The -u argument identifies the username and password; use your tenant name as the username, and your authentication token as the password.

The -o argument will take the file name as input from user. This will be name of file where content will be saved.

Authentication

In order to make an API request, you must first obtain an authentication token that has been issued for your tenant. This token combines username and password into a single long string. To get your token, log into the Configuration Manager, select "Integration", and click the "API Token" tab. Next, click the "New Token" button next to "Data Request Token". This generates a new private token for your tenant. You will use this token in all requests to the Recordings API. You may generate a new token at any time.

Meaning of status codes

0 OPEN Status is in open state.
-1 CLOSED Status is in close state.
Choice #1 CHOICE Status is in choice states.
Choice #2 CHOICE Status is in choice states.
Choice #3 CHOICE Status is in choice states.
Choice #4 CHOICE Status is in choice states.
Choice #5 CHOICE Status is in choice states.
Choice #6 CHOICE Status is in choice states.

API response codes

200 OK Request was successful.
400 Bad request The syntax of the request was wrong.
401 Unauthorized The request was not allowed, usually due to incorrect authentication.
404 Not found The requested resource was not found.
500 Internal error The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Server busy The server is currently unable to handle the request due to temporary overloading. This is to prevent denial of service. Another reason of this error is to allow only single request per customer at a time. Same error is also given if more than 10 customers hitting the CCM API at the same time.