LiveVox API Overview

LiveVox provides a set of APIs (Application Programming Interfaces) for integrating the functionality exposed by the LiveVox platform with third-party applications such as CRM systems and other systems of record used by clients to manage their accounts and calling lists. The APIs can build custom applications that make use of LiveVox functionality, such as custom agent desktops and reporting dashboards.

The API enables developers to access and manipulate the data and functionality of the LiveVox platform, such as creating and managing campaigns, monitoring and controlling call queues, and retrieving call and agent performance metrics, etc. The LiveVox APIs are independent of programming languages, so you can use them to develop applications in the language of your choice (Java, .NET, C, C++, PHP, etc.)

LiveVox provides its APIs through a REST interface only. For more information, see the REST APIs section on the same page.

Prerequisites

• You must have a valid account (username and password) to access the LiveVox platform. You can use the same username and password to log into the LiveVox Portal (LVP). You can also create a separate account for building applications with the API.
• You must have a valid Access Token that you will include in the Session requests you make to the LiveVox API. For more information, see the Security section below.

General Features

This section describes the general features of the LiveVox REST APIs.

Base URLs

All REST URLs referenced in the LiveVox API documentation have the following base:

https://api.livevox.com/{apiCategory}/{apiResource}...

For example:

LiveVox Environments and APIs

LiveVox portals exist in multiple environments; NA3, NA4, NA5, or NA6; depending on the environment a customer is in, the LiveVox API URLs will change. 

The clients can use the following URLs based on the environment they are using:

NA3 = https://api.livevox.com/session

NA4 = https://api.na4.livevox.com/session

NA5  = https://api.na5.livevox.com/session

NA6 = https://api.na6.livevox.com/session 

Security

All API interactions are carried out over HTTPS. This ensures that confidential information in both the request and URI are encrypted and are not prone to man-in-the-middle attacks. In addition, all API users are required to login before requesting the platform. No request will be authorized without a valid login session. Finally, clients are responsible for maintaining endpoint and client application security. This includes performing OS, browser, and other patching requirements to avoid security issues within their systems.

This section describes the use of Access Tokens, SessionIDs, and the effect of the user roles and agent configured in the client's LiveVox portal, which helps determine what you can and cannot do through the LiveVox APIs.

Access Tokens

Access tokens are generated by LiveVox and can be requested by contacting your Account team. They do not expire.

An access token is only required on the Session API login request. All other requests made with the resulting session will be tied to the API token provided in the login request for tracking purposes.

You must only pass the Access token with the filed name LV-Access. For example, if your Access token is NtBQkXoKElu0H1a1fQ0DWfo6IX4a, then your API request would include the following in the HTTP header:

If you don't send an Access token or send the wrong token, you will receive a 401 Unauthorized  response.

Session IDs

A Session ID is a string that must be passed in with all API requests except the Login, IsSessionValid, ChangePassword, and Logout requests. Your client application must first issue a Login request that includes a valid Client Name, Username, and Password. You will receive a Session ID in the response. To close the session, issue a Logout request. Session IDs will expire if there is no activity for 2 hours. Login requests by the same user with the same API Token will return the same Session ID if a valid one already exists. In addition, because Session IDs are tied to the LV-Access token, if a user makes two login requests with different API Tokens, then unique Session IDs will be returned.

Once you have logged in and received a Session ID, you will include it in an HTTP header.

The Session ID must be passed in the LV-Session header. The Session ID will be the only thing passed in the value. For example, if your Session ID is 5eb4ad6c-50b7-45da-8d56-f4e9ac7d9cbd, then your API request will include the following in the HTTP header: 

User Roles & Permissions

When you create a user and issue a Login request and receive a Session ID, the user has a configured security role to log in to the LiveVox platform. The configured user will have "optional powers" along with the assigned capabilities to access an API. The user should have the same role in both the LiveVox portal and the LiveVox API. For example, suppose the user has Read and Edit "Do Not Call" lists role in the LiveVox Portal. In that case, the same permission is applicable in the LiveVox API portal programmatically.

In the Agent login request, the Agent can access a few API methods during a session initiated by an Agent. For a list of these methods, refer to the "User Roles" section of each API's documentation.

The LiveVox Users/Agents created in a LiveVox platform are configured to access only specified services and Call Center. The LiveVox API uses the same permissions to determine the APIs the user can read, write, update, delete, etc., Moreover, these object permissions are considered when the user queries the LiveVox platform to retrieve information, such as list certain configuration objects. For example, suppose a user is configured to access only five of the twelve services under Call Center A in the LiveVox Portal. When a query is passed in the LiveVox API, only five services will be listed under Call Center A.

If the role or permissions are modified, they will reflect only after 5 minutes. You can create a new session for that user for the user's updated role or permissions to be accounted for in API requests.

Support for Cross-Origin Resource Sharing (CORS)

CORS is not supported in the LiveVox APIs.

SSL

For security purposes, the LiveVox API is only supported over HTTPS. Requests over HTTP will be rejected.

Date and Time Notation

Date/Time

dateTime parameters in REST API requests in JSON must be represented in the number of milliseconds since midnight on January 1, 1970 (UTC) or equivalent date/time zone format. JSON responses to REST API requests will always return dateTime parameters in the number of milliseconds since midnight on January 1, 1970 (UTC).

Time

time parameters in REST API requests in JSON must be represented as the number of milliseconds since midnight (UTC) or equivalent time zone format . JSON responses to REST API requests will always return time parameters in the number of milliseconds since midnight on January 1, 1970 (UTC).

Date

date parameters in REST API requests in JSON must be represented as the number of milliseconds since midnight on January 1, 1970 (UTC)  equivalent time zone format. JSON responses to REST API requests will always return date parameters in the number of milliseconds since midnight on January 1, 1970 (UTC).

REST APIs

The LiveVox REST APIs provide basic CRUD (create, read, update, and delete) capabilities through standard HTTP methods. Resources are made to appear as file-like and can be manipulated in this fashion. Successful changes to a request will be responded to with a 2xx status code. If the request was unsuccessful, then an error will be returned. For more information, see the Errors section.

REST Request Formats

Headers

In addition to the security-related HTTP headers, you must include the Content-Type header field in all requests to the REST API in LV19 and later versions. Also, you can include the Accept header field in all requests to the REST API. 

Content-Type

You can specify the MIME type of the request is JSON. This is done by using the Content-Type header field:

The Content-Type header field is optional up to U17 version.

Accept

The Accept header field is used to specify the MIME type for response. The currently supported MIME type is only JSON format and you can include header as Accept: application/json. 

Body

If a request contains a body, then you are required to include a body even if it is an empty body with just empty braces as {}.

Using URL Query Parameters in the Request

The REST API requests that support query parameters will indicate their support within the detailed documentation for those requests. In general, the usage pattern for such URLs will be:

https://api.livevox.com/{apiCategory}/{apiResource}...?{parameter1Name}={parameter1Value}&{parameter2Name}={parameter2Value}...

For example, to pass query parameters in the  ListDNC  request to retrieve the list of Daily DNC records for Client ID 12345, the GET HTTP request would look like this:

https://api.livevox.com/compliance/dnc?dncType=DAILY&client=12345

In the API documentation, optional query parameters are enclosed in brackets [ ].

Pagination

Certain API responses support pagination. To ensure that the response to your API request contains the data you would like, you will use the query parameters offset and count in the request. Note that for requests that use pagination, such as List queries, the usage of the offset and count query parameters is mandatory, not optional.

For example, if you expect the response to a ListDNC request to return hundreds of records, you would use the count and offset query parameters to control how many records are returned, as well as the starting number of the record (the offset from 0). If you wanted the response to provide 200 Daily DNC records, starting with record #200, the format of the request would look like this:

.../dnc?dncType=DAILY&client=12345&count=200&offset=200

Since the offset parameter represents the offset from zero, it means that if you wanted to return the first 200 Daily DNC records, you would use 0 as the value for the offset parameter.

REST Response Formats

You can control whether the REST responses are in XML or JSON, based on the value of the Accept header you pass in the request. See the Accept section above for details.

The API Rate Limit

The rate limit of an API refers to the maximum number of calls you can make within a period of time. Rate limits apply to limit API requests to the LiveVox Server. Currently, the Append Campaign method has a rate limit of 5 requests per minute; however, API rate limits can vary depending on the API. To avoid approaching an API’s rate limit, wait for a response before placing another call to the same API method.

Errors

Errors resulting from the use of the REST API will be generally communicated through the standard HTTP Status Codes. See Status Code Definitions for the standard list. Common errors include but are not limited to:

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error
• 503 Service Unavailable

In addition, error responses may contain a message body that will provide additional information. This message body is not a mandatory component in an error response.

#Response 
500 Internal Server Error
Content-Type: application/json
 
{[{"code": 42, "message": "Unable to charge the flux capacitor. Speed has not exceeded 88mph."}
 
#Response (XML)
500 Internal Server Error
Content-Type: application/xml
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorResponse xmlns="http://api.livevox.com/fault/v3.0" code="42" message="ibid"/>

#Response
400 Bad Request
Content-Type: application/json
 
{
   "code": 202,
   "message": "Missing required field"
}
 
#Response
400 Bad Request
Content-Type: application/xml
 
<ErrorResponse code="202" message="Missing required field" xmlns="http://api.livevox.com/fault/v3_2"/>