Methods, endpoints and parameters of the RingCentral API

This guide describes the fundamentals of the RingCentral API and is a useful to developers wishing to understand its conventions and usage guidelines.

Resources and parameters

Every entity in the RingCentral API is represented with a certain resource identified by a specific URI. The structure of a URI is similar to that of a web page's URL. The URI syntax is represented by the following scheme:

<protocol> :// <hostname> [: <port>] / <path> [? <query>] [# <fragment>]

Protocol, host and port together constitute the main entry point to access the API.

RingCentral production servers are accessible on https://platform.ringcentral.com. Please note that for security reasons connection is allowed using only HTTPS protocol to the default HTTPS port 443, so the port can be omitted in the URI.

Path parameters: account and extension IDs

All of RingCentral's API resources are organized in a hierarchical manner. All resource paths start with /restapi followed by the version number of the API you are accessing. Let's consider a typical API resource URI:

https://platform.ringcentral.com/restapi/v1.0/account/159048008/extension/171857008/call-log?dateFrom=2012-08-26

Path parameters are commonly used in the RingCentral API to identify a particular entity belonging to a given type by its unique key. Since most of the API resources represent some objects which are owned by particular a RingCentral account (company) or user, two basic path parameters are accountId and extensionId. As you might expect, they identify the account and extension of a RingCentral user, accordingly, and are bolded in the example above.

Developers often need to access a particular resource on behalf of the user whose credentials (phone number, extension number and password) were transmitted during the authentication phase. As a shortcut, one can use the tilde symbol (~) in place of the accountId and/or extensionId to access data that belongs to the account/extension of the entity one is currently authenticated as. Considering the example above, if the user successfully authenticated to work with account "159048008" and extension "171857008" the URI to retrieve the same resource may be written as follows:

https://platform.ringcentral.com/restapi/v1.0/account/~/extension/~/call-log?dateFrom=2012-08-26

Depending upon the API, additional path parameters may exist. They are described extensively in the API Reference.

Query Parameters

Another kind of parameter you will come across in the RingCentral API is a query parameter. Query parameters are generally used in object retrieval operations and let the consumer specify the filtering criteria, the desired level of details, etc. Query parameter values in the URL have to be encoded according to RFC-1738: Uniform Resource Locators. Query parameters support setting multiple values. It is possible to specify several values for a single query parameter, and filtering results will cover all of them. For example, this functionality is applied to retrieve or remove lists of messages and records.

Examples

Let's consider the examples below to illustrate the API resources and parameters. For simplicity reasons, we will exclude protocol and host values from the URIs in the examples.

• Get service plan information for RingCentral customer account (accountId will be automatically determined from authentication data):

  /restapi/v1.0/account/~/service-info

• Get all SMS messages from a mailbox of account user (extensionId is specified explicitly):

  /restapi/v1.0/account/~/extension/171857008/message-store?messageType=SMS

• Get all SMS and Pager messages from a mailbox of account user:

  /restapi/v1.0/account/~/extension/~/message-store?messageType=SMS&messageType=Pager

Methods

In the RingCentral API, as in any REST API, the resources are accessible by standard HTTP methods: GET, POST, PUT and DELETE. These methods form a uniform CRUD interface expanded as "create, retrieve, update and delete".

Example

Let's consider a simple example of a GET method — retrieving the version of the RingCentral REST API.

GET /restapi/v1.0 HTTP/1.1
Accept: application/json
Authorization: Bearer UExxxxxxxxMnzpdvtYYNWMSJ7CL8h0zM6q6a9ntw

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uri" : "https.../restapi/",
  "apiVersions" : [ {
    "uri" : "https.../restapi/v1.0",
    "versionString" : "1.0.9",
    "releaseDate" : "2013-12-01T00:00:00.000Z",
    "uriString" : "v1.0"
  } ],
  "serverVersion" : "6.1.0.846",
  "serverRevision" : "294476"
}

Method Tunneling

Sometimes, due to different technical/networking limitations, API clients cannot issue all HTTP methods. In the most severe case a client may be restricted to GET and POST methods only. To work around this situation the RingCentral API provides a mechanism for masquerading (or "tunneling") PUT and DELETE methods as a POST. This can be achieved in two ways:

X-HTTP-Method-Override header

Using X-HTTP-Method-Override the client instructs the server to override the actual value of the HTTP method by one passed in this header. For example, the following request:

DELETE /restapi/v1.0/account/~/extension/~/message-store/4084362008 HTTP/1.1

Can be alternatively sent as:

POST /restapi/v1.0/account/~/extension/~/message-store/4084362008 HTTP/1.1
X-HTTP-Method-Override: DELETE

The "_method" query parameter

In really unfortunate circumstances some clients do not even support HTTP headers. Therefore, one additional way one can override the method name is via the _method query parameter. For example:

POST /restapi/v1.0/account/~/extension/~/message-store/4084362008?_method=DELETE HTTP/1.1

If both the override header and query parameter are specified in the HTTP request and contain different values, the server returns HTTP 400 Bad Request error.

User Agent Identification

It is strongly recommended that client applications provide the User-Agent HTTP header with every request, which should contain the key information about the requesting application, including application name, version, OS/platform name and version, etc. For browser-based (JavaScript) applications it is usually not possible to override the user agent string which is sent by browser. But other types of applications (desktop, mobile and server-side) can easily follow this recommendation.

There are three primary rules when setting the User Agent:

1. Clients should send the User-Agent header and value with each request.
2. A particular application instance should send the exact same user agent string in all API requests.
3. The format of user agent value should follow the convention described below.

We recommend using a short application name and version delimited by forward slash character and optionally followed by additional details about this client instance in parentheses (e.g. operating system name, version, revision number, etc.).

For example:

• RCMobile/3.6.0 (RingCentral; Android/2.6; rev.12345)
• RCMobile/3.6.1 (OfficeAtHand; iOS/6.0; rev.987654)
• Softphone/6.2.0.11632

The User-Agent string format is described in RFC 1945 and RFC 2068.