Please read this entire document before proceeding if this is your first time using the LiveVox APIs. It provides crucial information about how to successfully use the LiveVox APIs and will allow for a much smoother startup process.

The LiveVox API

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 also be used to build custom applications that make use of LiveVox functionality, such as custom agent desktops and reporting dashboards. The LiveVox APIs are independent of programming languages, so you can use it to develop applications in the language of your choice (Java, .NET, C, C++, PHP, etc.)

LiveVox provides its APIs through both REST and SOAP interfaces. In v3.3 the ACD API has been replaced by the Call Control API and is available in both SOAP and REST.

Information About Future Development

Please be aware that all new development is done in REST JSON ONLY. Current SOAP and XML functionality will remain available in current versions, however in v6.0 ALL SOAP/XML FUNCTIONALITY WILL BE REMOVED. We strongly advise you to use REST if you are just starting out with the LiveVox APIs.

Prerequisites

  • You must have an internet connection to communicate with the LiveVox API
  • You must have a valid account (username and password) to access the LiveVox platform. This may be the same username and password that you use to log into the LiveVox Voice Portal (LVP), but you may also create a separate account for use in building applications with the API.
  • You must have a valid Access Token that you will include in the requests you make to the LiveVox API.
  • You must have a development environment or hosting server to integrate the LiveVox API with your custom application.

Top of Page

Common Concepts

This section describes concepts that are common across both the REST and SOAP APIs.

Differences between ACD API and other LiveVox APIs

The concepts described below are applicable to all public LiveVox APIs except the ACD API. SInce the ACD API predates the other public LiveVox APIs, it follows some different conventions. If you are not already using the ACD APIs you MUST use the Call Control APIs instead which follow the same concepts as our other APIs. The most significant ways in which the ACD API differs from the other public LiveVox APIs are:

  • The ACD API is available through a SOAP interface only, whereas the other public LiveVox APIs are available through both SOAP and REST interfaces
  • The ACD API requires LiveVox agent credentials, since it is meant to primarily support building applications such as agent desktops. The other public LiveVox APIs support both agent and LiveVox user credentials. Note that not all API methods of the non-ACD APIs will be accessible to you by using agent credentials. Refer to the specific API documentation pages (e.g. Configuration, Compliance, etc.) for more details.
  • The ACD API uses a "jSessionID" for session management. This means that after using the Logon method of the ACD API, you receive a jSessionID that you will then use in subsequent requests for ACD functionality such as call control. The ID itself gets passed in with the body of the various API requests. The other public LiveVox APIs utilize Session IDs that are provided in the response of either the Login or Agent Login requests (which are part of the LiveVox Session API), and those Session IDs get passed in with subsequent API requests in an HTTP header (as described below).
  • The ACD API does not require an Access Token, whereas the other public LiveVox APIs DO require an Access Token as described below.
  • The ACD API uses a different base URL than the other public LiveVox APIs.

Top of Page

Base URLs

All SOAP URLs referenced in the LiveVox API documentation (other than the ACD API) have the following base:

https://api.livevox.com/{apiCategory}/v{version}/{apiResource}/SOAP

For example:

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

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

For example:

7.0 Change

In v7.0 and above we have introduced some changes to help future API upgrades proceed more smoothly, one of those is the removal of the version number from the URL; so all REST URLs will have the following base:

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

For example:

API requests will be routed to the version defined in LVP on the API tab of the Client Editor.

If a client is on v7.0 or above and includes the version in the URL a 410 Gone error will be returned with a message that versions are no longer supported in the URL.

Security

All requests to the LiveVox API must include two identifiers in the HTTP header (this is changing in v7.0 and above, see references below):

  • Access Token
  • Session ID

This section describes these two concepts, how to generate these identifiers, and how to pass them in with your API requests.

This section also describes the effect that your user role will play in determining what you can and cannot do through the LiveVox API.

Top of Page

Access Tokens

An Access token is a simple string that must be passed in with all API requests–both SOAP and REST. It is used by LiveVox API Gateway to validate that the client making the request is authorized to use the specific API being requested. It is also used to check the request against any pre-determined rate limits for the API. You may also see Access tokens referred to in this documentation as "access keys" or "API keys".

Access tokens are generated by LiveVox, and can be requested by sending an email to customercare@livevox.com or by contacting your Account team. They do not expire.

The Access token must be included in an HTTP header, depending on the version of APIs being used the field name will vary.

In v7.0 and above a user is no longer required to include the LV-Access token in all requests, it is now only required on the Session API login request. For tracking purposes all other requests made with the resulting session will be tied to the API token provided in the login request.

The Access token needs to be passed with the filed name LV-Access. The token itself will be the only thing passed in the value, for example, if your Access token is NtBQkXoKElu0H1a1fQ0DWfo6IX4a, then your API request would include this HTTP header:

LV-Access: NtBQkXoKElu0H1a1fQ0DWfo6IX4a

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

Top of Page

Session IDs

A Session ID is a string that must be passed in with all API requests–both SOAP and REST–except for two, which are the Login and Agent Login requests (Agent Login only available on v3.2 or earlier in later versions it has been combined with Login). Your client application must first issue a Login or Agent Login request that includes a valid Client Name, Username, and Password. (In the case of the Agent Login request, the Username parameter will be populated by a valid Agent Login ID.) You will receive a Session ID in the response. To close the session, you will issue a Logout request. If you don't log out of a session, it will time out automatically, 25 hours after the session was created. It is possible to have multiple active Session IDs for the same Username, which allows you to create a new Session ID prior to the expiration of another one, to support building client applications that should be "always on" (such as a real-time reporting dashboard in a 24x7 contact center).

There are two changes that have been made in v7.0 and above to the functionality of Session IDs:

  1. Session IDs no longer expire after 25 hours, instead expiration will be based on activity. A token will expire if there is no activity on it for 2 hours.
  2. 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 field name of the header will vary based on the version of APIs being used.

If v3.2 or earlier is being utilized then the Session ID must be passed in the X-Authorization-LV field. It must be prepended with the string LV s= (which is case-sensitive). For example, if the Session ID that you are using is 5eb4ad6c-50b7-45da-8d56-f4e9ac7d9cbd, then your API requests would include this HTTP header:

X-Authorization-LV: LV s=5eb4ad6c-50b7-45da-8d56-f4e9ac7d9cbd

If v3.3 or later is being used then the Session ID must be passed in the LV-Session field. The Session ID itself 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 would include this HTTP header:

LV-Session: 5eb4ad6c-50b7-45da-8d56-f4e9ac7d9cbd

Top of Page

User roles & permissions

When you issue a Login request and receive a Session ID, the user on whose behalf you log in to the LiveVox platform has a configured security role. This role, along with any "optional powers" that have been configured for the user, will determine what capabilities you can access through the API. Except where noted in the API documentation, this access should mirror what that user would be able to do through the LiveVox Portal. For example, if a user belongs to a role (and perhaps associated optional powers) that enables him to read and edit Do Not Call lists through the LiveVox Portal, then that same user would be able to log into the LiveVox API and read and edit Do Not Call lists programmatically.

In the case of an Agent login request some, but not all, API methods can be accessed during a session initiated by an Agent. For a list of these methods, please refer to the "User Roles" section of the documentation of each API.

LiveVox Users (and Agents) created on the LiveVox platform are also configured with permissions to access specific Services, which in turn define the Call Centers they can access. These same permissions are used by the LiveVox API to determine which data that user can read, write, update, delete, etc. Moreover, these object permissions are taken into account when the user queries the LiveVox platform to retrieve information such as lists of certain types of configuration objects. For example, if a user only has access to 5 of 12 Services that are configured under Call Center A, if that user issues a query through the LiveVox API to list the Services under Call Center A, the size of that list will be reflected as "5", not "12". Furthermore, the actual Services returned in the list query would only be the 5 Services to which he has permission.

Note that if the role or permissions of a user are modified, those modifications will take affect 5 minutes after they are made. A new session can also be created for that user in order for the user's updated role and/or permissions to be accounted for in API requests.

With API v3.4 and v3.5 there is a bug where sysadmins are limited to only the services they’re assigned to. The bug is fixed in API v5.0 and above and is left as is in v3.4 and v3.5 to avoid disruption or breaking of a client's already working application in those versions.

Support for Cross-Origin Resource Sharing (CORS)

CORS is not supported in v3.3 and above of 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 SOAP and REST API requests sent in XML must be formatted according to the XML Schema specification's definition ofdateTime. XML responses to SOAP and REST API requests will represent dateTime parameters in this format as well.

dateTime parameters in REST API requests in JSON must be represented as the number of milliseconds since midnight on January 1, 1970 (UTC). JSON responses to REST API requests will display dateTime parameters in this format as well.

Time

time parameters in SOAP and REST API requests send in XML must be formatted according to the XML Schema specification's definition oftime. XML responses in SOAP and REST API requests will represent time parameters in this format as well.

time parameters in REST API requests in JSON must be represented as the number of milliseconds since midnight (UTC). JSON responses to REST API requests will display time parameters in this format as well.

Date

date parameters in SOAP and REST API requests send in XML must be formatted according to the XML Schema specification's definition ofdate. XML responses in SOAP and REST API requests will represent date parameters in this format as well.

date parameters in REST API requests in JSON must be represented as the number of milliseconds since midnight on January 1, 1970 (UTC). JSON responses to REST API requests will display date parameters in this format as well.

Top of Page

REST APIs

There is a separate section of the LiveVox API documentation about the REST APIs Overview, containing an overview as well as detail about each API method.

SOAP APIs

There is a separate section of the LiveVox API documentation about the SOAP APIs Overview, containing an overview as well as detail about each API method.

Top of Page