The Virtual Contact Center recordings API is composed of a set of URIs that identify and request recordings data from the Virtual Contact Center database. This style of API makes it very easy to compose and send a query, which is always done using an HTTP GET request.

The Recordings database contains data about call recordings; the recording file name, phone number called, customer ANI, etc.

All API requests are authenticated using a token that is issued to a valid Virtual Contact Center tenant. Responses are sent in either XML or CSV format.

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

Testing Using A Browser

The Recordings 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 promted 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,


will return information about all recording files, in XML format.

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

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 http://vcc-na4.8x8.com/api/recordings/files.csv

will return a list of recording files, in CSV format. The -u argument identifies the username and password; use your tenant name as the username, and your authentication token as the password.


List files


Returns a list of all files.

<?xml version='1.0'  encoding='UTF-8' ?>




    <outDialCode />
    <wrapUpCode />

To get a recording file for a completed call, use the parameters supplied in the post-call screen pop:


The return data of each recording could be either of the following types:

  • Outbound
  • Inbound
  • Direct Agent Access

To interpret the type of the recording, use the value provided in the channel field. For different type of call, the value in the phone number field represents different attribute of the call.

Call Type Channel Phone Number Queue ID Queue Name
Inbound Channel of the call dialing to Caller Id of the caller Queue Id of the queue Queue Name of the queue
Outbound #virtual_outbound# Dial out number QUEUE_OUTBOUND QUEUE_OUTBOUND
Direct Agent Access #virtual_daa# Caller Id of the caller QUEUE_DIRECT_AGENT_ACCESS QUEUE_DIRECT_AGENT_ACCESS


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


Date formats in queries adhere to the ISO 8601 standard. The {date range} argument can take one of two forms. To specify records from a given day, specify the date, with an optional time zone parameter:


Note that if no time is given, a day begins at midnight (00:00:00), and if no time zone is specified, the time defaults to the tenant time zone. A list of valid time zones can be found here (TZ column):List_of_valid_time_zones To specify a date range, separate the dates with a comma (",")


You can include times in date ranges as well, separated with a space ("%20″ in the URI):

  http://vcc-na4.8x8.com/api/recordings/files?d=2007-08-05 13:15Z,2007-08-07 14:30Z

"Z" is the time zone designator, signifying that the time is in UTC(Coordinated Universal Time). Dates may also be formatted as a single string, with no separators, and a capital "T" separating date and time:


There are several date constants available to represent relative dates:


– the current date, at the start of the day (midnight)


– yesterday, at the start of the day (midnight)


– seven days ago, at the start of the day (midnight)

To see yesterday's recordings:


Dates in responses also adhere to the ISO 8601 standard. They take the form:


where "-08:00″ represents the offset with the UTC timezone (Coordinated Universal Time). A negative offset typically represents timezones west UTC.



should be used to find voice recordings that started within 5 seconds (plus or minus) of a given date(/time). If no time is provided, the API will default to midnight (+-5 seconds).


should be used to find voice recordings that ended within 5 seconds (plus or minus) of a given date(/time). If no time is provided, the API will default to midnight (+-5 seconds).




cannot be used together to emulate a date range. You should use a date range directly with the


variable. If you still try to use both variables in a same query, only


will be used.


Requests that would return a large number of records will respond with 50 records per request. You can iterate through these response sets by setting the {offset} argument. In this example, we are asking for agent interactions, starting with the 101st record.


Query Variables

Queries that return interaction data may be further constrained by supplying query variables. These take the form of field=value where field is any field normally returned by the query(such as agentID, phoneNumber, channel, …).There are two exceptions worth mentioning:


– start-date should be used instead of startDate


– finish-date is not one of the output fields

Query variables are case-sensitive. It is start-date and not Start-Date.

For example, to return only the set of recordings for a particular channel:



Each resource may be returned in either XML or CSV format. To specify, add ".xml" or ".csv" to the URL:


The default is XML.

Response Codes

200 OK Request was successful
400 Bad request The syntax of the request was wrong
403 Forbidden 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