loading table of contents...

Overview

Resources and Parameters

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

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

  • protocol indicates a networking protocol (http or https protocols are generally used in REST).

  • hostname is a part of the URI that contains server network address information.

  • port is a TCP port where server listens for incoming requests. If omitted, the default value is used for a given protocol.

  • path is a resource identification hierarchical by nature.

  • query is an optional part separated by a question mark (?) and contains additional identification information that is not hierarchical in nature. The query string syntax is commonly organized as a sequence of key=value pairs separated by an ampersand. In the case of the RingCentral API, key is a name of query parameter, while value is its value. Not all API resources allow query parameters.

  • fragment is an optional part separated from the front parts by hash symbol (#), that contains additional information redirecting to a secondary resource; for example, a section heading of an article identified by the URI. The RingCentral REST API does not use fragments.

Protocol, host and port altogether 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.

even

[Note] Note

If you plan to work with non-production servers you may be required to use other entry points. For example, RingCentral Sandbox environment is accessible via https://platform.devtest.ringcentral.com base URI. If you are not sure what URI you should use for your environment, please contact RingCentral Technical Support to get proper connection settings.

All of the API resources are organized in a hierarchical manner and presented in a tree-like structure. All resource paths are started from /restapi. 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

The URI in the example above contains path parameters highlighted in bold. 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. They identify the account and extension of a RingCentral user, accordingly.

[Note] Note

RingCentral users associate an account with the company main phone number and an extension with the short extension number, but both accountId and extensionId are internal identifiers.

At the same time the typical API usage scenario includes accessing particular resources on behalf of some user whose credentials (phone number, extension number and password) were passed on authentication phase. Thus in this case API enables the simplified syntax of specifying account and extension identifiers in the URI. The tilde symbol (~) can be used as a replacement for both accountId and extensionId if you are going to access data that belongs to account/extension that you are currently logged in to. 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

Apart from these two basic path parameters you will also meet the others while learning the API. They will be discussed further in this guide and are extensively described in the API Reference section.

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.

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

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

  • GET method is idempotent and retrieves the object represented by the resource that is specified in the request body. It may be the call log information for an extension, the address book with contacts, etc.

  • POST method creates a new object represented by the resource that is specified in the request. In the response body the server sends the representation of the created object, as if there is an immediate GET request for it.

  • PUT method modifies the already existing object represented by the resource that is specified in the request body. If the object was successfully modified, the server responds with the representation of the changed resource in the response body. The request body may contain only the modified properties of the resource. The response returns the entire resource representation with all of the properties, as in case of the GET request.

  • DELETE method removes the object represented by the resource that is specified in the request body.

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

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"
}

The majority of API resources do not support all of the four methods. In order to find out which resources support a particular method, please refer to the corresponding section.

Method Tunneling

Sometimes, due to different technical 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 tunneling PUT and DELETE methods through POST. This can be achieved in two ways:

  1. 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
                     
  2. _method query parameter

    In really unfortunate circumstances some clients do not even support HTTP headers. The API allows overriding the method name using _method query parameter. See the example below which demonstrates this approach.

    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.

Tunneling HTTP methods should be used only when no other workaround is available. Each HTTP method has its own characteristics, such as how it is cached, which HTTP clients and intermediaries expect. When tunneling these methods through HTTP POST, those expectations can no longer be met.

Object Representation

Whenever you need to send or retrieve a particular piece of data — for example, a call log record, information on an extension, etc. — it will be embedded in the HTTP request or response.

The RingCentral API allows you to explicitly define a representation format by using the following HTTP headers.

  • Content-Type header defines the MIME type of the request body. The server will expect the request body to contain data in the specified format.

  • Accept header indicates desired MIME type of the response body. The server will return response data in this format (if possible) and will set the Content-Type response header accordingly.

[Note] Note

The API server accepts and returns all string values in UTF-8 encoding and does not support other character sets. It is not required to explicitly specify charset in Content-Type and Accept HTTP headers. But a client has to implement proper encoding/decoding of character strings passed in HTTP requests/responses.

Supported Representation Formats

Format MIME type HTTP request/response body example

JSON

application/json

{
   "uri": "https://platform.ringcentral.com/restapi/v1.0",
   "versionString": "1.0.0",
   "releaseDate": "2012-06-14T00:00:00.000Z",
   "uriString": "v1.0"
}

HTML Form Data

(only for token request body as governed by OAuth 2.0 specification)

application/x-www-form-urlencoded

grant_type=password&username=18887776655&password=987654

The RingCentral API uses JSON as the default representation format. It means that if the Accept header is not set, the server will return results in JSON. And, consequently, all of the examples in this guide are given in JSON.

However, Content-Type header is mandatory for all requests which have body (namely requests with POST and PUT HTTP methods). Also for such requests client is required to provide Content-Length header containing the length of the request body in bytes.

Data Types

The table below describes the data types which are used in the RingCentral API.

Data Type Description
string General string value
enumeration Predefined string constants/List of predefined string constants
integer 64-bit integer value
datetime

Timestamp in XML Schema-compatible format, in accordance with ISO 8601, see its profile at Date and Time Formats .

Note that "T" appears literally in the string, to indicate the beginning of the time element.

The supported formats with the examples are as follows:

Year:
      YYYY (eg 2012)
Year and month:
      YYYY-MM (eg 2012-07)
Complete date:
      YYYY-MM-DD (eg 2012-07-16)
Complete date plus hours and minutes:
      YYYY-MM-DDThh:mmTZD (eg 2012-07-16T23:12:30)
Complete date plus hours, minutes and seconds:
      YYYY-MM-DDThh:mm:ssTZD (eg 2012-07-16T23:12:30Z or 2012-07-16T23:12:30+04:00)
Complete date plus hours, minutes, seconds and a decimal fraction of a second:
      YYYY-MM-DDThh:mm:ss.sTZD (eg 2012-07-16T23:12:30.45Z)

where:

     YYYY = four-digit year
     MM   = two-digit month (01=January, etc.)
     DD   = two-digit day of month (01 through 31)
     hh   = two digits of hour (00 through 23) (am/pm NOT allowed)
     mm   = two digits of minute (00 through 59)
     ss   = two digits of second (00 through 59)
     s    = one or more digits representing a decimal fraction of a second
     TZD  = time zone designator (Z or +hh:mm or -hh:mm)

The server currently processes all timestamps in UTC time zone; for example, 2012-01-01T00:15:34Z.

By default the server returns datetime format in full format, including a decimal fraction of a second YYYY-MM-DDThh:mm:ss.sTZD, for example 2012-07-16T23:12:30.45Z).

Please note, that when comparing timestamps, the timestamp is truncated to a second precision. For example, the response to request where the dateFrom value is 2012-07-16T23:12:30.45Z is always identical to the one with the dateFrom value 2012-07-16T23:12:30Z.

Resource Identification Properties

The table below describes properties which are supported by almost all API resources and used for identification purposes.

Parameter Type Description
id integer / string Internal unique identifier of a resource. This property exists in all resources which support retrieval/update/delete of a single record of particular type. Depending on a resource it can hold either an integer or a string value. The resource id is also passed as a path parameter in the URI
uri URI string Canonical URI of a resource. This URI might not be the same as the one which was used to retrieve this resource information. For example, if a resource was accessed by the URI containing simplified syntax with the tilde (~) characters, the canonical URI will also contain real identifiers. In most cases the URI contains an id value embedded as a path parameter

The similar convention is used when one resource refers to another. For example, a direct phone number returned by the API contains a link to the extension it is assigned to in the following property:

"extension": 
  {
  "id": 234244008, 
  "uri": ".../account/405884008/extension/234244008"
  } 

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 main rules:

  • Client should send User-Agent value with each request

  • Particular application instance should send exactly the same user agent string in all API requests

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

Look at the examples below:

User-Agent: RCMobile/3.6.0 (RingCentral; Android/2.6; rev.12345)
User-Agent: RCMobile/3.6.1 (OfficeAtHand; iOS/6.0; rev.987654)
User-Agent: Softphone/6.2.0.11632

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

Languages Support

In most cases the content returned by RingCentral API is not localized because it is assumed to be machine-readable, not human readable. So all constants, enumerated values, error codes are in US English. However there are some API methods which return localized content. In this case client application can pass the preferred language (locale) code in the Accept-Language HTTP header. If this header is omitted, incorrect or contains unsupported language code, the server returns localized content in the language which is configured in user extension's regional settings (by default, en-US for RingCentral US and Canada accounts, en-GB for RingCentral UK accounts).

The server returns the language code in the Content-Language header in response.

For example, if one needs to get the localized content in English (UK variant)

GET /restapi/v1.0/.... HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxM
Accept-Language: en-GB
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en-GB

{...}

Response Status Codes. Error Handling

The RingCentral API is built on top of HTTP protocol, making use of general concepts and common HTTP status codes to inform a client on results of method calls.

The possible response scenarios are:

  1. Success — HTTP response with 2xx or 3xx status code and optionally - body payload depending on the request.

  2. Client Error — HTTP response with a 4xx status error code. Occurs if client does something disallowed or incorrect.

  3. Server Error — HTTP response with a 5xx status code. Occurs in case of unexpected issues on server side.

Response Status Codes

HTTP 2xx - Success — 200, 201, 202, 204, 206

Indicate that the action requested by the client was received, understood, accepted and processed successfully.

HTTP 207 is a multi-status code which is returned for API requests consisting of multiple parts. In this case the first part of a multipart response contains JSON array with HTTP status codes corresponding to each part of a response, see also Multi-Status, Batch Requests.

For example:

GET /restapi/v1.0/account/1446856004/extension/1446856004/message-store/2147676004,2147694004 HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwM3xBQURiN1lJRkROUTIya2xPaEhMaFR0WEVmLe_T0eA
Accept: application/json

HTTP/1.1 207 
Content-Type: multipart/mixed;boundary=Boundary_4061_632833321_1448881816038
Content-Language: en-US
Content-Length: 2406

--Boundary_4061_632833321_1448881816038
Content-Type: application/json

{
  "response" : [ {
    "href" : "https.../restapi/v1.0/account/1446856004/extension/1446856004/message-store/2147676004",
    "status" : 200,
    "responseDescription" : "OK"
  }, {
    "href" : "https.../restapi/v1.0/account/1446856004/extension/1446856004/message-store/2147694004",
    "status" : 200,
    "responseDescription" : "OK"
  } ]
}
--Boundary_4061_632833321_1448881816038
Content-Type: application/json

{
  "uri" : "https.../restapi/v1.0/account/1446856004/extension/1446856004/message-store/2147676004",
  "id" : 2147676004,
  {...}
}
--Boundary_4061_632833321_1448881816038
Content-Type: application/json

{
  "uri" : "https.../restapi/v1.0/account/1446856004/extension/1446856004/message-store/2147694004",
  "id" : 2147694004,
  {...}
}
--Boundary_4061_632833321_1448881816038--

HTTP 3xx - Redirection — 301, 302, 303, 304, 307, 308

Indicate that the client must take additional action to complete the request. For 301, 302, 303, 307 and 308the client must support automatic redirection to new URL returned in Location header.

If by some reason Location header is not returned, the client should repeat request to the target URL specified in Location header in original request.

HTTP 304 indicates that resource is not modified and there is no need to update its locally cached version. Returned for API requests with conditional headers If-None-Match or If-Modified-Since.

Example:

GET /restapi/v1.0/number-parser/phonedata.xml HTTP/1.1
Accept: application/xml
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFT3FnS3RzN2Jhd2tsZmo5NFl5
If-None-Match: "1.25"
HTTP/1.1 304 Not Modified
ETag: "1.24"
Content-Language: en-US

HTTP 4xx - Client Error — 400, 403, 405, 406, 409, 415

Indicate that the client does something incorrect. In this case (except for 429) the request should be changed.

HTTP 429 means that the client exceeded some rate limit defined for this API request (a particular one or any). The client should resend the original request when retry period is over, the value of retry period is specified in seconds in Retry-After response header.

HTTP 401 means that access token provided by the client is invalid or expired. The client should request a new access token and repeat the request.

HTTP 404 often means that the requested URL is invalid; or that resource with the given ID (a part of URL) is not accessible for the authorized user or does not exist. If the code is returned as a result of DELETErequest it can be ignored, it means the resource was already deleted on server.

HTTP 5xx - Server Error

Indicate that the server failed to fulfill an apparently valid request. The client may retry request up to 3 times and contact RingCentral Developer Support if the problem persists.

HTTP 503 means that the server is currently unavailable (overloaded or down for maintenance), which is a temporary state. In some cases this status indicates that the server cannot handle just this particular request type while others still can be processed. The client should resend the original request when retry period is over, the value of retry period is specified in seconds in Retry-After response header.

Logical Error Codes

The API uses specific logical error codes to make error processing for client applications more simple and effective. The body of HTTP response should be always logged and analyzed. It is sometimes impossible to understand the reason of the issue by HTTP status code only, so the logical code from the body should also be taken into consideration. The client app should rely on error code and, in some cases,on additional fields like parameterName, not on error message as they can be changed in next API versions.

Error code is unique and consists of two parts: short name of a functional module and a digital number, unique per module, for example CMN-101, MSG-221, etc.

The most common logical error codes are:

CMN-101 — for most of 'Invalid parameter' errors;

CMN-102 — for most of 'Not found' errors (for resource identifiers provided either in path or in request body);

CMN-201 — for most of temporary internal server errors;

CMN-203 — for most of internal server errors, of which client app is not aware of and/or cannot affect;

BIL-101 — for most of 'Feature not available' errors in terms of account service/billing plans;

BIL-102 — for most of 'Limit exceeded' errors in terms of account service/billing plans.

Response body can contain multiple error messages and has the following common structure:

{
   "errorCode":"LegacyCode",  //legacy logical error code, deprecated. Will not be supported in later versions of API"message":"Error message", //legacy error message
   "errors": [
      {
         "errorCode":"ABC-123",     //logical error code
         "message":"Error message", //error message
         "additionalInfo":"value",  //additional attribute for this error, e.g. "parameterName":"extensionId"
      },
      {
         "errorCode":"CBA-321",
         "message":"Second error message"
      }
   ]
}

Let's see the example below:

{
   "errorCode": "InvalidParameter",
   "message": "Parameter [to] is invalid. No recipients specified.",
   "parameterName": "to",
   "errors":    [
            {
         "errorCode": "MSG-219",
         "message": "Parameter [to] is invalid. No recipients specified.",
         "parameterName": "to"
      },
            {
         "errorCode": "MSG-221",
         "message": "Parameter [from] is invalid. Value is empty.",
         "parameterName": "from"
      },
            {
         "errorCode": "MSG-224",
         "message": "SMS message is empty."
      }
   ]
}

Batch Requests

One of the commonly used REST practices is the support of batch operations to retrieve multiple homogeneous resources by their key using a single request. The RingCentral API supports batch requests for a number of endpoints, for example messages, call records, blocked numbers, presence etc. They are implemented via the methods GET, DELETE and PUT with all their features.

Batch operations are not transaction-atomic. Each resource in a batch is processed separately from the others, making it possible to receive different success/failure results for different resources wrapped in a multipart response object. The HTTP status code 207 Multi-status (Multi-Status) is returned in every multipart response object and indicates a batch request.

[Note] Note

The 207 Multi-status code is not returned in response body in case of error accessing the endpoint. For example, if the requested endpoint does not exist at all, 404 Not Found status code is returned. If there is a server error, 5xx status code is returned.

In batch DELETE operations (if all resources are deleted successfully) the server returns the 204 No content instead of multi-status (since all parts would be identical in this case). In case of at least one failure the server returns the 207 Multi-status.

Apart from the top-level special status code in case of success, a multipart response object contains status codes in each part, representing a particular requested resource. This status specifies an individual result for each requested resource out of the batch. Let's consider the examples of batch request below.

1. Batch request via GET method:

GET /restapi/v1.0/account/~/extension/~/message-store/2447722008,2416832008 HTTP/1.1
Accept: application/json 

HTTP/1.1 207 Multi-Status
Content-Type: multipart/mixed

--Boundary_20_32057915_1351669531796
Content-Type: application/json

{
  "response" : [ {
    "href" : ".../account/154364008/extension/154364008/message-store/2447722008",
    "status" : 200,
    "responseDescription" : "OK"
  }, {
    "href" : "...1/restapi/v1.0/account/154364008/extension/154364008/message-store/2416832008",
    "status" : 200,
    "responseDescription" : "OK"
  } ]
}
--Boundary_20_32057915_1351669531796
Content-Type: application/json

{
  "uri" : ".../restapi/v1.0/account/154364008/extension/154364008/message-store/2447722008",
  "id" : 2447722008,
  "to" : [ {
    "phoneNumber" : "18559100010"
  } ],
  "from" : {
    "phoneNumber" : "18559100010"
  },
  "type" : "SMS",
  "creationTime" : "2012-10-29T15:36:04.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 1,
    "uri" : ".../restapi/v1.0/account/154364008/extension/154364008/message-store/2447722008/content/1",
    "contentType" : "text/plain"
  } ],
  "direction" : "Inbound",
  "availability" : "Alive",
  "subject" : "verificationMessage",
  "messageStatus" : "Received",
  "conversationId" : 5717224681082742945,
  "lastModifiedTime" : "2012-10-29T15:36:04.000Z"
}
--Boundary_20_32057915_1351669531796
Content-Type: application/json

{
  "uri" : ".../restapi/v1.0/account/154364008/extension/154364008/message-store/2416832008",
  "id" : 2416832008,
  "to" : [ {
    "phoneNumber" : "18559100010"
  } ],
  "from" : {
    "phoneNumber" : "16509101086"
  },
  "type" : "SMS",
  "creationTime" : "2012-10-29T13:09:54.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 1,
    "uri" : ".../restapi/v1.0/account/154364008/extension/154364008/message-store/2416832008/content/1",
    "contentType" : "text/plain"
  } ],
  "direction" : "Inbound",
  "availability" : "Alive",
  "subject" : "Inbound SMS",
  "messageStatus" : "Received",
  "conversationId" : 141549019326272744,
  "lastModifiedTime" : "2012-10-29T13:09:54.000Z"
}
--Boundary_20_32057915_1351669531796--

2. Batch request via PUT method:

  • The client has to specify the multipart/mixed content type and the boundary;

  • The client has to provide in request body modified fields for every single item which needs to be updated, separated by multipart boundaries.

PUT /restapi/v1.0/account/~/extension/~/message-store/401654758008,401642088008 HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFKV1MwMXz6Z7EkpZfJjToT_z4CVUwdekt9Iw
Content-Type: multipart/mixed; boundary=Boundary_1_15567762_1355833573664

--Boundary_1_15567762_1355833573664
Content-Type: application/json

{"readStatus": "Read"}
--Boundary_1_15567762_1355833573664
Content-Type: application/json

{"readStatus": "Read"}
--Boundary_1_15567762_1355833573664--

HTTP/1.1 207 Multi-Status
Content-Type: multipart/mixed; boundary=Boundary_1_15567762_1355833573664

--Boundary_1_15567762_1355833573664
Content-Type: application/json

{
  "response" : [ {
    "href" : ".../account/400129284008/extension/400129284008/message-store/401654758008",
    "status" : 200,
    "responseDescription" : "OK"
  }, {
    "href" : ".../account/400129284008/extension/400129284008/message-store/401642088008",
    "status" : 200,
    "responseDescription" : "OK"
  } ]
}
--Boundary_1_15567762_1355833573664
Content-Type: application/json

{
  "uri" : ".../account/400129284008/extension/400129284008/message-store/401654758008",
  "id" : 401654758008,
  "to" : [ {
    "phoneNumber" : "18559100010"
  } ],
  "type" : "Fax",
  "creationTime" : "2013-07-11T12:05:43.000Z",
  "readStatus" : "Read",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 1,
    "uri" : ".../account/400129284008/extension/400129284008/message-store/401654758008/content/1",
    "contentType" : "image/tiff"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "messageStatus" : "SendingFailed",
  "faxResolution" : "Low",
  "faxPageCount" : 0,
  "lastModifiedTime" : "2013-07-11T12:26:24.000Z"
}
--Boundary_1_15567762_1355833573664
Content-Type: application/json

{
  "uri" : ".../account/400129284008/extension/400129284008/message-store/401642088008",
  "id" : 401642088008,
  "to" : [ {
    "phoneNumber" : "77653287256446"
  } ],
  "type" : "Fax",
  "creationTime" : "2013-07-11T08:45:57.000Z",
  "readStatus" : "Read",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 1,
    "uri" : ".../account/400129284008/extension/400129284008/message-store/401642088008/content/1",
    "contentType" : "image/tiff"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "messageStatus" : "SendingFailed",
  "faxResolution" : "Low",
  "faxPageCount" : 0,
  "lastModifiedTime" : "2013-07-11T12:26:52.000Z"
}
--Boundary_1_15567762_1355833573664--

Application Permissions

In order to work with particular RingCentral API resources the application should have the corresponding permissions. Required API permissions are generally declared at the stage of application registration and confirmed by the user on authentication stage. The following permissions are available:

Permission Description Access Type  
EditMessages Viewing and updating user messages Read and Update ReadMessages
Faxes Sending and receiving faxes Special operation ReadMessages
Glip Working with Glip teams, users and messages CRUD  
InternalMessages Sending and receiving intra-company text messages Special operation ReadMessages
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number) Read Only  
ReadCallLog Viewing user call logs Read Only  
ReadCallRecording Downloading call recording content Read Only ReadCallLog
ReadMessages Viewing user messages Read Only  
ReadPresence Getting user presence information Read Only  
RingOut Performing two-legged ring-out phone calls Special operation  
SMS Sending and receiving (SMS) text messages Special operation ReadMessages
SubscriptionWebhook Managing push notification subscriptions which use Webhooks Special operation  

API Rate Limits

What is Rate Limit

The Rate Limits is a scheme specifying limits of using the API resources.

Applying rate limits enables consistent load allocation through correct interaction with RingCentral Connect Platform.

API Groups

Each Rate Limit specifies how many requests to each API group are allowed. Currently four API groups are distinguished:

  • Light

  • Medium

  • Heavy

  • Auth

That means all the requests are characterized by their processing as Light, Medium or Heavy. There are also authorization requests, that form a separate group — Auth. Each request is marked as Heavy, Medium, Light or Auth under the header API Group.

What Are Your App Rate Limits?

Rate Limits plan available for your client application is available in your RC account by clicking the 'Rate Limits' in My Apps tab, see the image below. It informs you how many requests of each API group are supported and what is the time frame in seconds for every request.

Let's consider the given rate limits. Within the above presented limits your client application is allowed to send 10 heavy, 40 medium, 50 light and 5 authorization requests per user (RC extension) per minute. If you exceed these limitations the server returns the 429 Too Many Requests HTTP error code. It means that the client is throttled by the server due to high request rate. The retry period in seconds, after which the requests can be sent, is specified in Retry-After response header.

Rate Limits Response Headers

Rate Limits are returned in specific headers in response for each request, unless the request is unlimited. Those headers are:

  • X-Rate-Limit-Group — API group of the given request (Light, Medium, Heavy, Auth)

  • X-Rate-Limit-Limit — current rate limit for the given request

  • X-Rate-Limit-Remaining — the number of requests left for the time interval (window) of this rate limit

  • X-Rate-Limit-Window — time interval in seconds for the given request rate limit

Let us consider the example of request retrieving account information. Rate Limits headers are returned in response alongside with HTTP status code.

GET /restapi/v1.0/account/1696121004 HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUNZemU3b2ZxMUtDWXBoeAxQQ
Accept: application/json


HTTP/1.1 200 OK
X-Rate-Limit-Group: light
X-Rate-Limit-Limit: 1000
X-Rate-Limit-Remaining: 999
X-Rate-Limit-Window: 60
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/1696121004",
  "id" : 1696121004,
  "serviceInfo" : {
    "uri" : "https.../restapi/v1.0/account/1696121004/service-info",
    "brand" : {
      "id" : "1210",
      "name" : "RingCentral",
      "homeCountry" : {
        "id" : "1",
        "uri" : "https.../restapi/v1.0/dictionary/country/1",
        "name" : "United States",
        "isoCode" : "US",
        "callingCode" : "1"
      }
    },
    "servicePlan" : {
      "id" : "1216",
      "name" : "Professional",
      "edition" : "Unknown"
    },
    "billingPlan" : {
      "id" : "159",
      "name" : "Monthly",
      "durationUnit" : "Month",
      "duration" : 1,
      "type" : "Regular"
    }
  },
  "operator" : {
    "uri" : "https.../restapi/v1.0/account/1696121004/extension/1696121004",
    "id" : 1696121004,
    "extensionNumber" : "101"
  },
  "mainNumber" : "+18774180010",
  "status" : "Confirmed",
  "signupInfo" : {
    "signupState" : [ "CreditCardApproved", "BillingEntered", "AccountCreated", "AccountConfirmed" ],
    "verificationReason" : "Unknown"
  },
  "setupWizardState" : "Completed"
}

OAuth 2.0 Authorization & Authentication

The RingCentral API supports OAuth 2.0 authentication flows as described in RFC-6749: The OAuth 2.0 Authorization Framework, RFC-6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage and RFC-7009: OAuth 2.0 Token Revocation.

Authorization

URI

/restapi/oauth/authorize

Authorization Code Flow

Since 1.0.27 (Release 8.3)

Returns link to a login page location.

Method

GET

API Group

Auth

Request Header

Client app may pass localization language code value in Accept-Language header. But if any of these parameters 'localeId' or 'ui_locales' is specified, the header value is overwritten.

Request Body

Parameter Type Description
response_type string Must be set to code
redirect_uri string This is a callback URI which determines where the response is sent. The value of this parameter must exactly match one of the URIs you have provided for your app upon registration
client_id string Identifier (key) of a client application
state string Client state. Returned back to the client at the end of the flow
brand_id string Brand identifier. If it is not provided in request, server will try to determine brand from client app profile. The default value is '1210' - RingCentral US
display 'page' | 'popup' | 'touch' | 'mobile' Style of login form. The default value is 'page'. The 'popup' and 'touch' values are featured for mobile applications
prompt 'login' | 'sso' | 'consent' Specifies which login form will be displayed. Space-separated set of the following values: 'login' - official RingCentral login form, 'sso' - Single Sign-On login form, 'consent' - form to show the requested scope and prompt user for consent. Either 'login' or 'sso' (or both) must be specified. The default value is 'login&sso'
localeId string Localization code of a language. Overwrites 'Accept-Language' header value
ui_locales string Localization code of a language. Overwrites 'localeId' parameter value
ui_options 'hide_logo' | '-hide_tos' | 'hide_remember_me' | 'external_popup' | 'old_ui' User interface options data

Response Body

Link to a login page location.

Example

Request example

GET

/restapi/oauth/authorize?client_id=A50F55593E224b381E81D6A969391D0e49E27FB9A1C3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Foauthredirect&response_type=code&state=ABC123&prompt=login

            

Response example

HTTP/1.1 302 Found

Location:
https://service.ringcentral.com/mobile/loginDispatcher?session=2008293087662283621&clientId=A50F55593E224b381E81D6A969391D0e49E27FB9A1C3
&state=ABC123&brandId=1210&appUrlScheme=https%3A%2F%2Fmyapp%2Eexample%2Ecom%2Foauthredirect&localeId=en_US&display=page&prompt=login&hideNavigationBar=true  
       

Implicit Grant Type Flow

Since 1.0.27 (Release 8.3)

Returns login page location. And upon successful login - access token embedded in a link redirecting to a client web application. Please note: Access token obtained via this request expires in an hour and can be refreshed by sending this request repeatedly.

Method

GET

API Group

Auth

Request Header

Client app may pass localization language code value in Accept-Language header. But if any of these parameters 'localeId' or 'ui_locales' is specified, the header value is overwritten.

Request Body

Parameter Type Description
response_type string Must be set to token
redirect_uri string This is a callback URI which determines where the response is sent. The value of this parameter must exactly match one of the URIs you have provided for your app upon registration
client_id string Identifier (key) of a client application
state string Client state. Returned back to the client at the end of the flow
brand_id string Brand identifier. If it is not provided in request, server will try to determine brand from client app profile. The default value is '1210' - RingCentral US
display 'page' | 'popup' | 'touch' | 'mobile' Style of login form. The default value is 'page'. The 'popup' and 'touch' values are featured for mobile applications
prompt 'login' | 'sso' | 'consent' | 'none' Specifies which login form will be displayed. Space-separated set of the following values: 'login' - official RingCentral login form, 'sso' - Single Sign-On login form, 'consent' - form to show the requested scope and prompt user for consent. Either 'login' or 'sso' (or both) must be specified. Please note: The value must be set to 'none' for all requests except for the first one
ui_locales string Localization code of a language. Overwrites 'localeId' parameter value
localeId string Localization code of a language. Overwrites 'Accept-Language' header value
ui_options 'hide_logo' | '-hide_tos' | 'hide_remember_me' | 'external_popup' | 'old_ui' User interface options data

Response Body

Link to a login page location.

After successful user login the browser will pass the hash fragment with access token directly to the application redirect URI.

Example

Request example

GET https://api.ringcentral.com/restapi/oauth/authorize?response_type=token&client_id=9oQlL98tTQGhpdqq5KB60Q&state=xyz&prompt=login%20consent&
redirect_uri=http%3A%2F%2Fmyapp%2Eexample%2Ecom%2Foauthredirect HTTP/1.1

Response example

HTTP/1.1 302 Found

Location:
https://service.ringcentral.com/mobile/loginDispatcher?session=2008293087662283621&clientId=9oQlL98tTQGhpdqq5KB60Q&state=xyz
&brandId=1210&appUrlScheme=http%3A%2F%2Fmyapp%2Eexample%2Ecom%2Foauthredirect&localeId=en_US&display=page&prompt=login%20consent&hideNavigationBar=true 

Callback Request

http://myapp.example.com/oauthredirect#access_token=tuyt43gjhg6u54uiy6iuyhh3k45jh34k5hO6884534jk5hkh83yh3kj5h348y59345ikh&token_type=bearer&state=xyz&expires_in=3600 

Get Token

URI

/restapi/oauth/token

This endpoint enables client applications to get access tokens for making API requests. Requests to this endpoint must be authenticated with HTTP Basic scheme using the application key and application secret as login and password, correspondingly.

Authorization Code Flow

Since 1.0.19 (Release 7.3)

Each time you call token endpoint using this flow a new client session starts. It is associated with the issued token pair: access token and refresh token, returned in response to this request. To continue the session you can refresh the obtained access token and refresh token as many times as you need, using Refresh Token flow or the same flow.

To start another client session you should call token endpoint using this flow again. Please consider that only 5 simultaneously active sessions per extension per application are supported. Thus if you exceed the number of sessions started per extension per application, the oldest one is ended.

Method

POST

API Group

Auth

Request Body

Parameter Type Description
grant_type string Must be set to authorization_code for authorization code flow
code string Authorization code
redirect_uri URI This is a callback URI which determines where the response is sent. The value of this parameter must exactly match one of the URIs you have provided for your app upon registration
access_token_ttl integer Access token lifetime in seconds; the possible values are from 600 sec (10 min) to 3600 sec (1 hour). The default value is 3600 sec. If the value specified exceeds the default one, the default value is set. If the value specified is less than 600 seconds, the minimum value (600 sec) is set
refresh_token_ttl integer Refresh token lifetime in seconds. The default value depends on the client application, but as usual it equals to 7 days. If the value specified exceeds the default one, the default value is applied

Response Body

Parameter Type Description
access_token string Access token to pass to subsequent API requests
expires_in integer Issued access token TTL (time to live), in seconds
refresh_token string Refresh token to get a new access token, when the issued one expires
refresh_token_expires_in integer Issued refresh token TTL (time to live), in seconds
scope string List of permissions allowed with this access token, white-space separated
token_type string Type of token. The only possible value supported is 'Bearer'. This value should be used when specifying access token in Authorization header of subsequent API requests
owner_id string Extension identifier

Example

Request example

POST /restapi/oauth/token 
Authorization: Basic 
RTI3RkI5QUE1MEY1NTU5MzFENkE5NjkzOTFEMGU0OTFDM0UyMjRXxBQUJfTVpHWk5lM29zNV

code=U0pDMDFQMDRQQVMwMnxBQUFGTVUyYURGYi0wUEhEZ2VLeGFiamFvZlNMQlZ5TExBUHBlZVpTSVlhWk
xYajg5aDA3UVJmZ3VHdTNOTk05YkR0MEw0RkhnMlRPdTZuMTJSdEYwUkZyZHBSNWtLUzlzc1V8eW1OWVhRf
FdnUW5QcExvYVhrN3lqY3p5NEJwWHc&grant_type=authorization_code&redirect_uri=https://www.example.com/myapp
             

Response example

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

{
"access_token" : "U1BCMDFUMDRKV1MwMXxzLFSvXdw5PHMsVLEn_MrtcyxUsw",
"token_type" : "bearer",
"expires_in" : 7199,
"refresh_token" : "U1BCMDFUMDRKV1MwMXxzLFL4ec6A0XMsUv9wLriecyxS_w",
"refresh_token_expires_in" : 604799,
"scope" : "AccountInfo CallLog ExtensionInfo Messages SMS",
"owner_id" : "256440016"
}

Password Flow

Since 1.0.4 (Release 5.13)

Each time you call token endpoint using this flow a new client session starts. It is associated with the issued token pair: access token and refresh token, returned in response to this request. To continue the session you can refresh the obtained access token and refresh token as many times as you need, using Refresh Token flow or the same flow.

To start another client session you should call token endpoint using this flow again. Please consider that only 5 simultaneously active sessions per extension per application are supported. Thus if you exceed the number of sessions started per extension per application, the oldest one is ended.

Method

POST

API Group

Auth

Request Header

The Content-Type header should be specified as application/x-www-form-urlencoded. Please note: Request body should be encoded appropriately. For example email john+doe@example.com as username parameter should be specified so - john%2Bdoe%40example.com.

Request Body

Parameter Type Description
grant_type string Must hold password value for Resource Owner Credentials flow. If client application is not authorized by the specified grant_type, response does not contain refresh_token and refresh_token_ttl attributes
access_token_ttl integer Access token lifetime in seconds; the possible values are from 600 sec (10 min) to 3600 sec (1 hour). The default value is 3600 sec. If the value specified exceeds the default one, the default value is set. If the value specified is less than 600 seconds, the minimum value (600 sec) is set
refresh_token_ttl integer Refresh token lifetime in seconds. The default value depends on the client application, but as usual it equals to 7 days. If the value specified exceeds the default one, the default value is applied. If client specifies refresh_token_ttl<=0, refresh token is not returned even if the corresponding grant type is supported
username string

Phone number (in E.164 format) or email address linked to account or extension. Please note: You cannot use one and the same email address for authorization on different extensions (even if they are assigned to different accounts)

extension string Extension short number. If company number is specified as a username, and extension is not specified, the server will attempt to authenticate client as main company administrator
password string User password
endpoint_id string Unique identifier of a client application. You can pass it in request according to pattern [a-zA-Z0-9_\-]{1,64}. Otherwise it is auto-generated by server. The value will be returned in response in both cases

Response Body

Token Info

Example 1

Phone number as a username

Request example

 POST /restapi/oauth/token HTTP/1.1
 Accept: application/json
 Content-Type: application/x-www-form-urlencoded
 Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==
 
 grant_type=password&username=18559100010&extension=101&password=121212
       

Response example

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

 {
   "access_token" : "U1BCMDFUMDRKV1MwMXxzLFSvXdw5PHMsVLEn_MrtcyxUsw",
   "token_type" : "bearer",
   "expires_in" : 7199,
   "refresh_token" : "U1BCMDFUMDRKV1MwMXxzLFL4ec6A0XMsUv9wLriecyxS_w",
   "refresh_token_expires_in" : 604799,
   "owner_id" : "256440016"
                }            
 

Example 2

Email address as a username

Request example

POST /restapi/oauth/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==
 
grant_type=password&username=john%2Bdoe%40example.com&password=121212

Response example

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

 {
   "access_token" : "U1BCMDFUMDRKV1MwMXxzLFSvXdw5PHMsVLEn_MrtcyxUsw",
   "token_type" : "bearer",
   "expires_in" : 7199,
   "refresh_token" : "U1BCMDFUMDRKV1MwMXxzLFL4ec6A0XMsUv9wLriecyxS_w",
   "refresh_token_expires_in" : 604799,
   "owner_id" : "256440016"
 }   

Refresh Token Flow

Since 1.0.4 (Release 5.13)

Each time you call token endpoint using this flow, you continue current client session, and receive a new token pair: access token and refresh token in response to this request. The old token pair immediately becomes inactive.

Method

POST

API Group

Auth

Request Body

Parameter Type Description
refresh_token string Previously issued refresh token
grant_type string Must hold refresh_token value
endpoint_id string Unique identifier of a client application. If not specified, the previously specified or auto-generated value is used by default

Response Body

Token Info

Example

Request example

 POST /restapi/oauth/token HTTP/1.1
 Accept: application/json
 Content-Type: application/x-www-form-urlencoded
 Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==

 refresh_token=BCMDFUMDRKV1MwMXx5d5dwzLFL4ec6U1A0XMsUv935527jghj48&grant_type=refresh_token
              

Response example

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

  {
     "access_token" : "U1BCMDFUMDRKV1MwMXxzLFSvXdw5PHMsVLEn_MrtcyxUsw",
     "token_type" : "bearer",
     "expires_in" : 7199,
     "refresh_token" : "U1BCMDFUMDRKV1MwMXxzLFL4ec6A0XMsUv9wLriecyxS_w",
     "refresh_token_expires_in" : 6048799,
     "scope" : "AccountInfo CallLog ExtensionInfo Messages SMS"
   
  }
                

Revoke Token

Since 1.0.5 (Release 5.14)

Revokes access/refresh token. Requests to this endpoint must be authenticated with HTTP Basic scheme using the application key and application secret as login and password, correspondingly.

Request Body

Parameter Type Description
token string Active access or refresh token to be revoked

Response Body

None

Example

Request example

POST /restapi/oauth/revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic M2ZmYjNlMThkZDU4ZDE1YTk2NTIwYmFmNzUzZjBiNzk6MzI5OWQ0NTg5NGU1Njg5ODllOTY1ZTFiMTk5MGU2OTI

token=U0pDMDFQMDFKV1MwMXwJ_W7L1fG4eGXBW9Pp-otywzriCw
            

Response example

HTTP/1.1 200 OK

API Versions

Base URL

URI

/restapi/

Get API Versions

Since 1.0.0

Returns current API version(s) and server info.

Method

GET

API Group

Light

Request Body

None

Response Body

Parameter Type Description
uri string Canonical URI of the API version
apiVersions Collection of Version Info API version data: link, number, release date
serverVersion string Server version
serverRevision string Server revision

Version Info

Parameter Type Description
uri string Canonical URI of API versions
versionString string Version of the RingCentral API
releaseDate string Release date of this version
uriString string URI part determining the current version

Example

Request example

GET /restapi/ HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUFWZmY4ZXoxMlhvSmlGdjlQc1

Response example

HTTP/1.1 200 OK
Date: Mon, 13 Oct 2014 13:24:10 GMT
RoutingKey: SJC01P01PAS01
Content-Type: application/json
Content-Language: en
Content-Length: 312

{
  "uri" : "https.../restapi/",
  "apiVersions" : [ {
    "uri" : "https.../restapi/v1.0",
    "versionString" : "1.0.14",
    "releaseDate" : "2014-10-31T00:00:00.000Z",
    "uriString" : "v1.0"
  } ],
  "serverVersion" : "7.0.0.551",
  "serverRevision" : "598ed4edcc56"
}            

API Version Info

URI

/restapi/{apiVersion}

Get Version Info

Since 1.0.0

Returns current API version info by apiVersion.

Method

GET

API Group

Light

Path Parameters

Parameter Type Description
apiVersion string API version to be requested, for example "v1.0"

Request Body

None

Response Body

Parameter Type Description
uri string Canonical URI of the version info resource
versionString string Version of the RingCentral API
releaseDate string Release date of this version
uriString string URI part determining the current version

Example

Request example

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

Response example

HTTP/1.1 200 OK
Date: Mon, 13 Oct 2014 13:57:02 GMT
RoutingKey: SJC01P01PAS01
Content-Type: application/json
Content-Language: en
Content-Length: 156

{
  "uri" : "https.../restapi/v1.0",
  "versionString" : "1.0.14",
  "releaseDate" : "2014-10-31T00:00:00.000Z",
  "uriString" : "v1.0"
}
                    

Account

Account Info

URI

/restapi/v1.0/account/{accountId}

Get Account Info

Since 1.0.0

Returns basic information about a particular RingCentral customer account.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session

Request Body

None

Response Body

Parameter Type Description
id string Internal identifier of an account
uri string Canonical URI of an account
mainNumber string Main phone number of a current account in E.164 format
operator Extension Info Operator's extension information. This extension will receive all calls and messages intended for the operator
partnerId string Additional account identifier, developed and applied by the client
serviceInfo Service Info Account service information, including brand, service plan and billing plan
setupWizardState 'NotStarted' | 'Incomplete' | 'Completed' Specifies account configuration wizard state (web service setup). The default value is 'NotStarted'
regionalSettings Regional Settings Account level region data (web service Auto-Receptionist settings)
status 'Confirmed' | 'Disabled' Status of the current account
statusInfo Status Info Status information (reason, comment, lifetime). Returned for 'Disabled' status only

Service Info

Parameter Type Description
uri string Canonical URI of a service info resource
billingPlan Billing Plan Info Information on account billing plan
brand Brand Info Information on account brand
servicePlan Service Plan Info Information on account service plan
targetServicePlan Target Service Plan Info Information on account target service plan

Billing Plan Info

Parameter Type Description
id string Internal identifier of a billing plan
name string Billing plan name
durationUnit 'Month' | 'Day' Duration period
duration string Number of duration units
type 'Initial' | 'Regular' | 'Suspended' | 'Trial' | 'TrialNoCC' | 'Free' Billing plan type
includedPhoneLines integer Count of phone lines included into account service plan

Brand Info

Parameter Type Description
id string Internal identifier of a brand
name string Brand name, for example 'RingCentral UK', 'ClearFax'
homeCountry Country Info Home country information

Country Info

Parameter Type Description
id string Internal identifier of a home country
uri string Canonical URI of a home country
name string Official name of a home country
isoCode string Country code according to the ISO standard, see ISO 3166
callingCode string Country calling code defined by ITU-T recommendations E.123 and E.164, see Calling Codes

Service Plan Info

Parameter Type Description
id string Internal identifier of a service plan
name string Name of a service plan
edition string Edition of a service plan

Target Service Plan Info

Parameter Type Description
id string Internal identifier of a target service plan
name string Name of a target service plan

Status Info

Parameter Type Description
comment string A free-form user comment, describing the status change reason
reason string Type of suspension

Example

Request example

GET /restapi/v1.0/account/612410004 HTTP/1.1
Authorization: Bearer UExBMDFUMDRQV1MwMXzq47-tLtp8ltajk78BuDxCDNYh_Q
Accept: application/json              

Response example

HTTP/1.1 200 OK

Content-Type: application/json; charset=UTF-8
Content-Length: 1226
 

{
   "uri": "https.../restapi/v1.0/account/12133895004",
   "id": 12133895004,
   "serviceInfo":    {
      "uri": "https:.../restapi/v1.0/account/12133895004/service-info",
      "brand":       {
         "id": "1210",
         "name": "RingCentral",
         "homeCountry":          {
            "id": "1",
            "uri": "https.../restapi/v1.0/dictionary/country/1",
            "name": "United States",
            "isoCode": "US",
            "callingCode": "1"
         }
      },
      "servicePlan":       {
         "id": "1216",
         "name": "Professional",
         "edition": "Unknown"
      },
      "billingPlan":       {
         "id": "159",
         "name": "Monthly",
         "durationUnit": "Month",
         "duration": 1,
         "type": "Regular",
         "includedPhoneLines": 100
      }
   },
   "operator":    {
      "uri": "https.../restapi/v1.0/account/12133895004/extension/12133895004",
      "id": 12133895004,
      "extensionNumber": "101"
   },
   "mainNumber": "+18772003451",
   "status": "Confirmed",
   "signupInfo":    {
      "tosAccepted": true,
      "signupState":       [
         "BillingEntered",
         "AccountCreated",
         "AccountConfirmed",
         "CreditCardApproved"
      ],
      "verificationReason": "Unknown"
   },
   "setupWizardState": "Completed",
   "regionalSettings":    {
      "timezone":       {
         "uri": "https.../restapi/v1.0/dictionary/timezone/58",
         "id": "58",
         "name": "US/Pacific",
         "description": "Pacific Time (US & Canada)",
         "bias": "-480"
      },
      "homeCountry":       {
         "uri": "https.../restapi/v1.0/dictionary/country/1",
         "id": "1",
         "name": "United States"
      },
      "language":       {
         "id": "1033",
         "name": "English (United States)",
         "localeCode": "en-US"
      },
      "greetingLanguage":       {
         "id": "1033",
         "name": "English (United States)",
         "localeCode": "en-US"
      },
      "formattingLocale":       {
         "id": "1033",
         "name": "English (United States)",
         "localeCode": "en-US"
      },
      "timeFormat": "12h"
   }
}

Account Business Address

URI

/restapi/v1.0/account/{accountId}/business-address

Get Account Business Address

Since 1.0.10 (Release 6.2)

Returns the business address of account company.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session

Request Body

None

Response Body

Account Info

Example

Request example

GET /restapi/v1.0/account/1215058004/business-address HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFTU5WZlgwT

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 348

{
  "uri" : "https.../restapi/v1.0/account/1215058004/business-address",
  "businessAddress" : {
    "street" : "13 Elm Street",
    "city" : "Foster City",
    "state" : "CA",
    "zip" : "94404",
    "country" : "United States"
  },
  "company" : "MyCompany Inc.",
  "email" : "firstname.lastname@mycompany.com"
}       

Account Phone Numbers

URI

/restapi/v1.0/account/{accountId}/phone-number

Get Account Phone Numbers

Since 1.0.2

Returns the list of phone numbers assigned to RingCentral customer account. Both company-level and extension-level numbers are returned.

Method

GET

API Group

Heavy

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session

Query Parameters

Parameter Type Description
page integer Indicates the page number to retrieve. Only positive number values are allowed. Default value is '1'
perPage integer Indicates the page size (number of items). If not specified, the value is '100' by default
usageType 'CompanyNumber' | 'MainCompanyNumber' | 'AdditionalCompanyNumber' | 'DirectNumber' | 'CompanyFaxNumber' | 'ForwardedNumber' | 'ForwardedCompanyNumber' Usage type of a phone number

Request Body

None

Response Body

Property Type Description
records Collection of Phone Number Info List of account phone numbers
paging Paging Info Information on paging
navigation Navigation Info Information on navigation

Example

Request example

GET /restapi/v1.0/account/~/phone-number HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFKV1MwMXz6J_ixC7_yYvon-KUZ31Lx-if4rw

Response example

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

{
  "uri" : ".../account/754224008/phone-number?usageType=DirectNumber&page=1&perPage=100",
  "records" : [ {
    "id" : 281162008,
    "phoneNumber" : "+18559100010",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "CompanyNumber"
  }, {
    "id" : 284652008,
    "phoneNumber" : "+18559103500",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754226008",
      "id" : 754226008,
      "extensionNumber" : "102"
    }
  }, {
    "id" : 284653008,
    "phoneNumber" : "+18559103501",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754227008",
      "id" : 754227008,
      "extensionNumber" : "103"
    }
  }, {
    "id" : 284654008,
    "phoneNumber" : "+18559103502",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754228008",
      "id" : 754228008,
      "extensionNumber" : "104"
    }
  }, {
    "id" : 284655008,
    "phoneNumber" : "+18559103503",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754229008",
      "id" : 754229008,
      "extensionNumber" : "105"
    }
  }, {
    "id" : 284656008,
    "phoneNumber" : "+18559103504",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754230008",
      "id" : 754230008,
      "extensionNumber" : "106"
    }
  }, {
    "id" : 284657008,
    "phoneNumber" : "+18559103505",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754231008",
      "id" : 754231008,
      "extensionNumber" : "107"
    }
  }, {
    "id" : 284658008,
    "phoneNumber" : "+18559103506",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754232008",
      "id" : 754232008,
      "extensionNumber" : "108"
    }
  }, {
    "id" : 284659008,
    "phoneNumber" : "+18559103507",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754233008",
      "id" : 754233008,
      "extensionNumber" : "109"
    }
  }, {
    "id" : 341898008,
    "phoneNumber" : "+12056770024",
    "paymentType" : "Local",
    "location" : "Chelsea, AL",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754226008",
      "id" : 754226008,
      "extensionNumber" : "102"
    }
  }, {
    "id" : 341903008,
    "phoneNumber" : "+12056770029",
    "paymentType" : "Local",
    "location" : "Chelsea, AL",
    "type" : "VoiceFax",
    "usageType" : "DirectNumber",
    "extension" : {
      "uri" : ".../account/754224008/extension/754227008",
      "id" : 754227008,
      "extensionNumber" : "103"
    }
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 100,
    "totalElements" : 11,
    "pageStart" : 0,
    "pageEnd" : 10
  },
  "navigation" : {
    "firstPage" : {
      "uri" : ".../account/754224008/phone-number?usageType=DirectNumber&page=1&perPage=100"
    },
    "lastPage" : {
      "uri" : ".../account/754224008/phone-number?usageType=DirectNumber&page=1&perPage=100"
    }
  }
}

Account Phone Number

URI

/restapi/v1.0/account/{accountId}/phone-number/{phoneNumberId}

Get Phone Number(s) by ID

Since 1.0.2

Returns the phone number(s) belonging to a certain account or extension by phoneNumberId(s). Batch request is supported.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
phoneNumberId string Internal identifier of a phone number

Request Body

None

Response Body

Phone Number Info

Example

Request example

GET /restapi/v1.0/account/400151109008/phone-number/400554025008 HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMXzL-t9eGDjdrzwP1m29blNa_s10vQ

Response example

HTTP/1.1 200, OK
Content-Type: application/json
{
 "id": 400554025008,
 "uri": ".../restapi/v1.0/account/400151109008/phone-number/400554025008"
 "phoneNumber": "+16505550102",
 "paymentType": "Local", 
 "location": "Pleasanton, CA",
 "type": "VoiceFax",
 "usageType": "DirectNumber",
 "extension": {
   "uri": ".../restapi/v1.0/account/400151109008/extension/203498239454",
   "id": 22034982394,
   "extensionNumber": "123"
 }
} 

Extension

Extension List

URI

/restapi/v1.0/account/{accountId}/extension

Get Extension List

Since 1.0.0

Returns the list of extensions created for a particular account. All types of extensions are included in this list.

Method

GET

API Group

Medium

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session

Query Parameters

Parameter Type Description
page integer Indicates the page number to retrieve. Only positive number values are allowed. Default value is '1'
perPage integer Indicates the page size (number of items). If not specified, the value is '100' by default.
status 'Enabled' | 'Disabled' | 'NotActivated' | 'Unassigned' Extension current state. Multiple values are supported. If 'Unassigned' is specified, then extensions without extensionNumber are returned. If not specified, then all extensions are returned
type 'User' | 'FaxUser' | 'VirtualUser' | 'DigitalUser' | 'Department' | 'Announcement' | 'Voicemail' | 'SharedLinesGroup' | 'PagingOnly' | 'IvrMenu' | 'ApplicationExtension' | 'ParkLocation' | 'Limited' Extension type. Multiple values are supported

Request Body

None

Response Body

Property Type Description
records Collection of Extension Info List of extensions with extension information
navigation Navigation Info Information on navigation
paging Paging Info Information on paging

Navigation Info

Parameter Type Description
firstPage string Canonical URI for the first page of the list
nextPage string Canonical URI for the next page of the list
previousPage string Canonical URI for the previous page of the list
lastPage string Canonical URI for the last page of the list

Paging Info

Parameter Type Description
page integer The current page number. 1-indexed, so the first page is 1 by default. May be omitted if result is empty (because non-existent page was specified or perPage=0 was requested)
perPage integer Current page size, describes how many items are in each page. Default value is 100. Maximum value is 1000. If perPage value in the request is greater than 1000, the maximum value (1000) is applied
pageStart integer The zero-based number of the first element on the current page. Omitted if the page is omitted or result is empty
pageEnd integer The zero-based index of the last element on the current page. Omitted if the page is omitted or result is empty
totalPages integer The total number of pages in a dataset. May be omitted for some resources due to performance reasons
totalElements integer The total number of elements in a dataset. May be omitted for some resource due to performance reasons

Example

Request example

GET /restapi/v1.0/account/401836781008/extension?page=1&perPage=2 HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQUJFU3VOMlp2bjZFR2VwOWp4bXpl3bUE

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 2602

{
  "uri" : "https.../restapi/v1.0/account/401836781008/extension?page=1&perPage=2",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/401836781008/extension/401864056008",
    "id" : 401864056008,
    "extensionNumber" : "102",
    "contact" : {
      "firstName" : "Jane",
      "lastName" : "Smith",
      "email" : "jane.smith@mycompany.com",
      "emailAsLoginName" : true
    },
    "name" : "Jane Smith",
    "type" : "User",
    "status" : "Enabled",
    "permissions" : {
      "admin" : {
        "enabled" : false
      },
      "internationalCalling" : {
        "enabled" : true
      }
    },
    "profileImage" : {
      "uri" : "https.../restapi/v1.0/account/401836781008/extension/401864056008/profile-image"
    }
  }, {
    "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008",
    "id" : 401836781008,
    "extensionNumber" : "101",
    "contact" : {
      "firstName" : "John",
      "lastName" : "Smith",
      "company" : "MyCompany Inc.",
      "email" : "john.smith@mycompany.com",
      "businessPhone" : "+16025809302",
      "emailAsLoginName" : true
    },
    "name" : "John Smith",
    "type" : "User",
    "status" : "Enabled",
    "permissions" : {
      "admin" : {
        "enabled" : true
      },
      "internationalCalling" : {
        "enabled" : true
      }
    },
    "profileImage" : {
      "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008/profile-image",
      "etag" : "7a1decb8efda89d7c0acff42f061d99d",
      "contentType" : "image/gif",
      "lastModified" : "2016-02-26T09:29:45.316Z",
      "scales" : [ {
        "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008/profile-image/90x90"
      }, {
        "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008/profile-image/195x195"
      }, {
        "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008/profile-image/584x584"
      } ]
    }
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 2,
    "totalElements" : 2,
    "pageStart" : 0,
    "pageEnd" : 1
  },
  "navigation" : {
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/401836781008/extension?page=1&perPage=2"
    },
    "lastPage" : {
      "uri" : "https.../restapi/v1.0/account/401836781008/extension?page=1&perPage=2"
    }
  }
}

Extension Info

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}

Get Extension Info

Since 1.0.0

Returns basic information about a particular extension of an account.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

None

Response Body

Parameter Type Description
id string Internal identifier of an extension
uri string Canonical URI of an extension
contact Contact Info Contact detailed information
departments Department Info Information on department extension(s), to which the requested extension belongs. Returned only for user extensions, members of department, requested by single extensionId
extensionNumber string Number of extension
account Account Info Account of a requested extension. Returned for currently logged-in extension only
name string Extension user name
partnerId string For Partner Applications Internal identifier of an extension created by partner. The RingCentral supports the mapping of accounts and stores the corresponding account ID/extension ID for each partner ID of a client application. In request URIs partner IDs are accepted instead of regular RingCentral native IDs as path parameters using pid = XXX clause. Though in response URIs contain the corresponding account IDs and extension IDs. In all request and response bodies these values are reflected via partnerId attributes of account and extension
permissions Extension Permissions Extension permissions, corresponding to the Service Web permissions 'Admin' and 'InternationalCalling'
profileImage Profile Image Info Information on profile image
references Collection of Reference Info List of non-RC internal identifiers assigned to an extension
regionalSettings Regional Settings Extension region data (timezone, home country, language)
serviceFeatures Collection of Extension Service Feature Info Extension service features returned in response only when the logged-in user requests his/her own extension info, see also Extension Service Features
setupWizardState 'NotStarted' | 'Incomplete' | 'Completed' Specifies extension configuration wizard state (web service setup). The default value is 'NotStarted'
status 'Enabled' | 'Disabled' | 'NotActivated' | 'Unassigned' Extension current state
statusInfo Status Info Status information (reason, comment). Returned for 'Disabled' status only
type 'User' | 'FaxUser' | 'VirtualUser' | 'DigitalUser' | 'Department' | 'Announcement' | 'Voicemail' | 'SharedLinesGroup' | 'PagingOnly' | 'IvrMenu' | 'ApplicationExtension' | 'ParkLocation' | 'Limited' Extension type
callQueueInfo Call Queue Info For Department extension type only. Call queue settings

Contact Info

Parameter Type Description
firstName string For User extension type only. Extension user first name
lastName string For User extension type only. Extension user last name
company string Extension user company name
email string Email of extension user
businessPhone string Extension user contact phone number in E.164 format
businessAddress Contact Address Info Business address of extension user company
emailAsLoginName boolean If 'True' then contact email is enabled as login name for this user. The default value is 'False'
pronouncedName Pronounced Name Info Voice name data; the option ensures user's name is pronounced correctly by the system voice operator. The name can be spelled/recorded by user, or just taken as it is from the user profile
department string Extension user department, if any

Contact Address Info

Parameter Type Description
country string Country name of extension user company. Not returned for Address Book
state string State/province name of extension user company
city string City name of extension user company
street string Street address of extension user company
zip string Zip code of extension user company

Pronounced Name Info

Parameter Type Description
type 'Default' | 'TextToSpeech' | 'Recorded' Voice name type

Default - default extension name; first name and last name specified in user profile

TextToSpeech - custom text; user name spelled the way it sounds and specified by user

Recorded - custom audio; user name recorded in user's own voice (supported only for extension retrieval)

text string Custom text

Department Info

Parameter Type Description
id string Internal identifier of a department extension
uri string Canonical URI of a department extension
extensionNumber string Number of a department extension

Account Info

Parameter Type Description
id string Internal identifier of an account
uri string Canonical URI of an account

Extension Permissions

Parameter Type Description
admin Permission Info Admin permission
internationalCalling Permission Info International Calling permission

Permission Info

Parameter Type Description
enabled boolean Specifies if a permission is enabled or not

Profile Image Info

Parameter Type Description
uri string Link to a profile image. If an image is not uploaded for an extension, only uri is returned
etag string Identifier of an image
lastModified datetime The datetime when an image was last updated in ISO 8601 format, for example 2016-03-10T18:07:52.534Z
contentType string The type of an image
scales Collection of string List of URIs to profile images in different dimensions

Reference Info

Parameter Type Description
ref string Non-RingCentral identifier of an extension
type 'PartnerId' | 'CustomerDirectoryId' Type of external identifier

Regional Settings

Parameter Type Description
homeCountry Country Info Extension country information
timezone Timezone Info Extension timezone information
language Language Info User interface language data
greetingLanguage Greeting Language Info Information on language used for telephony greetings
formattingLocale Formatting Locale Info Formatting language preferences for numbers, dates and currencies
timeFormat '12h' | '24h' Time format setting. The default value is '12h'

Timezone Info

Parameter Type Description
id string Internal identifier of a timezone
uri string Canonical URI of a timezone
name string Short name of a timezone
description string Meaningful description of a timezone

Language Info

Parameter Type Description
id string Internal identifier of a language
uri string Canonical URI of a language
greeting boolean Indicates whether a language is available as greeting language
formattingLocale boolean Indicates whether a language is available as formatting locale
localeCode string Localization code of a language
name string Official name of a language
ui boolean Indicates whether a language is available as UI language

Greeting Language Info

Parameter Type Description
id string Internal identifier of a greeting language
localeCode string Localization code of a greeting language
name string Official name of a greeting language

Formatting Locale Info

Parameter Type Description
id string Internal identifier of a formatting language
localeCode string Localization code of a formatting language
name string Official name of a formatting language

Extension Service Feature Info

Parameter Type Description
enabled boolean Feature status; shows feature availability for an extension
featureName string Feature name, see all available values in Service Feature List
reason string Reason of limitation for a particular service feature. Returned only if the enabled parameter value is 'False', see Service Feature Limitations and Reasons. When retrieving service features for an extension, the reasons for the limitations, if any, are returned in response

Service Feature List

Feature Name Description
AccountDirectory Availability to use Account Directory API
AccountFederation Availability to federate this account with other accounts
AutomaticCallRecordingMute Muting of automatic recording
AutomaticInboundCallRecording Automatic recording of inbound calls
AutomaticOutboundCallRecording Automatic recording of outbound calls
BlockedMessageForwarding Disables forwarding of unencrypted fax and voicemail messages and specifies 'Open With' on Android devices
Calendar Local calendar integration
CallerIdControl CallerId is shown as 'Unknown' on softphone HUD menu for extensions which disallowed to pick up their calls
CallForwarding Forwarding a call to the number previously added to the extension forwarding list
CallPark Availability of Call Park feature. Phone call is transferred to the first non-busy system phone number extension (*800, *803, etc.) when the user puts it on hold
CallParkLocations Availability of Park Locations feature. Phone call is transferred to the selected phone number extension by the user when the user puts it on hold
CallSupervision Call supervision (monitoring) feature availability
CallQualitySurvey Showing call quality survey for a particular account
Conferencing Conference calling
DeveloperPortal Access to Developer Portal
DND DnD (Do not Disturb) mode
EmergencyCalling Availability to make emergency calls
EncryptionAtRest Data protection on mobile devices and softphones
ExternalDirectoryIntegration Availability of integration with external directory
Fax Sending and receiving Fax messages
FaxReceiving Receiving Fax messages
FreeSoftPhoneLines Availability to assign free phone line to a softphone. Does not work if 'LinkedSoftPhoneLines' feature is active
HDVoice Support of HD Voice compatible phones
HipaaCompliance HIPAA Compliance of the account. The Health Insurance Portability and Accountability Act is a standard for protecting sensitive patient data, providing physical, network and process security
Intercom Intercom calling. A soft key on the caller's phone is assigned for the Intercom function. By pressing it the user makes a call which is received by the destination number automatically via the loudspeaker. The callee is also able to switch the microphone on. Available for User extension types except Fax User
InternationalCalling Calling to international phone numbers
LinkedSoftphoneLines Availability to assign one of already purchased phone lines to a softphone. Does not work if 'FreeSoftPhoneLines' feature is active
MMS Sending and receiving multimedia messages
OnDemandCallRecording Recording a call on demand
Pager Sending and receiving Pager messages
PagerReceiving Receiving Pager messages
Paging Intercom calling without callback possibility; used when some information is to be delivered via the loud speaker to one or several paging groups. Available for User extension types except Fax User
PasswordAuth Availability to authorize by password
PromoMessage Displaying promotive messages in emails
Reports Viewing reports on call history
Presence Enables user extension to monitor other extensions' presence
RCTeams Availability to use messaging collaboration products (Glip)
RingOut Click-to-Call feature, allowing to make calls using the web on any IP, analog or mobile phone. When you initiate a call using RingOut, RingCentral will call your current location number. Once you answer, RingCentral dials a destination number for you. It is useful, when you do not want to dial a number manually or want to make a call with another phone using RingCentral number. Also it may be used by a third party (secretary) to initiate a call between you and another person
SalesForce Integration with Salesforce
SingleExtensionUI Indicates that current account can contain one and only one extension
SMS Sending and receiving SMS messages
SMSReceiving Receiving SMS messages
SoftPhoneUpdate Availability of softphone (RC desktop application) updates for end users
UserManagement User management
VideoConferencing Video conference calling
VoipCalling IP telephony
Voicemail Sending and receiving Voicemail messages
VoicemailToText Transcription of voicemail audio record to text message
WebPhone Web phone calls support

Service Feature Limitations and Reasons

Limitation Description Example
AccountTypeLimitation Principal account type limitation. Feature is not supported for account type Call Forwarding service feature is turned off on Fax tier
ExtensionTypeLimitation Principal extension type limitation. Feature is not supported for particular extension type (built-in Product restriction) 'Announcement Only' or 'Take Messages Only' extension types cannot send text messages, service feature SMS is disabled because of immutable extension type limitation and it is impossible to change the type of this extension
AccountLimitation Account limitation (service parameter setting at brand, tier or account level); can be changed only by RC Customer Support, or by upgrading to a different tier SMS service feature can be turned off for a particular account/tier
ExtensionLimitation

Extension limitation, requiring chargeable action; can be changed by Account Administrator, requires chargeable action (except tier upgrades)

Automatic Inbound Call Recording service feature can be turned off for a particular extension
InsufficientPermissions Extension limitation, resolution is not chargeable; can be changed by Account Administrator without extra charges International Calling is turned off if there is no corresponding extension permission

Status Info

Parameter Type Description
comment string A free-form user comment, describing the status change reason
reason string Type of suspension

Call Queue Info

Parameter Type Description
slaGoal integer

Target percentage of calls that must be answered by agents within the service level time threshold

slaThresholdSeconds integer Period of time in seconds that is considered to be an acceptable service level
includeAbandonedCalls boolean

If 'True' abandoned calls (hanged up prior to being served) are included into service level calculation

abandonedThresholdSeconds integer Period of time in seconds specifying abandoned calls duration - calls that are shorter will not be included into the calculation of service level.; zero value means that abandoned calls of any duration will be included into calculation

Example 1

For Enabled, Disabled or NotActivated extensions the same response is returned

Request example

GET /restapi/v1.0/account/401836781008/extension/401836781008 HTTP/1.1
Accept: application/json
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQUJFU3VOMlp2bjZFR2VwOWp4bXpkODh4RS14WnoyT1

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008",
  "id" : 401836781008,
  "extensionNumber" : "101",
  "account" : {
    "uri" : "https.../restapi/v1.0/account/401836781008",
    "id" : "401836781008"
  },
  "contact" : {
    "firstName" : "John",
    "lastName" : "Smith",
    "company" : "MyCompany Inc.",
    "email" : "john.smith@mycompany.com",
    "businessPhone" : "+16025809302",
    "businessAddress" : {
      "street" : "13 Elm Street",
      "city" : "Foster City",
      "zip" : "94404",
      "country" : "United States"
    },
   "emailAsLoginName" : true,    
   "pronouncedName" : {
      "type" : "Default",
      "text" : "John Smith"
    }
  },
  "name" : "Jane Smith",
  "type" : "User",
  "status" : "Enabled",
  "serviceFeatures" : [ {
    "featureName" : "MMS",
    "enabled" : true
  }, {
    "featureName" : "AutomaticCallRecordingMute",
    "enabled" : false
  }, {
    "featureName" : "SMS",
    "enabled" : true
  }, {
    "featureName" : "Intercom",
    "enabled" : true
  }, {
    "featureName" : "SoftPhoneUpdate",
    "enabled" : true
  }, {
    "featureName" : "Presence",
    "enabled" : true
  }, {
    "featureName" : "SMSReceiving",
    "enabled" : true
  }, {
    "featureName" : "VideoConferencing",
    "enabled" : true
  }, {
    "featureName" : "Calendar",
    "enabled" : true
  }, {
    "featureName" : "DND",
    "enabled" : true
  }, {
    "featureName" : "Conferencing",
    "enabled" : true
  }, {
    "featureName" : "OnDemandCallRecording",
    "enabled" : true
  }, {
    "featureName" : "VoipCalling",
    "enabled" : true
  }, {
    "featureName" : "Reports",
    "enabled" : true
  }, {
    "featureName" : "AccountFederation",
    "enabled" : false
  }, {
    "featureName" : "EmergencyCalling",
    "enabled" : false
  }, {
    "featureName" : "PasswordAuth",
    "enabled" : true
  }, {
    "featureName" : "LinkedSoftphoneLines",
    "enabled" : false
  }, {
    "featureName" : "CallerIdControl",
    "enabled" : false
  }, {
    "featureName" : "InternationalCalling",
    "enabled" : false
  }, {
    "featureName" : "RCTeams",
    "enabled" : true
  }, {
    "featureName" : "BlockedMessageForwarding",
    "enabled" : false
  }, {
    "featureName" : "AutomaticOutboundCallRecording",
    "enabled" : true
  }, {
    "featureName" : "FaxReceiving",
    "enabled" : true
  }, {
    "featureName" : "Paging",
    "enabled" : false
  }, {
    "featureName" : "UserManagement",
    "enabled" : false
  }, {
    "featureName" : "SingleExtensionUI",
    "enabled" : false
  }, {
    "featureName" : "FreeSoftPhoneLines",
    "enabled" : true
  }, {
    "featureName" : "CallQualitySurvey",
    "enabled" : false
  }, {
    "featureName" : "CallPark",
    "enabled" : true
  }, {
    "featureName" : "AutomaticInboundCallRecording",
    "enabled" : true
  }, {
    "featureName" : "Pager",
    "enabled" : true
  }, {
    "featureName" : "VoicemailToText",
    "enabled" : true
  }, {
    "featureName" : "HDVoice",
    "enabled" : true
  }, {
    "featureName" : "Voicemail",
    "enabled" : true
  }, {
    "featureName" : "CallForwarding",
    "enabled" : true
  }, {
    "featureName" : "HipaaCompliance",
    "enabled" : false
  }, {
    "featureName" : "AccountDirectory",
    "enabled" : false
  }, {
    "featureName" : "DeveloperPortal",
    "enabled" : true
  }, {
    "featureName" : "Fax",
    "enabled" : true
  }, {
    "featureName" : "PagerReceiving",
    "enabled" : true
  }, {
    "featureName" : "SalesForce",
    "enabled" : true
  }, {
    "featureName" : "RingOut",
    "enabled" : true
  }, {
    "featureName" : "EncryptionAtRest",
    "enabled" : false
  }, {
    "featureName" : "WebPhone",
    "enabled" : false
  }, {
    "featureName" : "CallSupervision",
    "enabled" : true
  }, {
    "featureName" : "CallParkLocations",
    "enabled" : true
   }, {
    "featureName" : "PromoMessage",
    "enabled" : true
  },{
    "featureName" : "ExternalDirectoryIntegration",
    "enabled" : false
  }],
  "regionalSettings" : {
    "timezone" : {
      "uri" : "https.../restapi/v1.0/dictionary/timezone/14",
      "id" : "14",
      "name" : "Europe/Moscow",
      "description" : "Moscow, St. Petersburg, Volgograd"
    },
    "homeCountry" : {
      "uri" : "https.../restapi/v1.0/dictionary/country/1",
      "id" : "1",
      "name" : "United States",
      "isoCode" : "US",
      "callingCode" : "1"
    },
    "language" : {
      "id" : "1033",
      "name" : "English (United States)",
      "localeCode" : "en-US"
    },
    "greetingLanguage" : {
      "id" : "1033",
      "name" : "English (United States)",
      "localeCode" : "en-US"
    },
    "formattingLocale" : {
      "id" : "1033",
      "name" : "English (United States)",
      "localeCode" : "en-US"
    },
   "timeFormat" : "12h"
  },
  "setupWizardState" : "Completed",
  "permissions" : {
    "admin" : {
      "enabled" : true
    },
    "internationalCalling" : {
      "enabled" : true
    }
  },
  "profileImage" : {
    "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008/profile-image",
    "etag" : "7a1decb8efda89d7c0acff42f061d99d",
    "contentType" : "image/gif",
    "lastModified" : "2016-02-26T09:29:45.316Z",
    "scales" : [ {
      "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008/profile-image/90x90"
    }, {
      "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008/profile-image/195x195"
    }, {
      "uri" : "https.../restapi/v1.0/account/401836781008/extension/401836781008/profile-image/584x584"
    } ]
  }
}

Example 2

For Unassigned extensions only the subset of attributes is returned:

Request example

GET /restapi/v1.0/account/3236453004/extension/3236457004 HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFR3FqR1o5M29O

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 306

{
  "uri" : "https.../restapi/v1.0/account/3236453004/extension/3236457004",
  "id" : 3236457004,
  "type" : "User",
  "status" : "Unassigned",
  "profileImage" : {
    "uri" : "https.../restapi/v1.0/account/3236453004/extension/3236457004/profile-image",
   }
}

Extension Caller ID

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/caller-id

Get Extension Caller ID

Since 1.0.28 (Release 8.4)

Access level: Beta

Returns information on an outbound caller ID of a current extension.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

None

Response Body

Parameter Type Description
uri string Canonical URL of an extension caller ID resource
byDevice Collection of Caller ID by Device Info Caller ID settings by device
byFeature Collection of Caller ID by Feature Info Caller ID settings by feature

Caller ID by Device Info

Parameter Type Description
device Device Info Device information
callerId Caller ID by Device Caller ID settings by a particular device

Device Info

Parameter Type Description
id string Internal identifier of a device
uri string Link to a device resource
name string Name of a device

Caller ID by Device

Parameter Type Description
type 'PhoneNumber' | 'Blocked' If 'PhoneNumber' value is specified, then a certain phone number is shown as a caller ID when calling from this device. If 'Blocked' value is specified, then a caller ID is hidden. The default is 'PhoneNumber'
phoneInfo Phone Info Phone number information

Caller ID by Feature Info

Parameter Type Description
feature 'RingOut' | 'RingMe' | 'CallFlip' | 'FaxNumber' | 'AdditionalSoftphone' | 'Alternate' Feature name
callerId Caller ID by Feature Caller ID settings by a particular feature

Caller ID by Feature

Parameter Type Description
type 'PhoneNumber' | 'Blocked' | 'CurrentLocation' If 'PhoneNumber' value is specified, then a certain phone number is shown as a caller ID when using this telephony feature. If 'Blocked' value is specified, then a caller ID is hidden. The value 'CurrentLocation' can be specified for 'RingOut' feature only. The default is 'PhoneNumber'
phoneInfo Phone Info Phone number information

Phone Info

Parameter Type Description
id string Internal identifier of a phone number
uri string Link to a phone number resource
phoneNumber string Phone number in E.164 (with '+' sign) format

Example

Request example

GET /restapi/v1.0/account/400338298008/extension/400338298008/caller-id HTTP/1.1

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/400338298008/extension/400338298008/caller-id",
  "byFeature" : [ {
    "feature" : "FaxNumber",
    "callerId" : {
      "type" : "PhoneNumber",
      "phoneInfo" : {
        "uri" : "http.../restapi/v1.0/account/phone-number/400338298008",
        "id" : "400859646008",
        "phoneNumber" : "+18662020433"
      }
    }
  }, {
    "feature" : "CallFlip",
    "callerId" : {
      "type" : "PhoneNumber",
      "phoneInfo" : {
        "uri" : "http:.../restapi/v1.0/account/phone-number/400338298008",
        "id" : "400859646008",
        "phoneNumber" : "+18662020433"
      }
    }
  }, {
    "feature" : "RingOut",
    "callerId" : {
      "type" : "PhoneNumber",
      "phoneInfo" : {
        "uri" : "http:.../restapi/v1.0/account/phone-number/400338298008",
        "id" : "400859646008",
        "phoneNumber" : "+18662020433"
      }
    }
  }, {
    "feature" : "RingMe",
    "callerId" : {
      "type" : "PhoneNumber",
      "phoneInfo" : {
        "uri" : "http.../restapi/v1.0/account/phone-number/400338298008",
        "id" : "400859646008",
        "phoneNumber" : "+18662020433"
      }
    }
  }, {
    "feature" : "Alternate",
    "callerId" : { }
  } ]
}

Update Extension Caller ID

Since 1.0.28 (Release 8.4)

Updates outbound caller ID information of a current extension.

Method

PUT

API Group

Medium

Required Permissions

Permission Description
EditExtensions Viewing and updating my extension info (includes extension name, number, email and phone number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

Parameter Type Description
uri string Canonical URL of an extension caller ID resource
byDevice Collection of Caller ID by Device Info Caller ID settings by device
byFeature Collection of Caller ID by Feature Info Caller ID settings by feature

Caller ID by Device Info

Parameter Type Description
device Device Info Device information
callerId Caller ID by Device Caller ID settings by a particular device

Device Info

Parameter Type Description
id string Internal identifier of a device

Caller ID by Device

Parameter Type Description
type 'PhoneNumber' | 'Blocked' If 'PhoneNumber' value is specified, then a certain phone number is shown as a caller ID when calling from this device. If 'Blocked' value is specified, then a caller ID is hidden. The default is 'PhoneNumber'
phoneInfo Phone Info Phone number information

Caller ID by Feature Info

Parameter Type Description
feature 'RingOut' | 'RingMe' | 'CallFlip' | 'FaxNumber' | 'AdditionalSoftphone' | 'Alternate' Feature name
callerId Caller ID by Feature Caller ID settings by a particular feature

Caller ID by Feature

Parameter Type Description
type 'PhoneNumber' | 'Blocked' | 'CurrentLocation' If 'PhoneNumber' value is specified, then a certain phone number is shown as a caller ID when using this telephony feature. If 'Blocked' value is specified, then a caller ID is hidden. The value 'CurrentLocation' can be specified for 'RingOut' feature only. The default is 'PhoneNumber'
phoneInfo Phone Info Phone number information

Phone Info

Parameter Type Description
id string Internal identifier of a phone number

Response Body

Extension Caller ID Info

Example

Request example

PUT /restapi/v1.0/account/~/extension/~/caller-id

{
  "byDevice": [ {
    "device": { "id": "11111111" },
    "callerId": {
      "phoneInfo": { "id": "22222222" }
    }
  } ],
  "byFeature": [ {
    "feature": "CallFlip"
    "callerId": {
      "phoneInfo": { "id": "33333333" }
    }
  } ]
}

Response example

HTTP 200 OK

{
  "uri": "https.../restapi/v1.0/account/444444444/extension/55555555/caller-id",
"byDevice": [ {
    "device": { 
      "id": "11111111",
      "uri": "https.../restapi/v1.0/account/444444444/device/111111111",
      "name": "John Smith's Cisco SPA-303"
    },
    "callerId": {
      "type": "PhoneNumber",
      "phoneInfo": { 
        "id": "22222222",
        "uri": "https.../restapi/v1.0/account/444444444/extension/55555555/phone-number/22222222",
         "phoneNumber": "+16505138862"
      }
    }
  } ],
  "byFeature": [ {
    "feature": "RingOut",
    "callerId": {
    "type": "CurrentLocation"
    }
  }, {
    "feature": "RingMe",
    "type": "PhoneNumber",
    "callerId": {
      "phoneInfo": { 
        "id": "33333333",
        "uri": "https.../restapi/v1.0/account/444444444/extension/55555555/phone-number/22222222",
        "phoneNumber": "+16503456789"
      }
    }
  }, {
    "feature": "CallFlip",
    "callerId": {
      "type": "Blocked",
    }
  }, {
    "feature": "FaxNumber",
    "callerId": {
      "type": "PhoneNumber",
      "phoneInfo": { 
        "id": "66666666",
        "uri": "https.../restapi/v1.0/account/444444444/extension/55555555/phone-number/66666666",
        "phoneNumber": "+16509876543"
      }
    }
  }, {
    "feature": "AdditionalSoftphone",
    "callerId": {
      "type": "PhoneNumber",
      "phoneInfo": { 
        "id": "33333333",
        "uri": "https.../restapi/v1.0/account/444444444/extension/55555555/phone-number/22222222",
        "phoneNumber": "+16503456789"
      }
    }
  }, {
    "feature": "Alternate",
    "callerId": { }
  } ]
}

Extension Phone Number List

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/phone-number

Get Extension Phone Number List

Since 1.0.2

Returns the list of phone numbers that are used by a particular extension, and can be filtered by the phone number type. The returned list contains all numbers which are directly mapped to a given extension plus the features and also company-level numbers which may be used when performing different operations on behalf of this extension.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Query Parameters

Parameter Type Description
usageType 'CompanyNumber' | 'MainCompanyNumber' | 'AdditionalCompanyNumber' | 'DirectNumber' | 'CompanyFaxNumber' | 'ForwardedNumber' | 'ForwardedCompanyNumber' Usage type of the phone number
page integer Indicates the page number to retrieve. Only positive number values are allowed. Default value is '1'
perPage integer Indicates the page size (number of items). If not specified, the value is '100' by default

Request Body

None

Response Body

Property Type Description
records Collection of Phone Number Info List of phone numbers
navigation Navigation Info Information on navigation
paging Paging Info Information on paging

Phone Number Info

Parameter Type Description
id integer Internal identifier of a phone number
country Country Info Brief information on a phone number country
extension Extension Info Information on the extension, to which the phone number is assigned. Returned only for account phone number list
features Collection of string Indicates phone number features. Returned only for extension phone number list. The supported values are:
  • 'CallerId' - specified if a phone number can be displayed as caller ID

  • 'SmsSender' - specified if sending of outbound SMS from this phone number is allowed

  • 'MmsSender' - specified if sending of outbound MMS from this phone number is allowed

label string Custom user name of a phone number, if any. Supported for numbers assigned to Auto-Receptionist, with usage type 'CompanyNumber'
location string Location (City, State). Filled for local US numbers
paymentType 'External' | 'TollFree' | 'Local' Payment type. 'External' is returned for forwarded numbers which are not terminated in the RingCentral phone system
phoneNumber string Phone number
status string Status of a phone number. If the value is 'Normal', the phone number is ready to be used. Otherwise it is an external number not yet ported to RingCentral
usageType 'CompanyNumber' | 'MainCompanyNumber' | 'AdditionalCompanyNumber' | 'DirectNumber' | 'CompanyFaxNumber' | 'ForwardedNumber' | 'ForwardedCompanyNumber' Usage type of a phone number
type 'VoiceFax' | 'FaxOnly' | 'VoiceOnly' Type of a phone number

Extension Info

Parameter Type Description
id string Internal identifier of an extension
uri string Canonical URI of an extension
extensionNumber string Number of department extension
partnerId string For Partner Applications Internal identifier of an extension created by partner. The RingCentral supports the mapping of accounts and stores the corresponding account ID/extension ID for each partner ID of a client application. In request URIs partner IDs are accepted instead of regular RingCentral native IDs as path parameters using pid = XXX clause. Though in response URIs contain the corresponding account IDs and extension IDs. In all request and response bodies these values are reflected via partnerId attributes of account and extension

Example

Request example

GET /restapi/v1.0/account/~/extension/~/phone-number?page=1&perPage=100&usageType=CompanyNumber HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFRGNoMU5VQW1oQmhnTkp2bTE5UlhpT0ZidGplN1dkV

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 1473

{
  "uri" : "https.../restapi/v1.0/account/2194945004/extension/2194945004/phone-number?usageType=CompanyNumber&page=1&perPage=100",
  "records" : [ {
    "id" : 267408004,
    "phoneNumber" : "+18883790003",
    "paymentType" : "TollFree",
    "type" : "VoiceOnly",
    "usageType" : "CompanyNumber",
    "features" : [ "CallerId" ],
    "status" : "Normal",
    "label" : "Company Number Label",
    "country" : {
      "uri" : "https.../restapi/v1.0/dictionary/country/1",
      "id" : "1",
      "name" : "United States"
    }
  }, {
    "id" : 267409004,
    "phoneNumber" : "+18883790004",
    "paymentType" : "TollFree",
    "type" : "VoiceFax",
    "usageType" : "CompanyNumber",
    "features" : [ "CallerId" ],
    "status" : "Normal",
    "country" : {
      "uri" : "https.../restapi/v1.0/dictionary/country/1",
      "id" : "1",
      "name" : "United States"
    }
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 100,
    "totalElements" : 2,
    "pageStart" : 0,
    "pageEnd" : 1
  },
  "navigation" : {
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/2194945004/extension/2194945004/phone-number?usageType=CompanyNumber&page=1&perPage=100"
    },
    "lastPage" : {
      "uri" : "https.../restapi/v1.0/account/2194945004/extension/2194945004/phone-number?usageType=CompanyNumber&page=1&perPage=100"
    }
  }
}

Extension Profile Image

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/profile-image

Get Extension Profile Image

Since 1.0.20 (Release 7.4)

Returns the extension profile image.

Method

GET

API Group

Medium

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

None

Response Body

Profile image of the specified size as binary data.

Example

Request example

GET /restapi/v1.0/account/401865412008/extension/401865412008/profile-image HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQUJFU3VOMlp2bjZFR2VwOWp4bXpkODhtdVR2

Response example

HTTP/1.1 200 OK
ETag: "c93721648d8f4714e24560d3179d4433"
Content-Type: image/jpeg
Content-Language: en-US
Content-Length: 771

<...binary data...>

Create Extension Profile Image

Since 1.0.20 (Release 7.4)

Returns the extension profile image.

Method

POST

API Group

High

Required Permissions

Permission Description
EditExtensions Viewing and updating my extension info (includes extension name, number, email and phone number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

Binary data image passed as a multipart.

Response Body

Binary data image.

Example

Request example

POST /restapi/v1.0/account/3262476004/extension/3262476004/profile-image HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFR3FqR1o5M29ONS1YaWd3c
Content-Type: multipart/form-data; boundary=pdxvZf8oX86wwlbOoPl0KtGHgwHZIVnI
Content-Length: 835

pdxvZf8oX86wwlbOoPl0KtGHgwHZIVnI
Content-Disposition: form-data; name="image"; filename="john_smith.gif"
Content-Type: image/gif
Content-Transfer-Encoding: binary

GIF89a.............,........@.......;
28

--pdxvZf8oX86wwlbOoPl0KtGHgwHZIVnI--

Response example

HTTP/1.1 200 OK
ETag: "c93721648d8f4714e24560d3179d4433"
Content-Type: image/jpeg
Content-Language: en-US
Content-Length: 771

<...binary data...>

Update Extension Profile Image

Since 1.0.20 (Release 7.4)

Updates the extension profile image.

Method

PUT

API Group

High

Required Permissions

Permission Description
EditExtensions Viewing and updating my extension info (includes extension name, number, email and phone number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

Binary data image passed as a multipart.

Response Body

Binary data image.

Example

Request example

PUT /restapi/v1.0/account/3262476004/extension/3262476004/profile-image HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFR3FqR1o5M29ONS1YaWd3c
Content-Type: multipart/form-data; boundary=pdxvZf8oX86wwlbOoPl0KtGHgwHZIVnI
Content-Length: 835

pdxvZf8oX86wwlbOoPl0KtGHgwHZIVnI
Content-Disposition: form-data; name="image"; filename="john_smith.gif"
Content-Type: image/gif
Content-Transfer-Encoding: binary

GIF89a.............,........@.......;
28

--pdxvZf8oX86wwlbOoPl0KtGHgwHZIVnI--

Response example

HTTP/1.1 204 No Content

Extension Scaled Profile Image

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/profile-image/{scaleSize}

Get Extension Profile Image

Since 1.0.20 (Release 7.4)

Returns the scaled profile image of an extension.

Method

GET

API Group

Medium

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session
scaleSize string Optional. Dimensions of a profile image which will be returned in response. The possible values are '90x90'/ '195x195' / '584x584'

Request Body

None

Response Body

Profile image of the specified size as binary data.

Example

Request example

GET /restapi/v1.0/account/401865412008/extension/401865412008/profile-image/90x90 HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQUJFU3VOMlp2bjZFR2VwOWp4bXpkODhtdVR2

Response example

HTTP/1.1 200 OK
ETag: "c93721648d8f4714e24560d3179d4433"
Content-Type: image/jpeg
Content-Language: en-US
Content-Length: 771

<...binary data...>

Department Member List

URI

/restapi/v1.0/account/{accountId}/department/{departmentId}/members

Get Department Member List

Since 1.0.2

Access level: Beta

Returns the list of department members.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
departmentId string Internal identifier of a Department extension (same as extensionId but only the ID of a department extension is valid)

Query Parameters

Parameter Type Description
page integer Indicates the page number to retrieve. Only positive number values are allowed. Default value is '1'
perPage integer Indicates the page size (number of items). If not specified, the value is '100' by default

Request Body

None

Response Body

Property Type Description
records Collection of Extension Info List of extensions belonging to a given department
navigation Navigation Info Information on navigation
paging Paging Info Information on paging

Example

Request example

GET /restapi/v1.0/account/~/department/754234008/members HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFKV1MwMXz6J_ixC7_yYvon-KUZ31Lx-if4rw

Response example

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

{
  "uri" : ".../account/754224008/department/754234008/members?page=1&perPage=100",
  "records" : [ {
    "uri" : ".../account/754224008/extension/754227008",
    "id" : 754227008,
    "extensionNumber" : "103"
  }, {
    "uri" : ".../account/754224008/extension/754226008",
    "id" : 754226008,
    "extensionNumber" : "102"
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 100,
    "totalElements" : 2,
    "pageStart" : 0,
    "pageEnd" : 1
  },
  "navigation" : {
    "firstPage" : {
      "uri" : ".../account/754224008/department/754234008/members?page=1&perPage=100"
    },
    "lastPage" : {
      "uri" : ".../account/754224008/department/754234008/members?page=1&perPage=100"
    }
  }
}

Edit Departments

URI

/restapi/v1.0/account/{accountId}/department/bulk-assign

Edit Department Members

Since 1.0.25 (Release 8.1)

Access level: Beta

Adds and/or removes multiple department members.

Method

POST

API Group

Heavy

Required Permissions

Permission Description
EditAccounts Viewing and updating user account info (including name, business name, address and phone number/account number)
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)
EditExtensions Viewing and updating user extension info (includes extension name, number, email and phone number, assigned phone numbers, devices and other extension settings)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
departmentId string Internal identifier of a Department extension (same as extensionId but only the ID of a department extension is valid)

Request Body

Parameter Type Description
items Collection of Department Members Info List of departments and their members to be updated

Department Members Info

Parameter Type Description
departmentId string Internal identifier of a department
removedExtensionIds Collection of string Collection of members (extensions) to be removed from a department
addedExtensionIds Collection of string Collection of members (extensions) to be added to a department

Response Body

None

Example

Request example

POST /restapi/v1.0/account/289481004/department/bulk-assign HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFRkljT3pjVlNGbETmZJTHc
Content-Type: application/json
Content-Length: 214

{
  "items": [
    {
      "departmentId": "289484004",   
      "addedExtensionIds": [
        "289481004", "289485004"
      ],
      "removedExtensionIds": [
        "289483004", "289487004"
      ]
    }
  ] 
}

Response example

HTTP/1.1 204 No Content

Answering Rules

Answering Rules List

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/answering-rule

Get Answering Rules List

Since 1.0.15 (Release 7.0)

Returns the extension answering rules.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

None

Response Body

Parameter Type Description
uri string Canonical URI of an answering rule resource
records Collection of Answering Rule Info List of answering rules
paging Paging Info Information on paging
navigation Navigation Info Information on navigation

Answering Rule Info

Parameter Type Description
uri string Canonical URI to the answering rule resource
id string Internal identifier of an asnwering rule
type 'BusinessHours' | 'AfterHours' | 'Custom' Type of an answering rule
name string Name of an answering rule specified by user
enabled boolean Specifies if an answering rule is active or inactive

Example

Request example

GET /restapi/v1.0/account/12843281004/extension/~/answering-rule HTTP/1.1

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule?page=1&perPage=100",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule/business-hours-rule",
    "id" : "business-hours-rule",
    "type" : "BusinessHours",
    "enabled" : true
  }, {
    "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule/24494102004",
    "id" : "24494102004",
    "type" : "Custom",
    "name" : "My Rule # 1",
    "enabled" : true
  }, {
    "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule/after-hours-rule",
    "id" : "after-hours-rule",
    "type" : "AfterHours",
    "enabled" : true
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 100,
    "totalElements" : 3,
    "pageStart" : 0,
    "pageEnd" : 2
  },
  "navigation" : {
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule?page=1&perPage=100"
    },
    "lastPage" : {
      "uri" : "https.../restapi/v1.0/account/12843281004/extension/12843281004/answering-rule?page=1&perPage=100"
    }
  }
}
 

Create Custom Answering Rule

Since 1.0.24 (Release 8.0)

Creates a custom answering rule for a particular caller ID.

Please note: At least one condition from the list below should be specified in the request body:

  1. callerId - phone number of a caller

  2. phoneNumber - RingCentral number that is called

  3. schedule - calling date and time

Method

POST

API Group

Medium

Required Permissions

Permission Description
EditExtensions Viewing and updating my extension info (includes extension name, number, email and phone number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

Parameter Type Description
enabled boolean Specifies if the rule is active or inactive. The default value is 'True'
type string Type of an answering rule, the supported value is 'Custom'
name string Name of an answering rule specified by user. Max number of symbols is 30
callers Collection of Callers Info Answering rule will be applied when calls are received from the specified caller(s)
calledNumbers Collection of Called Number Info Answering rule will be applied when calling the specified number(s)
schedule Schedule Info Schedule when an answering rule should be applied
callHandlingAction 'ForwardCalls' | 'UnconditionalForwarding' | 'AgentQueue' | 'TransferToExtension' | 'TakeMessagesOnly' | 'PlayAnnouncementOnly' Specifies how incoming calls should be forwarded. The default value for user extension type is 'ForwardCalls'. The default value for department (call queue) extension type is 'AgentQueue'
forwarding Forwarding Info Forwarding parameters. If the 'callHandlingAction' parameter value is set to 'ForwardCalls' - should be specified . The settings determine the forwarding numbers to which the call should be forwarded. If not specified in request, then the business-hours forwarding rules are set by default
unconditionalForwarding Unconditional Forwarding Info Unconditional forwarding parameters. Should be specified if the 'callHandlingAction' parameter value is set to 'UnconditionalForwarding'
queue Queue Info Queue settings applied for department (call queue) extension type, with the 'AgentQueue' value specified as a call handling action
voicemail Voicemail Info Specifies whether to take a voicemail and who should do it
greetings Collection of Greeting Info Greetings applied for an answering rule; only predefined greetings can be applied, see Dictionary Greeting List

Callers Info

Parameter Type Description
callerId string Phone number of a caller
name string Contact name of a caller

Called Number Info

Parameter Type Description
phoneNumber string Called phone number

Schedule Info

Parameter Type Description
weeklyRanges Weekly Schedule Info Weekly schedule. If specified, ranges cannot be specified
ranges Ranges Info Specific data ranges. If specified, weeklyRanges cannot be specified

Weekly Schedule Info

Parameter Type Description
monday Collection of Time Interval

Time intervals for a particular day

tuesday Collection of Time Interval Time intervals for a particular day
wednesday Collection of Time Interval Time intervals for a particular day
thursday Collection of Time Interval Time intervals for a particular day
friday Collection of Time Interval Time intervals for a particular day
saturday Collection of Time Interval Time intervals for a particular day
sunday Collection of Time Interval Time intervals for a particular day

Ranges Info

Parameter Type Description
from string

Date and time in format YYYY-MM-DD hh:mm

to string Date and time in format YYYY-MM-DD hh:mm

Time Interval

Parameter Type Description
from string Time in format hh:mm
to string Time in format hh:mm

Forwarding Info

Parameter Type Description
notifyMySoftPhones boolean Specifies if the first ring on desktop/mobile apps is enabled. The default value is 'True'
notifyAdminSoftPhones boolean Specifies if the administrator's softphone (desktop application) is notified before forwarding the incoming call to desk phones and forwarding numbers. The default value is 'True'
softPhonesRingCount integer Specifies delay between ring on apps and starting of a call forwarding. The default value is 1
ringingMode

'Sequentially' | 'Simultaneously'

Specifies the order in which forwarding numbers ring. 'Sequentially' means that forwarding numbers are ringing one at a time, in order of priority. 'Simultaneously' means that forwarding numbers are ringing all at the same time. The default value is 'Sequentially'

rules Collection of Rule Info Information on a call forwarding rule. By default includes all forwarding numbers used in default rule (business hours)

Rule Info

Parameter Type Description
index integer Forwarding number (or group) ordinal
ringCount integer Number of rings for a forwarding number (or group)
forwardingNumbers Collection of Forwarding Number Info Forwarding number (or group) data

Forwarding Number Info

Parameter Type Description
id string Internal identifier of a forwarding number

Unconditional Forwarding Info

Parameter Type Description
phoneNumber string Phone number to which the call is forwarded

Queue Info

Parameter Type Description
transferMode 'Rotating' | 'Simultaneous' | 'FixedOrder' Specifies how calls are transferred to group members. The default value is 'Rotating'
fixedOrderAgents Collection of Fixed Order Agent Ordered list of agents (department members). The default value is the list from business hours rule
holdAudioInterruptionMode 'Never' | 'WhenMusicEnds' | 'Periodically' Connecting audio interruption mode. The default value is 'Never' if holdAudioInterruptPeriod is not specified, otherwise the default value is 'Periodically'
holdAudioInterruptPeriod integer Connecting audio interruption message period in seconds, the possible values are from 1 to 60. Mandatory if interruption mode is set to 'Periodically'
agentTimeout integer Maximum time in seconds to wait for a call queue member before trying the next member. The possible values are from 10 to 300. The default value is 60
wrapUpTime integer Minimum post-call wrap up time in seconds before agent status is automatically set. The possible values are from 0 to 60. The default value is 15
holdTime integer Maximum hold time in seconds to wait for an available call queue member. The possible values are from 0 to 900. The default vale is 180
maxCallers integer Maximum count of callers on hold. The possible values are from 0 to 30. The default value is 10
maxCallersAction 'Voicemail' | 'Announcement' Action which should be taken if count of callers on hold exceeds the maximum. The default value is 'Voicemail'
transfer Transferred Extension Transfer settings applied for department (call queue) extension type with 'TransferToExtension' call handling action. It is possible to use any extension of a given account, including the extension of a department

Transferred Extension

Parameter Type Description
extension Extension Info Information on an agent (department member) extension

Extension Info

Parameter Type Description
id integer Internal identifier of an extension

Fixed Order Agent

Parameter Type Description
extension Extension Info Information on an agent (department member) extension
index integer Ordinal of an agent (department member)

Extension Info

Parameter Type Description
id string Internal identifier of an extension

Voicemail Info

Parameter Type Description
enabled boolean If 'True' then voicemails are allowed to be received. The default value is 'True'. For department (call queue) extension type the parameter is mandatory and must be set to 'True'
recipient Recipient Info Recipient data

Recipient Info

Parameter Type Description
id string Internal identifier of a recipient extension

Response Body

Answering Rule Info

Example 1

Request example

POST /restapi/v1.0/account/400430664008/extension/400430664008/answering-rule HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQURIZjAzWFFySGpMMHpFRXkyWTZCbVg2bHUzNUtm
Content-Type: application/json
Content-Length: 91

{
	"callers":[
		{"callerId": "+46843216868"
		},
		{"callerId": "+46843216860"
		}
	]
	
	}

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/400430664008/extension/400430664008/answering-rule/400592844008",
  "id" : "400592844008",
  "type" : "Custom",
  "name" : "My Rule 2",
  "enabled" : true,
  "callers" : [ {
    "callerId" : "46843216860"
  }, {
    "callerId" : "46843216868"
  } ],
  "callHandlingAction" : "ForwardCalls",
  "forwarding" : {
    "notifyMySoftPhones" : true,
    "notifyAdminSoftPhones" : false,
    "softPhonesRingCount" : 1,
    "ringingMode" : "Sequentially"
  },
  "voicemail" : {
    "enabled" : true,
    "recipient" : {
      "uri" : "https.../restapi/v1.0/account/400430664008/extension/400430664008",
      "id" : 400430664008
    }
  },
  "greetings" : [ {
    "type" : "Voicemail",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/65792",
      "id" : "65792",
      "name" : "Default"
    }
  }, {
    "type" : "Introductory",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66301",
      "id" : "66301",
      "name" : "None"
    }
  }, {
    "type" : "ConnectingAudio",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66310",
      "id" : "66310",
      "name" : "Acoustic"
    }
  }, {
    "type" : "ConnectingMessage",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/68867",
      "id" : "68867",
      "name" : "Default"
    }
  } ]
}

Example 2

Request example

POST /restapi/v1.0/account/400430664008/extension/400430664008/answering-rule HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQURIZjAzWFFySGpMMHpFRXkyWTZCbVg2bHUzNUHc
Content-Type: application/json
Content-Length: 798

{
    "schedule": {
        "weeklyRanges": {
            "tuesday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ],
            "friday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ],
            "thursday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ],
            "wednesday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ],
            "monday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ]
        }
    }
}

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 386

{
  "uri" : "https.../restapi/v1.0/account/400430664008/extension/400430664008/answering-rule/400604613008",
  "id" : "400604613008",
  "type" : "Custom",
  "name" : "My Rule 3",
  "enabled" : true,
  "schedule" : {
    "weeklyRanges" : {
      "monday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "tuesday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "wednesday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "thursday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "friday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ]
    }
  },
  "callHandlingAction" : "ForwardCalls",
  "forwarding" : {
    "notifyMySoftPhones" : true,
    "notifyAdminSoftPhones" : false,
    "softPhonesRingCount" : 1,
    "ringingMode" : "Sequentially"
  },
  "voicemail" : {
    "enabled" : true,
    "recipient" : {
      "uri" : "https.../restapi/v1.0/account/400430664008/extension/400430664008",
      "id" : 400430664008
    }
  }
}

Answering Rule

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/answering-rule/{ruleId}

Get Answering Rule by ID

Since 1.0.15 (Release 7.0)

Returns an answering rule by ID.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session
ruleId string Internal identifier of an answering rule. The value can be standard digital ID or specific ID - either business-hours-rule or after-hours-rule

Request Body

None

Response Body

Parameter Type Description
uri string Canonical URI to the answering rule resource
id string Internal identifier of an asnwering rule
type 'BusinessHours' | 'AfterHours' | 'Custom' Type of an answering rule
name string Name of an answering rule specified by user
enabled boolean Specifies if an answering rule is active or inactive
schedule Schedule Info Schedule when an answering rule should be applied
calledNumbers Collection of Called Number Info Answering rules are applied when calling to selected number(s)
callers Collection of Callers Info Answering rules are applied when calls are received from specified caller(s)
callHandlingAction 'ForwardCalls' | 'TakeMessagesOnly' | 'PlayAnnouncementOnly' | 'UnconditionalForwarding' Specifies how incoming calls are forwarded
forwarding Forwarding Info Forwarding parameters. Returned if 'ForwardCalls' is specified in 'callHandlingAction'. These settings determine the forwarding numbers to which the call will be forwarded
unconditionalForwarding Unconditional Forwarding Info Unconditional forwarding parameters. Returned if 'UnconditionalForwarding' is specified in 'callHandlingAction'
queue Queue Info Queue settings applied for department (call queue) extension type, with the 'AgentQueue' value specified as a call handling action
voicemail Voicemail Info Specifies whether to take a voicemail and who should do it
greetings Collection of Greeting Info Predefined greetings applied for an answering rule, see Dictionary Greeting List

Schedule Info

Parameter Type Description
weeklyRanges Weekly Schedule Info Weekly schedule. Not returned if ranges are specified
ranges Ranges Info Specific data ranges. Not returned if weeklyRanges are specified
ref 'BusinessHours' | 'AfterHours' The user's schedule specified for business hours or after hours; it can also be set/retrieved calling the corresponding method

Weekly Schedule Info

Parameter Type Description
monday Collection of Time Interval

Time intervals for a particular day

tuesday Collection of Time Interval Time intervals for a particular day
wednesday Collection of Time Interval Time intervals for a particular day
thursday Collection of Time Interval Time intervals for a particular day
friday Collection of Time Interval Time intervals for a particular day
saturday Collection of Time Interval Time intervals for a particular day
sunday Collection of Time Interval Time intervals for a particular day

Ranges Info

Parameter Type Description
from string

Date and time in format YYYY-MM-DD hh:mm

to string Date and time in format YYYY-MM-DD hh:mm

Time Interval

Parameter Type Description
from string Time in format hh:mm
to string Time in format hh:mm

Called Number Info

Parameter Type Description
phoneNumber string Called phone number

Callers Info

Parameter Type Description
callerId string Phone number of a caller
name string Contact name of a caller

Forwarding Info

Parameter Type Description
notifyMySoftPhones boolean Specifies if the user's softphone(s) are notified before forwarding the incoming call to desk phones and forwarding numbers
notifyAdminSoftPhones boolean For Internal Use Only. Specifies if the administrator's softphone is notified before forwarding the incoming call to desk phones and forwarding numbers. The default value is 'False'
softPhonesRingCount integer Number of rings before forwarding starts
ringingMode

'Sequentially' | 'Simultaneously'

Specifies the order in which forwarding numbers ring. 'Sequentially' means that forwarding numbers are ringing one at a time, in order of priority. 'Simultaneously' means that forwarding numbers are ring all at the same time

rules Collection of Rule Info Information on a call forwarding rule

Rule Info

Parameter Type Description
index integer Forwarding number (or group) ordinal
ringCount integer Number of rings for a forwarding number (or group)
forwardingNumbers Collection of Forwarding Number Info Forwarding number (or group) data

Forwarding Number Info

Parameter Type Description
uri string Link to a forwarding number resource
id string Internal identifier of a forwarding number
phoneNumber string Phone number to which the call is forwarded
label string Name of a forwarding number

Unconditional Forwarding Info

Parameter Type Description
phoneNumber string Phone number to which the call is forwarded

Queue Info

Parameter Type Description
transferMode 'Rotating' | 'Simultaneous' | 'FixedOrder' Specifies how calls are transferred to group members
fixedOrderAgents Collection of Fixed Order Agent Ordered list of agents (department members)
holdAudioInterruptionMode 'Never' | 'WhenMusicEnds' | 'Periodically' Connecting audio interruption mode
holdAudioInterruptPeriod integer Connecting audio interruption message period in seconds.
agentTimeout integer Maximum time in seconds to wait for a call queue member before trying the next member
wrapUpTime integer Minimum post-call wrap up time in seconds before agent status is automatically set
holdTime integer Maximum hold time in seconds to wait for an available call queue member
maxCallers integer Maximum count of callers on hold
maxCallersAction 'Voicemail' | 'Announcement' Action which should be taken if count of callers on hold exceeds the maximum
transfer Transferred Extension Transfer settings applied for department (call queue) extension type, with 'TransferToExtension' call handling action

Transferred Extension

Parameter Type Description
extension Extension Info Information on an agent (department member) extension

Extension Info

Parameter Type Description
id integer Internal identifier of an extension

Fixed Order Agent

Parameter Type Description
extension Extension Info Information on an agent (department member) extension
index integer Ordinal of an agent (department member)

Extension Info

Parameter Type Description
id string Internal identifier of an extension
uri string Link to an extension resource

Voicemail Info

Parameter Type Description
enabled boolean If 'True' then voicemails are allowed to be received
recipient Recipient Info Recipient data

Recipient Info

Parameter Type Description
uri string Link to a recipient extension resource
id string Internal identifier of a recipient extension

Greeting Info

Parameter Type Description
type 'Introductory' | 'Announcement' | 'ConnectingMessage' | 'ConnectingAudio' | 'Voicemail' | 'Unavailable' | 'InterruptPrompt' Type of a greeting, specifying the case when the greeting is played. See Greeting Types
usageType 'UserExtensionAnsweringRule' | 'DepartmentExtensionAnsweringRule' Usage type of a greeting, specifying if the greeting is applied to user extension or department extension
preset Preset Info Predefined greeting information

Preset Info

Parameter Type Description
uri string Link to a greeting resource
id string Internal identifier of greeting
name string Name of a greeting

Example 1

Get Custom Rule

Request example

GET /restapi/v1.0/account/934789004/extension/~/answering-rule/1553002004 HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUJFU3VOMlp2bjZFQmN4UnV6MF9QS1VJcU3c

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/934789004/extension/934789004/answering-rule/1553002004",
  "id" : "1553002004",
  "type" : "Custom",
  "name" : "My Rule #1",
  "enabled" : true,
  "callers" : [ {
    "callerId" : "46843216860"
  }, {
    "callerId" : "46843216868"
  } ],
  "callHandlingAction" : "ForwardCalls",
  "forwarding" : {
    "notifyMySoftPhones" : true,
    "notifyAdminSoftPhones" : false,
    "softPhonesRingCount" : 5,
    "ringingMode" : "Sequentially",
    "rules" : [ {
      "index" : 1,
      "ringCount" : 3,
      "forwardingNumbers" : [ {
        "uri" : "https.../restapi/v1.0/account/934789004/extension/934789004/forwarding-number/1253646004",
        "id" : "1253646004",
        "phoneNumber" : "+16500000001",
        "label" : "Work"
      } ]
    }, {
      "index" : 2,
      "ringCount" : 4,
      "forwardingNumbers" : [ {
        "uri" : "https.../restapi/v1.0/account/934789004/extension/934789004/forwarding-number/1253903004",
        "id" : "1253903004",
        "phoneNumber" : "+16500009001",
        "label" : "Home"
      } ]
    } ]
  },
  "voicemail" : {
    "enabled" : true,
    "recipient" : {
      "uri" : "https.../restapi/v1.0/account/934789004/extension/934789004",
      "id" : 934789004
    }
  },
  "greetings" : [ {
    "type" : "Voicemail",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/65792",
      "id" : "65792",
      "name" : "Default"
    }
  }, {
    "type" : "Introductory",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66301",
      "id" : "66301",
      "name" : "None"
    }
  }, {
    "type" : "ConnectingAudio",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66310",
      "id" : "66310",
      "name" : "Acoustic"
    }
  }, {
    "type" : "ConnectingMessage",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/68867",
      "id" : "68867",
      "name" : "Default"
    }
  } ]
}

Example 2

Get Business Hours Rule

Request example

GET /restapi/v1.0/account/2601711004/extension/~/answering-rule/business-hours-rule HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUJFU3VOMlp2bjZFSGY2SUZmcEdhNHQ3aGdTMUTXNYYW5NbXc

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 697

{
  "uri" : "https.../restapi/v1.0/account/2601711004/extension/2601711004/answering-rule/business-hours-rule",
  "id" : "business-hours-rule",
  "type" : "BusinessHours",
  "enabled" : true,
  "schedule" : {
    "ref" : "BusinessHours"
  },
  "callHandlingAction" : "ForwardCalls",
  "forwarding" : {
    "notifyMySoftPhones" : true,
    "notifyAdminSoftPhones" : false,
    "softPhonesRingCount" : 1,
    "ringingMode" : "Sequentially",
    "rules" : [ ]
  },
    "voicemail" : {
    "enabled" : true,
    "recipient" : {
      "uri" : "https.../restapi/v1.0/account/2601711004/extension/2601711004",
      "id" : 2601711004
      }
     },
   "greetings" : [ {
    "type" : "Voicemail",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/65792",
      "id" : "65792",
      "name" : "Default"
    }
  }, {
    "type" : "Introductory",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66301",
      "id" : "66301",
      "name" : "None"
    }
  }, {
    "type" : "ConnectingAudio",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66310",
      "id" : "66310",
      "name" : "Acoustic"
    }
  }, {
    "type" : "ConnectingMessage",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/68867",
      "id" : "68867",
      "name" : "Default"
    }
  } ]
 }

Update Custom Answering Rule by ID

Since 1.0.24 (Release 8.0)

Updates a custom answering rule for a particular caller ID.

Method

PUT

API Group

Medium

Required Permissions

Permission Description
EditExtensions Viewing and updating my extension info (includes extension name, number, email and phone number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session
ruleId string Internal identifier of an answering rule

Request Body

Parameter Type Description
enabled boolean Specifies if the answering rule is active or not
name string Custom name of an answering rule. The maximum number of characters is 64
callers Collection of Callers Info Answering rules are applied when calls are received from specified caller(s)
calledNumbers Collection of Called Number Info Answering rules are applied when calling to selected number(s)
schedule Schedule Info Schedule when an answering rule should be applied
callHandlingAction 'ForwardCalls' | 'UnconditionalForwarding' | 'AgentQueue' | 'TransferToExtension' | 'TakeMessagesOnly' | 'PlayAnnouncementOnly' Specifies how incoming calls should be forwarded. The default value for user extension type is 'ForwardCalls'. The default value for department (call queue) extension type is 'AgentQueue'
forwarding Forwarding Info Forwarding parameters. Specified if 'ForwardCalls' is specified in 'callHandlingAction'. These settings determine the forwarding numbers to which the call will be forwarded
unconditionalForwarding Unconditional Forwarding Info Unconditional forwarding parameters. Specified if 'UnconditionalForwarding' is specified in 'callHandlingAction'
queue Queue Info Queue settings applied for department (call queue) extension type, with the 'AgentQueue' value specified as a call handling action
greetings Collection of Greeting Info Greetings applied for an answering rule; only predefined greetings can be applied, see Dictionary Greeting List
voicemail Voicemail Info Specifies whether to take a voicemail and who should do it

Response Body

Answering Rule Info

Example

Request example

PUT /restapi/v1.0/account/400750830008/extension/400750830008/answering-rule/401166074008 HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQUJFU3VOMlp2bjZFR2VwOWp4bXpkODhxNjIwWHRaaRXc
Content-Type: application/json
Content-Length: 400

{
    "name": "My Rule #1",
    "enabled" : "true",
    "forwarding" : {
        "notifyMySoftPhones" : true,
        "softPhonesRingCount" : 5,
        "ringingMode" : "Sequentially",
        "rules": [
       {
         "index": 1,
         "ringCount" : 3,
         "forwardingNumbers": [ { "id": "401019103008" } ]
       }, 
       {
         "index": 2,
         "forwardingNumbers": [ { "id": "401019101008" } ]
       }
    ]
  },
  "greetings" : [ {
    "type" : "Voicemail",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/65792",
      "id" : "65792",
      "name" : "Default"
    }
  }, {
    "type" : "Introductory",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66301",
      "id" : "66301",
      "name" : "None"
    }
  }, {
    "type" : "ConnectingAudio",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66310",
      "id" : "66310",
      "name" : "Acoustic"
    }
  }, {
    "type" : "ConnectingMessage",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/68867",
      "id" : "68867",
      "name" : "Default"
    }
  } ]
}

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/400750830008/extension/400750830008/answering-rule/401166074008",
  "id" : "401166074008",
  "type" : "Custom",
  "name" : "My Rule #1",
  "enabled" : true,
  "calledNumbers" : [ {
    "phoneNumber" : "+13018680001"
  } ],
  "callHandlingAction" : "ForwardCalls",
  "forwarding" : {
    "notifyMySoftPhones" : true,
    "notifyAdminSoftPhones" : false,
    "softPhonesRingCount" : 5,
    "ringingMode" : "Sequentially",
    "rules" : [ {
      "index" : 1,
      "ringCount" : 3,
      "forwardingNumbers" : [ {
        "uri" : "https.../restapi/v1.0/account/400750830008/extension/400750830008/forwarding-number/401019103008",
        "id" : "401019103008",
        "phoneNumber" : "+16500000003",
        "label" : "Home"
      } ]
    }, {
      "index" : 2,
      "ringCount" : 4,
      "forwardingNumbers" : [ {
        "uri" : "https.../restapi/v1.0/account/400750830008/extension/400750830008/forwarding-number/401019101008",
        "id" : "401019101008",
        "phoneNumber" : "+16500000001",
        "label" : "Work"
      } ]
    } ]
  },
  "voicemail" : {
    "enabled" : true,
    "recipient" : {
      "uri" : "https.../restapi/v1.0/account/400750830008/extension/400750830008",
      "id" : 400750830008
    } 
    },
  "greetings" : [ {
    "type" : "Voicemail",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/65792",
      "id" : "65792",
      "name" : "Default"
    }
  }, {
    "type" : "Introductory",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66301",
      "id" : "66301",
      "name" : "None"
    }
  }, {
    "type" : "ConnectingAudio",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/66310",
      "id" : "66310",
      "name" : "Acoustic"
    }
  }, {
    "type" : "ConnectingMessage",
    "preset" : {
      "uri" : "https.../restapi/v1.0/dictionary/greeting/68867",
      "id" : "68867",
      "name" : "Default"
    }
  } ]
}

Delete Answering Rule by ID

Since 1.0.25 (Release 8.1)

Deletes a custom answering rule by a particular ID.

Method

DELETE

API Group

Medium

Required Permissions

Permission Description
EditExtensions Viewing and updating my extension info (includes extension name, number, email and phone number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session
ruleId string Internal identifier of an answering rule

Request Body

None

Response Body

None

Example

Request example

DELETE /restapi/v1.0/account/400660389008/extension/~/answering-rule/401000267008 HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQUJFU3VOMlp2bjZFREJ5ejN5
Content-Type: application/json
Content-Length: 0

Response example

HTTP/1.1 204 No Content
Content-Language: en-US

User Business Hours

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/business-hours

Get User Business Hours

Since 1.0.15 (Release 7.0)

Returns the extension user hours when answering rules are to be applied.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

None

Response Body

Parameter Type Description
uri string Canonical URI of a business-hours resource
schedule Schedule Info Schedule when an answering rule is applied

Schedule Info

Parameter Type Description
weeklyRanges Weekly Schedule Info Weekly schedule

Example

Request example

GET /restapi/v1.0/account/401800045008/extension/~/business-hours HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMnxBQUJFU3VOMlp2bjZFR2VwOWp4bXTcXc

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 774

{
  "uri" : "https.../restapi/v1.0/account/401800045008/extension/401800045008/business-hours",
  "schedule" : {
    "weeklyRanges" : {
      "wednesday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "friday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "sunday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "saturday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "tuesday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "monday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "thursday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ]
    }
  }
}

Update User Business Hours

Since 1.0.28 (Release 8.4)

Updates the extension user hours when answering rules are to be applied.

Method

PUT

API Group

Medium

Required Permissions

Permission Description
EditExtensions Viewing and updating user extension info (includes extension name, number, email and phone number, assigned phone numbers, devices and other extension settings)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

Parameter Type Description
schedule Schedule Info Schedule when an answering rule is applied

Response Body

Parameter Type Description
uri string Canonical URI of a business-hours resource
schedule Schedule Info Schedule when an answering rule is applied

Example

Request example

PUT /restapi/v1.0/account/13328820004/extension/13328820004/business-hours HTTP/1.1

{
    "schedule": {
        "weeklyRanges": {
            "tuesday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ],
            "friday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ],
            "thursday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ],
            "wednesday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ],
            "monday": [
                {
                    "from": "09:00",
                    "to": "18:00"
                }
            ]
        }

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/13328820004/extension/13328820004/business-hours",
  "schedule" : {
    "weeklyRanges" : {
      "monday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "tuesday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "wednesday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "thursday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ],
      "friday" : [ {
        "from" : "09:00",
        "to" : "18:00"
      } ]
    }
  }
}

Extension Custom Greeting List

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/greeting

Create Custom Greeting

Since 1.0.26 (Release 8.2)

Creates extension user custom greeting.

Method

POST

API Group

Heavy

Required Permissions

Permission Description
EditExtensions Viewing and updating my extension info (includes extension name, number, email and phone number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

Property Type Description
type 'Introductory' | 'Announcement' | 'ConnectingMessage' | 'ConnectingAudio' | 'Voicemail' | 'Unavailable' Type of a greeting, specifying the case when the greeting is played. See Greeting Types
answeringRule Answering Rule Info Information on an answering rule that the greeting is applied to

Answering Rule Info

Parameter Type Description
id string Internal identifier of an answering rule

Response Body

Custom Greeting Info

Example

Request example

POST /restapi/v1.0/account/1455897004/extension/1455897004/greeting HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQURIZjAzWFFySGpMMGxPaEhMaFR0
Content-Type: multipart/mixed;boundary=0123456789
Content-Length: 376

--0123456789
Content-Disposition: form-data; name="json"
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: binary

{
 "type": "Voicemail",
 "answeringRule": { "id": "2515566004" }
 }
--0123456789
Content-Disposition: form-data; name="binary"; filename="mygreeting.wav"
Content-Transfer-Encoding: binary
Content-Type: audio/wav

<...binary data...>

--0123456789--

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/1455897004/extension/1455897004/greeting/10145004",
  "id" : "10145004",
  "type" : "Voicemail",
  "contentType" : "audio/wav",
  "contentUri" : "https.../restapi/v1.0/account/1455897004/extension/1455897004/greeting/10145004/content",
  "answeringRule" : {
    "uri" : "https.../restapi/v1.0/account/1455897004/extension/1455897004/answering-rule/2515566004",
    "id" : "2515566004"
  }
}

Extension Custom Greeting

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/greeting/{greetingId}

Get Custom Greeting by ID

Since 1.0.26 (Release 8.2)

Returns a custom greeting by ID.

Method

GET

API Group

Medium

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session
greetingId string Internal identifier of a greeting

Request Body

None

Response Body

Parameter Type Description
uri string Link to an extension custom greeting
id string Internal identifier of an answering rule
type 'Introductory' | 'Announcement' | 'ConnectingMessage' | 'ConnectingAudio' | 'Voicemail' | 'Unavailable' Type of a greeting, specifying the case when the greeting is played. See Greeting Types
contentType string Content media type in WAV/MP3 format
contentUri string Link to a greeting content (audio file)

Greeting Types

Greeting type Service Web description
Introductory User greeting
Announcement Announcement Greeting
ConnectingMessage Set up a connecting message
ConnectingAudio Audio while connecting
Voicemail Voicemail Greeting
Unavailable Unavailable Greeting
InterruptPrompt Interrupt Audio

Example

Request example

GET /restapi/v1.0/account/1455897004/extension/1455897004/greeting/10148004 HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQURIZjAzWFFySGpMMGxPaEhMaFR0WEVYcVk1U1E

Response example

HTTP/1.1 200 OK
Content-Language: en-US

{
  "uri" : "https.../restapi/v1.0/account/1455897004/extension/1455897004/greeting/10148004",
  "id" : "10148004",
  "type" : "Introductory",
  "contentType" : "audio/wav",
  "contentUri" : "https.../restapi/v1.0/account/1455897004/extension/1455897004/greeting/10148004/content"
}

Authorization Profile

Get Authorization Profile

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/authz-profile

Get User Permissions

Since 1.0.22 (Release 7.5)

Returns a list of user permissions granted at authorization procedure. Please note: Some permissions may be restricted by extension type.

Method

GET

API Group

Medium

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

None

Response Body

Parameter Type Description
uri string Canonical URI of an authorization profile resource
permissions Collection of User Permissions List of user permissions granted

User Permissions

Parameter Type Description
permission User Permission Info Information on a permission granted
scopes Collection of string List of active scopes for permission

User Permission Info

Parameter Type Description
id string Internal identifier of a permission
uri string Canonical URI of a permission resource

Example

Request example

GET /restapi/v1.0/account/401172177008/extension/401172177008/authz-profile HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQURIZjAzWFFySGpMMHpFRXkyWTZCbVhoellPbT

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/401172177008/extension/401172177008/authz-profile",
  "permissions" : [ {
    "permission" : {
      "uri" : "https.../restapi/v1.0/dictionary/permission/AccountAdministration",
      "id" : "AccountAdministration"
    },
    "scopes" : [ "Account" ]
  }, {
    "permission" : {
      "uri" : "https.../restapi/v1.0/dictionary/permission/AccountValidation",
      "id" : "AccountValidation"
    },
    "scopes" : [ "Account" ]
  }, {
    "permission" : {
      "uri" : "https.../restapi/v1.0/dictionary/permission/ActiveDirectory",
      "id" : "ActiveDirectory"
    },
    "scopes" : [ "Account" ]
  }, {
    "permission" : {
      "uri" : "https.../restapi/v1.0/dictionary/permission/AddRemoveDevices",
      "id" : "AddRemoveDevices"
    },
    "scopes" : [ "Account" ]
  }, {
    "permission" : {
      "uri" : "https.../restapi/v1.0/dictionary/permission/AddRemoveGroups",
      "id" : "AddRemoveGroups"
    },
    "scopes" : [ "NonUserExtensions" ]
  }, 
   {...}
  ]

}

Check Authorization Profile

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/authz-profile/check

Check User Permissions

Since 1.0.22 (Release 7.5)

Checks if a certain user permission is activated for the particular extension.

Method

GET

API Group

Light

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Query Parameters

Parameter Type Description
permissionId string Permission to check
targetExtensionId string Optional. Internal identifier of an extension for which user permissions are to be checked. The default value is the currently logged-in extension

Request Body

None

Response Body

Parameter Type Description
uri string Canonical URI of a permission resource
successful boolean Specifies if check result is successful or not
details Permission Details Info Information on a permission checked. Returned if successful is 'True'
scopes Collection of string List of active scopes for permission. Returned if successful is 'True'

Permission Details Info

Parameter Type Description
permission User Permission Info Information on a permission checked

Example 1

If 'successful' parameter value is 'True'

Request example

GET /restapi/v1.0/account/401172177008/extension/401172177008/authz-profile/check?permissionId=ReadMessages&targetExtensionId=401172186008 HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQURIZjAzWFFySGpMMHpFRXkyWTZCbVhoellPbTBtendaQ

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/401172177008/extension/401172177008/authz-profile/check?permissionId=ReadMessages&targetExtensionId=401172186008",
  "successful" : true,
  "details" : {
    "permission" : {
      "uri" : "https.../restapi/v1.0/dictionary/permission/ReadMessages",
      "id" : "ReadMessages"
    },
    "scopes" : [ "AllExtensions" ]
  }
}

Example 2

If 'successful' parameter value is 'False'

Request example

GET /restapi/v1.0/account/401172177008/extension/401172177008/authz-profile/check?permissionId=UserManagement&targetExtensionId=401172186008 HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQURIZjAzWFFySGpMMHpFRXkyWTZCbVhoellbkE

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/401172177008/extension/401172177008/authz-profile/check?permissionId=UserManagement&targetExtensionId=401172186008",
  "successful" : false
}

Call Log

Extension Active Calls

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/active-calls

Get Extension Active Calls

Since 1.0.13 (Release 6.5)

Returns records of all extension calls that are in progress, ordered by start time in descending order.

Method

GET

API Group

Heavy

Required Permissions

Permission Description
ReadCallLog Viewing user call logs

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Query Parameters

Parameter Type Description
direction 'Inbound' | 'Outbound' The direction for the result records. It is allowed to specify more than one direction. If not specified, both inbound and outbound records are returned. Multiple values are supported
type 'Voice' | 'Fax' Call type of a record. It is allowed to specify more than one type. If not specified, all call types are returned. Multiple values are supported
transport 'PSTN' | 'VoIP' Call transport type. By default this filter is disabled
page integer Indicates the page number to retrieve. Only positive number values are allowed. Default value is '1'
perPage integer Indicates the page size (number of items). If not specified, the value is '100' by default

Request Body

None

Response Body

Property Type Description
records Collection of Call Log Record List of call log records
navigation Navigation Info Information on navigation
paging Paging Info Information on paging

Example

Request example

GET /restapi/v1.0/account/400618687004/extension/400618687004/active-calls HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMlhvUFI5dmhYVzV            

Response example

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

{
  "uri" : "https.../restapi/v1.0/account/400618687004/extension/400618687004/active-calls?page=1&perPage=100",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/400618687004/extension/400618687004/call-log/IV5fj9D8vHjs8fw",
    "id" : "IV5fj9D8vHjs8fw",
    "sessionId" : "403402173004",
    "startTime" : "2014-08-15T15:16:12.000Z",
    "duration" : 0,
    "type" : "Voice",
    "direction" : "Outbound",
    "action" : "RingOut Web",
    "result" : "Call connected",
    "to" : {
      "phoneNumber" : "+18556620006",
      "name" : "John Smith"
    },
    "from" : {
      "name" : "Jane Smith"
    }
  } ],
  "paging" : {
    "page" : 1,
    "perPage" : 100,
    "pageStart" : 0,
    "pageEnd" : 0
  },
  "navigation" : {
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/400618687004/extension/400618687004/active-calls?page=1&perPage=100"
    }
  }
}            

Extension Call Log

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log

Get Extension Call Log Records by Filter

Since 1.0.3 (Release 5.11)

Returns filtered call log records.

Method

GET

API Group

Heavy

Required Permissions

Permission Description
ReadCallLog Viewing user call logs

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Query Parameters

Parameter Type Description
extensionNumber string Extension number of a user. If specified, returns call log for a particular extension only. Cannot be specified together with the phoneNumber filter
showBlocked boolean If 'True' then calls from/to blocked numbers are returned. The default value is 'True'
phoneNumber string Phone number of a caller/call recipient. If specified, returns all calls (both incoming and outcoming) with the mentioned phone number. Cannot be specified together with the extensionNumber filter
direction 'Inbound' | 'Outbound' The direction for the result records. It is allowed to specify more than one direction. If not specified, both inbound and outbound records are returned. Multiple values are supported
sessionId string Internal identifier of a call session. Cannot be specified along with parameters 'dateTo'/'dateFrom'
type 'Voice' | 'Fax' Call type of a record. It is allowed to specify more than one type. If not specified, all call types are returned. Multiple values are supported
transport 'PSTN' | 'VoIP' Call transport type. By default this filter is disabled
view 'Simple' | 'Detailed' The default value is 'Simple' for both account and extension call log
withRecording boolean 'True' if only recorded calls are returned. The default value is 'False'
dateTo datetime The end datetime for resulting records in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z. The default value is current time
dateFrom datetime The start datetime for resulting records in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z. The default value is dateTo minus 24 hours
page integer Indicates the page number to retrieve. Only positive number values are allowed. Default value is '1'
perPage integer Indicates the page size (number of items). If not specified, the value is '100' by default

Request Body

None

Response Body

Property Type Description
records Collection of Call Log Record List of call log records
navigation Navigation Info Information on navigation
paging Paging Info Information on paging

Call Log Record

Parameter Type Description
id string Internal identifier of a cal log record
uri string Canonical URI of a call log record
sessionId string Internal identifier of a call session
from Caller Info Caller information
to Caller Info Callee information
message Voicemail Message Info For Extension Call Log only. Voicemail message data
type 'Voice' | 'Fax' Call type
direction 'Inbound' | 'Outbound' Call direction
action 'Unknown' | 'Phone Call' | 'Phone Login' | 'Incoming Fax' | 'Accept Call' | 'FindMe' | 'FollowMe' | 'Outgoing Fax' | 'Call Return' | 'Calling Card' | 'Ring Directly' | 'RingOut Web' | 'VoIP Call' | 'RingOut PC' | 'RingMe' | 'Transfer' | '411 Info' | 'Emergency' | 'E911 Update' | 'Support' | 'RingOut Mobile' Action description of the call operation
result 'Unknown' | 'InProgress' | 'Missed' | 'Call accepted' | 'Voicemail' | 'Rejected' | 'Reply' | 'Received' | 'Receive Error' | 'Fax on Demand' | 'Partial Receive' | 'Blocked' | 'Call connected' | 'No Answer' | 'International Disabled' | 'Busy' | 'Send Error' | 'Sent' | 'No fax machine' | 'ResultEmpty' | 'Account ' | 'Suspended' | 'Call Failed' | 'Call Failure' | 'Internal Error' | 'IP Phone offline' | 'Restricted Number' | 'Wrong Number' | 'Stopped' | 'Hang up' | 'Poor Line Quality' | 'Partially Sent' | 'International Restriction' | 'Abandoned' | 'Declined' | 'Fax Receipt Error' | 'Fax Send Error' Status description of the call operation
billing Billing Info For 'Detailed' view only. Call billing information
startTime datetime The call start datetime in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
duration integer Call duration in seconds
recording Recording Info Call recording data. Returned if the call is recorded, the withRecording parameter is set to 'True' in this case
lastModifiedTime datetime For 'Detailed' view only. The datetime when the call log record was modified in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
legs Collection of Leg Info For 'Detailed' view only. Leg description

Caller Info

Parameter Type Description
phoneNumber string Phone number of a party. Usually it is a plain number including country and area code like 18661234567. But sometimes it could be returned from database with some formatting applied, for example (866)123-4567. This property is filled in all cases where parties communicate by means of global phone numbers, for example when calling to direct numbers or sending/receiving SMS
extensionNumber string Extension short number (usually 3 or 4 digits). This property is filled when parties communicate by means of short internal numbers, for example when calling to other extension or sending/receiving Company Pager message
location string Contains party location (city, state) if one can be determined from phoneNumber. This property is filled only when phoneNumber is not empty and server can calculate location information from it (for example, this information is unavailable for US toll-free numbers)
name string Symbolic name associated with a party. If the phone does not belong to the known extension, only the location is returned, the name is not determined then
device Device Info For 'Detailed' view only. Device information

Voicemail Message Info

Parameter Type Description
id string Internal identifier of a voicemail message
type string Type of a message - 'Voicemail'
uri string Link to a voicemail message resource

Device Info

Parameter Type Description
id string Internal identifier of a device
uri string Link to a device

Leg Info

Parameter Type Description
action 'Unknown' | 'Phone Call' | 'Phone Login' | 'Incoming Fax' | 'Accept Call' | 'FindMe' | 'FollowMe' | 'Outgoing Fax' | 'Call Return' | 'Calling Card' | 'Ring Directly' | 'RingOut Web' | 'VoIP Call' | 'RingOut PC' | 'RingMe' | 'Transfer' | '411 Info' | 'Emergency' | 'E911 Update' | 'Support' | 'RingOut Mobile' Action description of a call operation
direction 'Inbound' | 'Outbound' Call direction
duration integer Call duration in seconds
extension Extension Info Information on extension
legType string Leg type
startTime datetime The call start datetime in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
type 'Voice' | 'Fax' Call type
result 'Unknown' | 'ResultInProgress' | 'Missed' | 'Call accepted' | 'Voicemail' | 'Rejected' | 'Reply' | 'Received' | 'Receive Error' | 'Fax on Demand' | 'Partial Receive' | 'Blocked' | 'Call connected' | 'No Answer' | 'International Disabled' | 'Busy' | 'Send Error' | 'Sent' | 'No fax machine' | 'ResultEmpty' | 'Account ' | 'Suspended' | 'Call Failed' | 'Call Failure' | 'Internal Error' | 'IP Phone offline' | 'Restricted Number' | 'Wrong Number' | 'Stopped' | 'Hang up' | 'Poor Line Quality' | 'Partially Sent' | 'International Restriction' | 'Abandoned' | 'Declined' | 'Fax Receipt Error' | 'Fax Send Error' Status description of a call operation
from Caller Info Caller information
to Caller Info Callee information
transport 'PSTN' | 'VoIP' Call transport type
billing Billing Info Call leg billing information
recording Recording Info Call recording data. Returned if the call is recorded. Each call recording is stored in the system for 90 days. But if the number of recordings exceeds the admissible limit (100,000 recordings per account) then the older recordings are replaced with the new ones. Thus a link to an older recording in a certain call log record becomes unavailable

Billing Info

Parameter Type Description
costIncluded number Cost per minute used included in your RingCentral Plan
costPurchased number Cost per minute used not included in your RingCentral Plan. for example International Calls

Recording Info

Parameter Type Description
id string Internal identifier of a call recording
uri string Link to a call recording metadata resource
type 'Automatic' | 'OnDemand' Indicates recording mode used
contentUri string Link to the call recording binary content

Extension Info

Parameter Type Description
id string Internal identifier of an extension
uri string Canonical URI of an extension

Example 1

If the view parameter value is 'Simple'

Request example

GET /restapi/v1.0/account/400569771008/call-log?page=1&perPage=2&view=Simple&withRecording=true&showBlocked=true&transport=PSTN HTTP/1.1

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 2307

{
  "uri" : "https.../restapi/v1.0/account/400569771008/call-log?page=1&perPage=2&view=Simple&withRecording=true&showBlocked=true&transport=PSTN",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/400569771008/call-log/IWAt50-PjeNDi2E?view=Simple",
    "id" : "IWAt50-PjeNDi2E",
    "sessionId" : "403487460008",
    "startTime" : "2015-11-23T15:17:13.000Z",
    "duration" : 60,
    "type" : "Voice",
    "direction" : "Inbound",
    "action" : "Phone Call",
    "result" : "Accepted",
    "to" : {
      "phoneNumber" : "+18445200003"
    },
    "from" : {
      "phoneNumber" : "+18887130017",
      "name" : "John Smith"
    },
    "recording" : {
      "uri" : "https.../restapi/v1.0/account/400569771008/recording/401225197008",
      "id" : "401225197008",
      "type" : "Automatic",
      "contentUri" : "https.../restapi/v1.0/account/400569771008/recording/401225197008/content"
    }
  }, {
    "uri" : "https.../restapi/v1.0/account/400569771008/call-log/IWAt5exKFYW5i2E?view=Simple",
    "id" : "IWAt5exKFYW5i2E",
    "sessionId" : "403487459008",
    "startTime" : "2015-11-23T15:17:13.000Z",
    "duration" : 60,
    "type" : "Voice",
    "direction" : "Inbound",
    "action" : "Phone Call",
    "result" : "Accepted",
    "to" : {
      "phoneNumber" : "+18887130017"
    },
    "from" : {
      "phoneNumber" : "+18887130016",
      "name" : "Jane Smith"
    },
    "recording" : {
      "uri" : "https.../restapi/v1.0/account/400569771008/recording/401225195008",
      "id" : "401225195008",
      "type" : "Automatic",
      "contentUri" : "https.../restapi/v1.0/account/400569771008/recording/401225195008/content"
    }
  } ],
  "paging" : {
    "page" : 1,
    "perPage" : 2,
    "pageStart" : 0,
    "pageEnd" : 1
  },
  "navigation" : {
    "nextPage" : {
      "uri" : "https.../restapi/v1.0/account/400569771008/call-log?page=1&perPage=2&view=Simple&withRecording=true&showBlocked=true&transport=PSTN"
    },
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/400569771008/call-log?page=1&perPage=2&view=Simple&withRecording=true&showBlocked=true&transport=PSTN"
    }
  }
}           

Example 2

If the view parameter value is 'Detailed'

Request example

GET /restapi/v1.0/account/404350835008/extension/404350835008/call-log?dateFrom=2016-09-20T13%3A59%3A00.000Z&dateTo=2017-09-20T13%3A59%3A00.000Z&page=1&perPage=3&view=Detailed&showBlocked=true HTTP/1.1
     

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../account/404350835008/extension/404350835008/call-log?view=Detailed&showBlocked=true&dateFrom=2016-09-20T13:59:00.000Z&dateTo=2017-09-20T13:59:00.000Z&page=1&perPage=3",
  "records" : [ {
    "uri" : "https.../account/404350835008/extension/404350835008/call-log/IaDUlfiF_23aKtI?view=Detailed",
    "id" : "IaDUlfiF_23aKtI",
    "sessionId" : "406540522008",
    "startTime" : "2017-04-06T11:19:54.000Z",
    "duration" : 4,
    "type" : "Voice",
    "direction" : "Inbound",
    "action" : "Phone Call",
    "result" : "Accepted",
    "to" : {
      "phoneNumber" : "+18882011073",
      "name" : "John Smith"
    },
    "from" : {
      "phoneNumber" : "+16504445567",
      "name" : "Jane Smith",
      "location" : "Palo Alto, CA"
    },
    "transport" : "PSTN",
    "lastModifiedTime" : "2017-04-06T11:19:57.001Z",
    "billing" : {
      "costIncluded" : 0.345,
      "costPurchased" : 0.255
    },
    "legs" : [ {
      "startTime" : "2017-04-06T11:19:54.000Z",
      "duration" : 4,
      "type" : "Voice",
      "direction" : "Inbound",
      "action" : "Phone Call",
      "result" : "Accepted",
      "to" : {
        "phoneNumber" : "+18882011073",
        "name" : "John Smith"
      },
      "from" : {
        "phoneNumber" : "+16504445567",
        "name" : "Jane Smith",
        "location" : "Palo Alto, CA"
      },
      "transport" : "PSTN",
      "billing" : {
      "costIncluded" : 0.345,
      "costPurchased" : 0.255
    },
      "legType" : "Accept",
      "extension" : {
        "uri" : "https.../account/404350835008/extension/404350835008",
        "id" : 404350835008
      }
    } ]
  }, {
    "uri" : "https.../account/404350835008/extension/404350835008/call-log/IaDUkGtwHfeyKs8?view=Detailed",
    "id" : "IaDUkGtwHfeyKs8",
    "sessionId" : "406540518008",
    "startTime" : "2017-04-06T11:19:51.000Z",
    "duration" : 10,
    "type" : "Voice",
    "direction" : "Outbound",
    "action" : "VoIP Call",
    "result" : "Call connected",
    "to" : {
      "phoneNumber" : "+16505556678"
    },
    "from" : {
      "phoneNumber" : "+18882011073",
      "name" : "John Smith"
    },
    "transport" : "VoIP",
    "lastModifiedTime" : "2017-04-06T11:19:54.001Z",
    "billing" : {
      "costIncluded" : 0.525,
      "costPurchased" : 0.112
    },
    "legs" : [ {
      "startTime" : "2017-04-06T11:19:51.000Z",
      "duration" : 10,
      "type" : "Voice",
      "direction" : "Outbound",
      "action" : "VoIP Call",
      "result" : "Call connected",
      "to" : {
        "phoneNumber" : "+16505556678"
      },
      "from" : {
        "phoneNumber" : "+18882011073",
        "name" : "John Smith"
      },
      "transport" : "VoIP",
      "billing" :  {
      "costIncluded" : 0.525,
      "costPurchased" : 0.112
    },
      "legType" : "SipToPstnMetered",
      "extension" : {
        "uri" : "https.../account/404350835008/extension/404350835008",
        "id" : 404350835008
      }
    } ]
  }, {
    "uri" : "https.../account/404350835008/extension/404350835008/call-log/IaDUjEGftN8UKs8?view=Detailed",
    "id" : "IaDUjEGftN8UKs8",
    "sessionId" : "406540515008",
    "startTime" : "2017-04-06T11:19:51.000Z",
    "duration" : 10,
    "type" : "Voice",
    "direction" : "Outbound",
    "action" : "VoIP Call",
    "result" : "Call connected",
    "to" : {
      "phoneNumber" : "+16504445567",
      "location" : "Palo Alto, CA"
    },
    "from" : {
      "phoneNumber" : "+18882011073",
      "name" : "John Smith"
    },
    "transport" : "VoIP",
    "lastModifiedTime" : "2017-04-06T11:19:54.001Z",
    "billing" : {
      "costIncluded" : 0.340,
      "costPurchased" : 0.250
    },
    "legs" : [ {
      "startTime" : "2017-04-06T11:19:51.000Z",
      "duration" : 10,
      "type" : "Voice",
      "direction" : "Outbound",
      "action" : "VoIP Call",
      "result" : "Call connected",
      "to" : {
        "phoneNumber" : "+16504445567",
        "location" : "Palo Alto, CA"
      },
      "from" : {
        "phoneNumber" : "+18882011073",
        "name" : "John Smith"
      },
      "transport" : "VoIP",
      "billing" :  {
      "costIncluded" : 0.340,
      "costPurchased" : 0.250
    },
      "legType" : "SipToPstnMetered",
      "extension" : {
        "uri" : "https.../restapi/v1.0/account/404350835008/extension/404350835008",
        "id" : 404350835008
      }
    } ]
  } ],
  "paging" : {
    "page" : 1,
    "perPage" : 3,
    "pageStart" : 0,
    "pageEnd" : 2
  },
  "navigation" : {
    "nextPage" : {
      "uri" : "https.../restapi/v1.0/account/404350835008/extension/404350835008/call-log?view=Detailed&showBlocked=true&dateFrom=2016-09-20T13:59:00.000Z&dateTo=2017-09-20T13:59:00.000Z&page=2&perPage=3"
    },
    "firstPage" : {
      "uri" : "https.../account/404350835008/extension/404350835008/call-log?view=Detailed&showBlocked=true&dateFrom=2016-09-20T13:59:00.000Z&dateTo=2017-09-20T13:59:00.000Z&page=1&perPage=3"
    }
  }
}

Extension Call Log Record

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log/{callRecordId}

Get Extension Call Log Record(s) by ID

Since 1.0.3 (Release 5.11)

Returns call log record(s) by their ID(s). Batch request is supported.

Method

GET

API Group

Heavy

Required Permissions

Permission Description
ReadCallLog Viewing user call logs

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session
callRecordId string Internal identifier of a call log record

Request Body

None

Response Body

Parameter Type Description
id string Internal identifier of a cal log record
uri string Canonical URI of a call log record
sessionId string Internal identifier of a call session
from Caller Info Caller information
to Caller Info Callee information
type 'Voice' | 'Fax' Call type
direction 'Inbound' | 'Outbound' Call direction
action 'Unknown' | 'Phone Call' | 'Phone Login' | 'Incoming Fax' | 'Accept Call' | 'FindMe' | 'FollowMe' | 'Outgoing Fax' | 'Call Return' | 'Calling Card' | 'Ring Directly' | 'RingOut Web' | 'VoIP Call' | 'RingOut PC' | 'RingMe' | 'Transfer' | '411 Info' | 'Emergency' | 'E911' | 'Update' | 'Support' | 'RingOut Mobile' Action description of the call operation
result 'Unknown' | 'ResultInProgress' | 'Missed' | 'Call accepted' | 'Voicemail' | 'Rejected' | 'Reply' | 'Received' | 'Receive Error' | 'Fax on Demand' | 'Partial Receive' | 'Blocked' | 'Call connected' | 'No Answer' | 'International Disabled' | 'Busy' | 'Send Error' | 'Sent' | 'No fax machine' | 'ResultEmpty' | 'Account ' | 'Suspended' | 'Call Failed' | 'Call Failure' | 'Internal Error' | 'IP Phone offline' | 'Restricted Number' | 'Wrong Number' | 'Stopped' | 'Hang up' | 'Poor Line Quality' | 'Partially Sent' | 'International Restriction' | 'Abandoned' | 'Declined' | 'Fax Receipt Error' | 'Fax Send Error' Status description of the call operation
startTime datetime The call start datetime in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
duration integer Call duration in seconds
recording Recording Info Call recording data. Returned if the call is recorded. Each call recording is stored in the system for 90 days. But if the number of recordings exceeds the admissible limit (100,000 recordings per account) then the older recordings are replaced with the new ones. Thus a link to an older recording in a certain call log record becomes unavailable

Example

Request example

GET /restapi/v1.0/account/401190149008/extension/401190149008/call-log/IXPCm_tIkCduk4I HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFSUNPU3BWV2wyZmZ4YkVPSFNDSlVFT3FaRmZTdFdraUx
Accept: application/json

Response example

{
   "uri": "https.../restapi/v1.0/account/401190149008/extension/401190149008/call-log/IXPCm_tIkCduk4I?view=Simple",
   "id": "IXPCm_tIkCduk4I",
   "sessionId": "404412141008",
   "startTime": "2015-06-25T14:57:30.000Z",
   "duration": 60,
   "type": "Voice",
   "direction": "Inbound",
   "action": "Phone Call",
   "result": "Accepted",
   "to":    {
      "phoneNumber": "+18772160007",
      "name": "John Smith"
   },
   "from":    {
      "phoneNumber": "+18882400004",
      "name": "Jane Smith"
   },
   "recording":    {
      "uri": "https.../restapi/v1.0/account/401190149008/recording/401547458008",
      "id": "401547458008",
      "type": "OnDemand",
      "contentUri": "https.../restapi/v1.0/account/401190149008/recording/401547458008/content"
   }
}

Call Recording

URI

/restapi/v1.0/account/{accountId}/recording/{recordingId}

Get Call Recording

Since 1.0.18

Returns call recording metadata.

Method

GET

API Group

Heavy

Required Permissions

Permission Description
ReadCallRecording Downloading call recording content
ReadCallLog Viewing user call logs

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
recordingId string Internal identifier of a recording (returned in Call Log)

Request Body

None

Response Body

Property Type Description
id string Internal identifier of a call recording
contentUri string Link to a call recording binary content
contentType string Call recording file format. Supported format is audio/x-wav
duration integer Recorded call duration

Example

Request example

GET /restapi/v1.0/account/401452676008/recording/401786818008
Authorization: Bearer U0pDMDFQMDFKV1MwMXy9Si---LvnH71KL52CevzJvUovkt
Content-Type=application/json;charset=UTF-8

Response example

HTTP 200 OK

{
  "id" : "401786818008",
  "contentUri" : "https.../restapi/v1.0/account/401452676008/recording/401786818008/content",
  "contentType" : "audio/x-wav",
  "duration" : 30
}

Call Recording Content

URI

/restapi/v1.0/account/{accountId}/recording/{recordingId}/content

Get Call Recording Data

Since 1.0.16 (Release 7.1)

Retrieves media content of a call recording.

Method

GET

API Group

Heavy

Required Permissions

Permission Description
ReadCallRecording Downloading call recording content

Request Header

The header Range allows to receive call recording in parts. For example, you need to receive the first 10 bytes of the binary file, then specify the header as follows Range: bytes=1-10

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
recordingId string Internal identifier of a call recording, see Recording Info

Request Body

None

Response Body

Call recording as binary data.

Example

Request example

GET /restapi/v1.0/account/10979280004/recording/59497406004/content HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFSUNPU3BWV2wyZmZ4YkVPSFNDSlVFT3FaRmZTdFdraUxYajg5
Range: bytes=1-10             

Response example

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: audio/x-wav
Content-Language: en-US
Content-Length: 119808

<...binary data...>      

Forwarding Numbers

Extension Forwarding Numbers

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/forwarding-number

Get Extension Forwarding Number List

Since 1.0.7 (Release 5.16)

Returns the list of extension phone numbers used for call forwarding and call flip. The returned list contains all the extension phone numbers that are used for call forwarding and call flip.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadAccounts Viewing user account info (including name, business name, address and phone number/account number)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Query Parameters

Parameter Type Description
page integer Indicates the page number to retrieve. Only positive number values are allowed. Default value is '1'
perPage integer Indicates the page size (number of items). If not specified, the value is '100' by default

Request Body

None

Response Body

Property Type Description
records Collection of Forwarding Number Info List of forwarding phone numbers
navigation Navigation Info Information on navigation
paging Paging Info Information on paging

Forwarding Number Info

Parameter Type Description
id string Internal identifier of a forwarding/call flip phone number
uri string Canonical URI of a forwarding/call flip phone number
phoneNumber string Forwarding/Call flip phone number
label string Name of a Forwarding/Call flip number
features 'CallFlip' | 'CallForwarding' Type of option this phone number is used for. Multiple values are supported
flipNumber integer Number assigned to the call flip phone number, corresponds to the shortcut dial number

Example

Request example

GET /restapi/v1.0/account/404611540004/extension/404611540004/forwarding-number HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMXwCWp6FKeVCbOcrnUJhug8KXEUtQA

Response example

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

{
  "uri" : "https.../restapi/v1.0/account/404611540004/extension/404611540004/forwarding-number?page=1&perPage=100",
  "records" : [ {
    "id" : "417276280004",
    "phoneNumber" : "+16502095678",
    "label" : "Mobile",
    "features" : [ "CallFlip", "CallForwarding" ],
    "flipNumber" : "1"
  }, {
    "id" : "417276281004",
    "phoneNumber" : "+16502090011",
    "label" : "Home",
    "features" : [ "CallFlip", "CallForwarding" ],
    "flipNumber" : "2"
  }, {
    "id" : "417276282004",
    "phoneNumber" : "+16502096235",
    "label" : "Work",
    "features" : [ "CallFlip", "CallForwarding" ],
    "flipNumber" : "3"
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 100,
    "totalElements" : 3,
    "pageStart" : 0,
    "pageEnd" : 2
  },
  "navigation" : {
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/404611540004/extension/404611540004/forwarding-number?page=1&perPage=100"
    },
    "lastPage" : {
      "uri" : "https.../restapi/v1.0/account/404611540004/extension/404611540004/forwarding-number?page=1&perPage=100"
    }
  }
}

Create Forwarding Number

Since 1.0.12 (Release 6.4)

Adds a new forwarding number to the forwarding number list.

Method

POST

API Group

Medium

Required Permissions

Permission Description
EditExtensions Viewing and updating user extension info (includes extension name, number, email and phone number, assigned phone numbers, devices and other extension settings)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

Property Type Description
phoneNumber string Forwarding/Call flip phone number
label string Name of a Forwarding/Call flip number

Response Body

Forwarding Number Info

Example

Request example

POST /restapi/v1.0/account/410992943004/extension/410992943004/forwarding-number HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMnzGB0Je_6D-6yHzXN088SZicddXcQ
Content-Type: application/json
Content-Length: 62

{
"phoneNumber" : "+16502096935",
 "label" : "Work"
  }

Response example

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

{
  "uri" : "https.../restapi/v1.0/account/410992943004/extension/410992943004/forwarding-number/409926525004",
  "id" : "409926525004",
  "phoneNumber" : "+16502096935",
  "label" : "Work",
  "features" : [ "CallFlip", "CallForwarding" ],
  "flipNumber" : "5"
}

Forwarding Number Update

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/forwarding-number/{forwardingNumberId}

Update Forwarding Number by ID

Since 1.0.24 (Release 8.0)

Updates an existent forwarding number from the forwarding number list.

Method

PUT

API Group

Medium

Required Permissions

Permission Description
EditExtensions Viewing and updating user extension info (includes extension name, number, email and phone number, assigned phone numbers, devices and other extension settings)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session
forwardingNumberId string Internal identifier of a forwarding number; returned in response in the id field

Request Body

Property Type Description
phoneNumber string Forwarding/Call flip phone number
label string Name of a Forwarding/Call flip number
flipNumber string Number assigned to the call flip phone number, corresponds to the shortcut dial number

Response Body

Forwarding Number Info

Example

Request example

PUT /restapi/v1.0/account/2284232004/extension/2284232004/forwarding-number/2622042004 HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUJFU3VOMlp2bjZFT2l3dTRGVllVcEE5Tmc
Content-Type: application/json
Content-Length: 80

{
   "phoneNumber": "+16504326573",
   "label": "Custom",
   "flipNumber": "5"
}

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 282

{
  "uri" : "https.../restapi/v1.0/account/2284232004/extension/2284232004/forwarding-number/2622042004",
  "id" : "2622042004",
  "phoneNumber" : "+16504326573",
  "label" : "Custom",
  "features" : [ "CallFlip", "CallForwarding" ],
  "flipNumber" : "5"
}

Delete Forwarding Number by ID

Since 1.0.24 (Release 8.0)

Deletes a forwarding number from the forwarding number list by its ID.

Method

DELETE

API Group

Medium

Required Permissions

Permission Description
EditExtensions Viewing and updating user extension info (includes extension name, number, email and phone number, assigned phone numbers, devices and other extension settings)

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session
forwardingNumberId string Internal identifier of a forwarding number

Request Body

None

Response Body

None

Example

Request example

DELETE /restapi/v1.0/account/2473672004/extension/2473672004/forwarding-number/2850503004 HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUJFU3VOMlp2bjZFTktMTGJmNGhQcmtKeXN0b3lHRHN6RWc
Content-Type: application/json

Response example

HTTP/1.1 204 No Content
Content-Language: en-US

Messages

Pager

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/company-pager

Create Pager Message

Since 1.0.2

Creates and sends a pager message.

Method

POST

API Group

Medium

Required Permissions

Permission Description
InternalMessages Sending and receiving intra-company text messages
ReadMessages Viewing user messages

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

Parameter Type Description
from Caller Info Sender of a pager message
to Collection of Caller Info Optional if replyOn parameter is specified. Receiver of a pager message
text string Text of a pager message. Max length is 1024 symbols (2-byte UTF-16 encoded). If a character is encoded in 4 bytes in UTF-16 it is treated as 2 characters, thus restricting the maximum message length to 512 symbols
replyOn integer Internal identifier of a message this message replies to

Caller Info

Parameter Type Description
extensionId string Internal identifier of an extension. It is strongly recommended not to use extensionNumber instead of extensionId, though it is still supported for compatibility reasons

Response Body

Parameter Type Description
uri string Canonical URI of a message
id string Internal identifier of a message
to Collection of Caller Info Recipient information
from Caller Info Sender information
attachments Collection of Message Attachment Info The list of message attachments
availability 'Alive' | 'Deleted' | 'Purged' Message availability status. Message in 'Deleted' state is still preserved with all its attachments and can be restored. 'Purged' means that all attachments are already deleted and the message itself is about to be physically deleted shortly
creationTime datetime Message creation datetime in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
direction 'Inbound' | 'Outbound' Message direction
conversationId string Identifier of the conversation the message belongs to
conversation Conversation Info Deprecated. Supported for SMS and Pager for compatibility reasons only
lastModifiedTime datetime The datetime when the message was modified on server in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
messageStatus 'Sent' | 'Received' Message status. 'Sent' - a message is successfully sent; 'Received' - a message is received (inbound messages have this status by default)
pgToDepartment boolean True if at least one of the message recipients is Department extension
priority 'Normal' | 'High' Message priority
readStatus 'Read' | 'Unread' Message read status
subject string Message subject. It replicates message text which is also returned as an attachment
type 'Pager' Message type

Caller Info

Parameter Type Description
extensionId string Internal identifier of an extension
extensionNumber string Extension number
name string Symbolic name associated with a party. If the phone does not belong to the known extension, only the location is returned, the name is not determined then

Message Attachment Info

Parameter Type Description
id string Internal identifier of a message attachment
uri string Canonical URI of a message attachment
type 'AudioRecording' | 'AudioTranscription' | 'RenderedDocument' | 'Text' | 'MmsAttachment' Type of a message attachment. See Attachment Type Info
contentType string MIME type of a given attachment, for instance 'audio/wav'

Conversation Info

Parameter Type Description
id string Internal identifier of a conversation
uri string Link to a conversation resource

Example

Request example

POST /restapi/v1.0/account/2759647004/extension/2759647004/company-pager HTTP/1.1

{
  "to": [{"extensionId": "2759654004"}, {"extensionId": "2759653004"}],
  "from": {"extensionId": "2759647004"},
  "text": "Hello!"
 }
                

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/2759647004/extension/2759647004/message-store/2640223004",
  "id" : 2640223004,
  "to" : [ {
    "extensionNumber" : "105",
    "extensionId" : "2759654004",
    "name" : "John Black"
  }, {
    "extensionNumber" : "104",
    "extensionId" : "2759653004",
    "name" : "Jane White"
  }, {
    "extensionNumber" : "101",
    "extensionId" : "2759647004",
    "name" : "Lily Bloomfield"
  } ],
  "from" : {
    "extensionNumber" : "101",
    "extensionId" : "2759647004",
    "name" : "Lily Bloomfield"
  },
  "type" : "Pager",
  "creationTime" : "2016-09-07T12:37:28.000Z",
  "readStatus" : "Read",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 2640223004,
    "uri" : "https.../restapi/v1.0/account/2759647004/extension/2759647004/message-store/2640223004/content/2640223004",
    "type" : "Text",
    "contentType" : "text/plain"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "subject" : "Hello!",
  "messageStatus" : "Sent",
  "conversationId" : 2640223004,
  "lastModifiedTime" : "2016-09-07T12:37:28.520Z",
  "pgToDepartment" : false
}       

Fax

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/fax

Create Fax Message

Since 1.0.2

Creates and sends/resends a fax message. A fax message can be sent to several recipients with several attachments. You can schedule fax sending by specifying time to send.

Each message must be a multi part. The first part contains fax sending information, the second and subsequent parts are binary attachments.

The size of all the attachments in total should not exceed 20 MB. The size of any single attachment is also limited to 20 Mb. The total number of pages (including cover page) is limited to 200.

If coverPageText is specified without coverIndex, the cover page is sent using the default template. If neither coverIndex, nor coverPageText and attachment are specified, the cover page is sent empty, in the default template.

Fax cover pages supported for the current extension are available by calling Fax Cover Pages.

Method

POST

API Group

Heavy

Required Permissions

Permission Description
Faxes Sending and receiving faxes
ReadMessages Viewing user messages

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Scenario A: Send Fax

Pattern 1 Request format: multipart/mixed
Metadata Part Header(s)

Header Value
Content-Type application/json

Metadata Part Body

Parameter Type Description
to Collection of Caller Info Recipient information. Phone number property is mandatory. Optional for resend fax request
faxResolution 'High' | 'Low' Fax resolution
sendTime datetime The datetime to send fax at, in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z. If time is not specified, the fax will be sent immediately
coverIndex integer Cover page identifier. For the list of available cover page identifiers please call the method Fax Cover Pages. If not specified, the default cover page which is configured in "Outbound Fax Settings" is attached
coverPageText string Cover page text, entered by the fax sender and printed on the cover page. Maximum length is limited to 1024 symbols

Caller Info

Parameter Type Description
phoneNumber string Phone number in E.164 (with '+' sign) format

Attachment Part(s) Header(s)

Header Value
Content-Disposition attachment; filename="filename.file extension"
Content-Type application/octet-stream

Attachment Part(s) Body

Binary data

Response Body

Parameter Type Description
id string Internal identifier of a message
uri string Canonical URI of a message
type 'Fax' Message type
from Caller Info From Sender information
to Collection of Caller Info To Recipient information
creationTime datetime Message creation datetime in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
readStatus 'Read' | 'Unread' Message read status
priority 'Normal' | 'High' Message priority
attachments Collection of Message Attachment Info The list of message attachments
direction 'Inbound' | 'Outbound' Message direction
availability 'Alive' | 'Deleted' | 'Purged' Message availability status. Message in 'Deleted' state is still preserved with all its attachments and can be restored. 'Purged' means that all attachments are already deleted and the message itself is about to be physically deleted shortly
messageStatus 'Queued' | 'Sent' | 'SendingFailed' | 'Received' Message status. 'Queued' - the message is queued for sending; 'Sent' - a message is successfully sent; 'SendingFailed' - a message sending attempt has failed; 'Received' - a message is received (inbound messages have this status by default)
faxResolution 'High' | 'Low' Resolution of a fax message. ('High' for black and white image scanned at 200 dpi, 'Low' for black and white image scanned at 100 dpi)
faxPageCount integer Page count in a fax message
lastModifiedTime datetime The datetime when the message was modified on server in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
coverIndex integer Cover page identifier. For the list of available cover page identifiers please call the method Fax Cover Pages
coverPageText string Cover page text, entered by the fax sender and printed on the cover page. Maximum length is limited to 1024 symbols

Message Attachment Info

Parameter Type Description
id string Internal identifier of a message attachment
uri string Canonical URI of a message attachment
type 'AudioRecording' | 'AudioTranscription' | 'RenderedDocument' | 'Text' | 'MmsAttachment' Type of a message attachment. See Attachment Type Info
contentType string MIME type of a given attachment, for instance 'audio/wav'

Caller Info From

Parameter Type Description
phoneNumber string Phone number in E.164 (with '+' sign) format
location string Contains party location (city, state) if one can be determined from phoneNumber. This property is filled only when phoneNumber is not empty and server can calculate location information from it (for example, this information is unavailable for US toll-free numbers)
name string Symbolic name associated with a party. If the phone does not belong to the known extension,only the location is returned, the name is not determined then

Caller Info To

Parameter Type Description
phoneNumber string Phone number in E.164 (with '+' sign) format
location string Contains party location (city, state) if one can be determined from phoneNumber. This property is filled only when phoneNumber is not empty and server can calculate location information from it (for example, this information is unavailable for US toll-free numbers)
name string Symbolic name associated with a party. If the phone does not belong to the known extension, only the location is returned, the name is not determined then
messageStatus 'Queued' | 'Sent' | 'SendingFailed' Status of a message. Returned for outbound fax messages only. 'Queued' - a message is queued for sending; 'Sent' - a message is successfully sent;' SendingFailed' - a message sending attempt has failed;
faxErrorCode 'Undefined' | 'NoFaxSendPermission' | 'NoInternationalPermission' | 'NoFaxMachine' | 'OutgoingCallError' | 'RenderingFailed' | 'TooManyPages' | 'ReturnToDBQueue' | 'NoCallTime' | 'WrongNumber' | 'ProhibitedNumber' | 'InternalError' | 'FaxSendingProhibited' | 'ThePhoneIsBlacklisted' | 'UserNotFound' | 'ConvertError' | 'DBGeneralError' | 'SkypeBillingFailed' | 'AccountSuspended' | 'ProhibitedDestination' | 'InternationalDisabled' Error code returned in case of fax sending failure. Returned if messageStatus value is 'SendingFailed'

Example 1

Specify filename and file extension in Content-Disposition header (see File extensions).

Request example

POST /restapi/v1.0/account/1446856004/extension/1446856004/fax HTTP/1.1
Authorization: Bearer ek1QUmZlOEhSS2hQTzczN093elQtTmVhRS03V2tMWVpBbWJRd3BOSXN8wm8pvsV6RuGTJvr5ex
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888
Content-Length: 352


--Boundary_1_14413901_1361871080888
Content-Type: application/json

{"to":[{"phoneNumber":"+18005630003"}],
 "faxResolution":"High",
 "sendTime":"2013-02-26T09:31:20.882Z"}

--Boundary_1_14413901_1361871080888
Content-Disposition: attachment; filename="fax.txt"

Hello, World!

--Boundary_1_14413901_1361871080888--

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 840

{
  "uri" : "https.../restapi/v1.0/account/2704667004/extension/2704667004/message-store/3349579004",
  "id" : 3349579004,
  "to" : [ {
    "phoneNumber" : "+18005630003",
    "messageStatus" : "Queued"
  } ],
  "type" : "Fax",
  "creationTime" : "2015-12-10T10:14:28.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 3349579004,
    "uri" : "https.../restapi/v1.0/account/2704667004/extension/2704667004/message-store/3349579004/content/3349579004",
    "type" : "RenderedDocument",
    "contentType" : "application/pdf"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "messageStatus" : "Queued",
  "faxResolution" : "High",
  "faxPageCount" : 0,
  "lastModifiedTime" : "2015-12-10T10:14:28.836Z",
  "coverIndex" : 7
}

Example 2

Specify file attachment MIME type in Content-Type header (see MIME types). Optionally you can also specify a filename with the corresponding file extension in Content-Disposition header (as in Scenario 1).

Request example

POST /restapi/v1.0/account/1446856004/extension/1446856004/fax HTTP/1.1
Authorization: Bearer ek1QUmZlOEhSS2hQTzczN093elQtTmVhRS03V2tMWVpBbWJRd3BOSXN8wm8pvsV6RuGTJvr5ex
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888
Content-Length: 324

--Boundary_1_14413901_1361871080888
Content-Type: application/json

{"to":[{"phoneNumber":"+18005630003"}],
 "faxResolution":"High",
 "sendTime":"2013-02-26T09:31:20.882Z"}

--Boundary_1_14413901_1361871080888
Content-Type: image/png

Hello, World!

--Boundary_1_14413901_1361871080888--
                        

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/2704667004/extension/2704667004/message-store/3349583004",
  "id" : 3349583004,
  "to" : [ {
    "phoneNumber" : "+18005630003",
    "messageStatus" : "Queued"
  } ],
  "type" : "Fax",
  "creationTime" : "2015-12-10T10:18:09.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 3349583004,
    "uri" : "https.../restapi/v1.0/account/2704667004/extension/2704667004/message-store/3349583004/content/3349583004",
    "type" : "RenderedDocument",
    "contentType" : "application/pdf"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "messageStatus" : "Queued",
  "faxResolution" : "High",
  "faxPageCount" : 0,
  "lastModifiedTime" : "2015-12-10T10:18:09.902Z",
  "coverIndex" : 7
}
                        

Pattern 2 Request format: multipart/form-data with JSON body

Metadata Part Header(s)

Header Value
Content-Disposition form-data; name="json"
Content-Type application/json; charset=UTF-8
Content-Transfer-Encoding 8 bit

Metadata Part Body

Send Fax Message Info

Attachment Part(s) Header(s)

Header Value
Content-Disposition form-data; name="content"; filename="name.file extension"
Content-Type application/octet-stream
Content-Transfer-Encoding binary

Attachment Part(s) Body

Binary data

Response Body

Fax Message Info

Example

Specify content type "application/octet-stream" in Content-Type header. Specify filename and file extension in Content-Disposition header (see File extensions).

Request example

POST /restapi/v1.0/account/1615677004/extension/1615677004/fax HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwM3xBQURiN1lJRkROUTIyb2VUcU1UUlNEMFlGOTNYNFN
Content-Type: multipart/form-data; boundary=19dj0d239d23d
Content-Length: 444

--19dj0d239d23d
Content-Disposition: form-data; name="json"
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: 8bit

{
  "to" : [ {
    "phoneNumber" : "+18004778345"
  } ],
  "faxResolution" : "Low"
  
}
--19dj0d239d23d
Content-Disposition: form-data; name="content"; filename="filename.txt"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

Hello World!
--19dj0d239d23d--

                                     

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 839

{
  "uri" : "https.../restapi/v1.0/account/1615677004/extension/1615677004/message-store/2309186004",
  "id" : 2309186004,
  "to" : [ {
    "phoneNumber" : "+18004778345",
    "messageStatus" : "Queued"
  } ],
  "type" : "Fax",
  "creationTime" : "2015-12-01T08:05:20.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 2309186004,
    "uri" : "https.../restapi/v1.0/account/1615677004/extension/1615677004/message-store/2309186004/content/2309186004",
    "type" : "RenderedDocument",
    "contentType" : "application/pdf"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "messageStatus" : "Queued",
  "faxResolution" : "Low",
  "faxPageCount" : 0,
  "lastModifiedTime" : "2015-12-01T08:05:20.106Z",
  "coverIndex" : 7
}

Pattern 3 Request format: multipart/form-data

Please note: All parameters are specified as separate request parts.

Cover Page Text Part Header(s)

Header Value
Content-Disposition form-data; name="name of parameter(see Fax Message Request Info)"
Content-Transfer-Encoding 8 bit
Content-Type text/plain

Cover Page Text Part Body

Binary data

Attachment Part(s) Header(s)

Header Value
Content-Disposition form-data; name="attachment"
Content-Transfer-Encoding binary
Content-Type text/plain

Attachment Part(s) Body

Binary data

Response Body

Fax Message Info

Example

Specify file attachment MIME type in Content-Type header (see MIME types). Specify filename and file extension in Content-Disposition header (see File extensions).

Request example

POST /restapi/v1.0/account/691748004/extension/691748004/fax HTTP/1.1
Content-Type: multipart/form-data;boundary=Boundary_14_2952358_1361963763144

--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="coverPageText"
Content-Transfer-Encoding: 8bit
Content-Type: text/plain


--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="coverIndex"
Content-Transfer-Encoding: 8bit
Content-Type: text/plain

2
--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="faxResolution"
Content-Transfer-Encoding: 8bit
Content-Type: text/plain

High
--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="sendTime"
Content-Transfer-Encoding: 8bit
Content-Type: text/plain

2030-03-19T08:00:00.000Z
--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="isoCode"
Content-Transfer-Encoding: 8bit
Content-Type: text/plain

GB
--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="to"
Content-Transfer-Encoding: 8bit
Content-Type: text/plain

+18774880001
--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="to"
Content-Transfer-Encoding: 8bit
Content-Type: text/plain

+18004778345
--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="attachment"
Content-Transfer-Encoding: binary
Content-Type: text/plain

attachment1
--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="attachment"; filename="1"
Content-Transfer-Encoding: binary
Content-Type: text/plain

attachment2
--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name="attachment"; filename="2"
Content-Transfer-Encoding: binary
Content-Type: text/plain

attachment3
--Boundary_14_2952358_1361963763144--

                                     

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/691748004/extension/691748004/message-store/1277646004",
  "id" : 1277646004,
  "to" : [ {
    "phoneNumber" : "+18774880001",
    "messageStatus" : "Queued"
  }, {
    "phoneNumber" : "+18004778345",
    "messageStatus" : "Queued"
  } ],
  "type" : "Fax",
  "creationTime" : "2016-06-14T13:38:06.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 1277646004,
    "uri" : "https.../restapi/v1.0/account/691748004/extension/691748004/message-store/1277646004/content/1277646004",
    "type" : "RenderedDocument",
    "contentType" : "application/pdf"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "messageStatus" : "Queued",
  "faxResolution" : "High",
  "faxPageCount" : 0,
  "lastModifiedTime" : "2016-06-14T13:38:06.040Z",
  "coverIndex" : 2
}

File Extensions/MIME Types

File extension MIME type Application Type
pdf application/pdf Adobe Acrobat / Adobe Reader
psd image/vnd.adobe.photoshop Adobe Photoshop
doc application/msword Microsoft Word k
docm application/vnd.ms-word.document.macroenabled.12 Microsoft Word
docx application/vnd.openxmlformats-officedocument.wordprocessingml.document Microsoft Word
xls application/vnd.ms-excel Microsoft Excel
xlsb application/vnd.ms-excel.sheet.binary.macroenabled.12 Microsoft Excel
xlsm application/vnd.ms-excel.sheet.macroenabled.12 Microsoft Excel
xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet Microsoft Excel
ppt application/vnd.ms-powerpoint Microsoft PowerPoint
pptm application/vnd.ms-powerpoint.presentation.macroenabled.12 Microsoft PowerPoint
pptx application/vnd.openxmlformats-officedocument.presentationml.presentation Microsoft PowerPoint
vsd application/vnd.visio Microsoft Visio
pub application/x-mspublisher Microsoft Publisher
wps application/vnd.ms-works Microsoft Works
wri application/x-mswrite Microsoft Windows Write
tiff image/tiff Generic Graphic Formats
gif image/gif Generic Graphic Formats
jpeg image/jpeg Generic Graphic Formats
bmp image/bmp Generic Graphic Formats
png image/png Generic Graphic Formats
pcx image/x-pcx Generic Graphic Formats
tga image/x-tga Generic Graphic Formats
wpd application/vnd.wordperfect Word Perfect Graphics
rtf application/rtf Rich Text Format
txt text/plain Text Files
xml application/xml Extensible Markup Language
html text/html Hypertext Markup Language
csv text/csv Comma Separated Values
vcard text/vcard Electronic Business Card

Scenario B: Resend Fax

Request Body

Parameter Type Description
originalMessageId string Internal identifier of the original fax message which needs to be resent
to Collection of Caller Info Recipient information. Phone number property is mandatory. Optional for resend fax request
sendTime datetime The datetime to send fax at, in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z. If time is not specified, the fax will be sent immediately

Response Body

Fax Message Info

Example
Resend fax messages by specifying original message ID. It is possible to resend a fax message of any status - Queued, Sent, Received, SendingFailed. You can forward both inbound and outbound faxes. If the recipient or recipients differ from the original message - specify them in the "to" field.

Request example

POST /restapi/v1.0/account/2704667004/extension/2704667004/fax HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwM3xBQUJFU3VOMlp2bjZFR05mZkQ4eEdZcaHg
Content-Type: application/json
Content-Length: 158

{
   "originalMessageId": "3370637004",
   "to": [{"phoneNumber": "+18005630003"},{"phoneNumber": "+18005630803"} ],
   "sendTime":"2015-12-01T08:05:20.000Z"
}

                                     

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 917

{
  "uri" : "https.../restapi/v1.0/account/2704667004/extension/2704667004/message-store/3370639004",
  "id" : 3370639004,
  "to" : [ {
    "phoneNumber" : "+18005630003",
    "messageStatus" : "Queued"
  }, {
    "phoneNumber" : "+18005630803",
    "messageStatus" : "Queued"
  } ],
  "type" : "Fax",
  "creationTime" : "2015-12-10T17:46:00.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 3370639004,
    "uri" : "https.../restapi/v1.0/account/2704667004/extension/2704667004/message-store/3370639004/content/3370639004",
    "type" : "RenderedDocument",
    "contentType" : "application/pdf"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "messageStatus" : "Queued",
  "faxResolution" : "High",
  "faxPageCount" : 0,
  "lastModifiedTime" : "2015-12-10T17:46:00.517Z",
  "coverIndex" : 7
}

SMS/MMS

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/sms

Create SMS/MMS Message

Since 1.0.2

Creates and sends a new SMS/MMS message. Sending messages to different recipients simultaneously is limited up to 50 requests per minute; relevant for all client applications.

Each MMS message must be a multi part. The first part contains message sending information, the second and subsequent parts are binary attachments.

Total attachments size is limited to 1.5 Mb; attachment count is up to 10, not counting the auxiliary "text" attachment.

Sending MMS message to multiple recipients via Batch request is supported. The number of recipients is limited to 10.

MMS feature is currently provided for US and Canada only.

Method

POST

API Group

Medium

Required Permissions

Permission Description
SMS Sending and receiving SMS/MMS messages
ReadMessages Viewing user messages

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Request Body

Parameter Type Description
from Caller Info Sender of an SMS/MMS message. The phoneNumber property should correspond to one of the account phone numbers which is allowed to send SMS/MMS. Please call the method Get Extension Phone Number List to check if the 'SmsSender'/'MmsSender' feature is available for a phone number
to Collection of Caller Info Receiver of an SMS/MMS message. Maximum number of phone numbers is 10
text string Text of a message. Max length is 1000 symbols (2-byte UTF-16 encoded). If a character is encoded in 4 bytes in UTF-16 it is treated as 2 characters, thus restricting the maximum message length to 500 symbols. Optional if a message contains attachment

Caller Info

Parameter Type Description
phoneNumber string Phone number in E.164 (with '+' sign) format

Response Body

Parameter Type Description
uri string Canonical URI of a message
id string Internal identifier of a message
to Collection of Caller Info Recipient information
from Caller Info Sender information
type 'SMS' Message type
creationTime datetime Message creation datetime in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
readStatus 'Read' | 'Unread' Message read status
priority 'Normal' | 'High' Message priority
attachments Collection of Message Attachment Info The list of message attachments. The maximum number of attachments is 10
direction 'Inbound' | 'Outbound' Message direction
availability 'Alive' | 'Deleted' | 'Purged' Message availability status. Message in 'Deleted' state is still preserved with all its attachments and can be restored. 'Purged' means that all attachments are already deleted and the message itself is about to be physically deleted shortly
subject string Message subject. It replicates message text which is also returned as an attachment
messageStatus 'Queued' | 'Sent' | 'SendingFailed' | 'Delivered' | 'DeliveryFailed' | 'Received' Message status. 'Queued' - a message is queued for sending; 'Sent' - a message is successfully sent; 'SendingFailed' - a message sending attempt has failed; 'Delivered' - a message is successfully delivered to a recipient; 'DeliveryFailed' - a message has not been delivered to a recipient; 'Received' - a message is received (inbound messages have this status by default)
smsSendingAttemptsCount integer Number of attempts made to send an outbound SMS to the gateway (if gateway is temporary unavailable)
conversationId string Identifier of a conversation this message belongs to
conversation Conversation Info Deprecated. Supported for SMS and Pager for compatibility reasons only
deliveryErrorCode string Delivery error code returned by gateway, if delivery fails
lastModifiedTime datetime The datetime when the message was modified on server in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
smsDeliveryTime datetime The datetime when outbound SMS was delivered to recipient's handset in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z. It is filled only if the carrier sends a delivery receipt to RingCentral

Caller Info

Parameter Type Description
phoneNumber string Phone number in E.164 (with '+' sign) format
location string Contains party location (city, state) if one can be determined from phoneNumber. This property is filled only when phoneNumber is not empty and server can calculate location information from it (for example, this information is unavailable for US toll-free numbers)
name string Symbolic name associated with a party. If the phone does not belong to the known extension, only the location is returned, the name is not determined then

Message Attachment Info

Parameter Type Description
id string Internal identifier of a message attachment
uri string Canonical URI of a message attachment
type 'AudioRecording' | 'AudioTranscription' | 'RenderedDocument' | 'Text' | 'MmsAttachment' Type of a message attachment. See Attachment Type Info
contentType string Content type of an attachment. The types supported are: application/gzip; application/zip; audio/mpeg; image/bmp; image/gif; image/jpeg; image/png; image/bmp; image/svg+xml; image/tiff; text/vcard; video/3gpp; video/mp4; video/mpeg; video/msvideo
size integer Attachment size in bytes

Conversation Info

Parameter Type Description
id string Internal identifier of a conversation
uri string Link to a conversation resource

Example 1

Send SMS message

Request example

POST /restapi/v1.0/account/~/extension/~/sms HTTP/1.1
Accept: application/json
Authorization: Bearer U1BCMDFUMDRKV1MwMXwVVOaPwPu88hVU5oR0u-FQFVTmhA
Content-Type: application/json

{
"to": [{"phoneNumber": "+18551003738"}],
"from": {"phoneNumber": "+18559100010}"},
"text": "Test SMS message from Platform server"
}
                

Response example

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

{
    "uri" : ".../account/1346632010/extension/1346632010/message-store/315450330010",
    "id" : 315450330010,
    "to" : [ {
        "phoneNumber" : "+18551003738"
    } ],
    "from" : {
        "phoneNumber" : "+18559100010"
    },
    "type" : "SMS",
    "creationTime" : "2012-09-13T15:21:08.000Z",
    "readStatus" : "Unread",
    "priority" : "Normal",
    "attachments" : [ {
        "id" : 1,
        "uri" : ".../account/1346632010/extension/1346632010/message-store/315450330010/content/1",
        "contentType" : "text/plain"
    } ],
    "direction" : "Outbound",
    "availability" : "Alive",
    "subject" : "Test SMS message from Platform server",
    "messageStatus" : "Sent",
    "conversationId" : 4481650717038104652,
    "lastModifiedTime" : "2012-09-13T15:21:09.000Z"
}                

Example 2

Send MMS message (multipart/mixed)

Request example

POST /restapi/v1.0/account/403391985008/extension/403391985008/sms HTTP/1.1
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888

--Boundary_1_14413901_1361871080888
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: 8bit

{"to" :[{"phoneNumber": "+18772004569"},{"phoneNumber": "+18772094569"}],
"text" :"hello" ,
"from" :{"phoneNumber": "+18882004237"}}

--Boundary_1_14413901_1361871080888
Content-Type: image/png
Content-Disposition: attachment; filename="filename.png"

Hello world!

--Boundary_1_14413901_1361871080888--       

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/403391985008/extension/403391985008/message-store/403038404008",
  "id" : 403038404008,
  "to" : [ {
    "phoneNumber" : "+18772004569"
  }, {
    "phoneNumber" : "+18772094569"
  } ],
  "from" : {
    "phoneNumber" : "+18882004237"
  },
  "type" : "SMS",
  "creationTime" : "2017-04-14T13:46:54.000Z",
  "readStatus" : "Read",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 403038404008,
    "uri" : "https.../restapi/v1.0/account/403391985008/extension/403391985008/message-store/403038404008/content/403038404008",
    "type" : "Text",
    "contentType" : "text/plain"
  }, {
    "id" : 400938873008,
    "uri" : "https.../restapi/v1.0/account/403391985008/extension/403391985008/message-store/403038404008/content/400938873008",
    "type" : "MmsAttachment",
    "contentType" : "image/png",
    "size" : 13,
    "fileName" : "filename.png"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "subject" : "hello",
  "messageStatus" : "Sent",
  "smsSendingAttemptsCount" : 1,
  "conversationId" : 4671355828682655051,
  "lastModifiedTime" : "2017-04-14T13:46:54.838Z"
}

Example 3

Send MMS message (multipart/form-data)

Request example

POST /restapi/v1.0/account/403391985008/extension/403391985008/sms HTTP/1.1
Content-Type: multipart/form-data; boundary=k2G00qjur_GTyOqELNRJOHEGPzsdAyk8lFcSH

--k2G00qjur_GTyOqELNRJOHEGPzsdAyk8lFcSH
Content-Disposition: form-data; name="json"
Content-Type: application/json
Content-Transfer-Encoding: 8bit

{"to" :[{"phoneNumber": "+18882004287"}],
"text" :"profile image" ,
"from" :{"phoneNumber": "+18882004237"}}
--k2G00qjur_GTyOqELNRJOHEGPzsdAyk8lFcSH
Content-Disposition: form-data; name="image.gif"; filename="image.gif"
Content-Type: image/gif
Content-Transfer-Encoding: binary

<.........................................................>
--k2G00qjur_GTyOqELNRJOHEGPzsdAyk8lFcSH--

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/403391985008/extension/403391985008/message-store/403038406008",
  "id" : 403038406008,
  "to" : [ {
    "phoneNumber" : "+18882004287"
  } ],
  "from" : {
    "phoneNumber" : "+18882004237"
  },
  "type" : "SMS",
  "creationTime" : "2017-04-14T13:55:22.000Z",
  "readStatus" : "Read",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 403038406008,
    "uri" : "https.../restapi/v1.0/account/403391985008/extension/403391985008/message-store/403038406008/content/403038406008",
    "type" : "Text",
    "contentType" : "text/plain"
  }, {
    "id" : 400938874008,
    "uri" : "https.../restapi/v1.0/account/403391985008/extension/403391985008/message-store/403038406008/content/400938874008",
    "type" : "MmsAttachment",
    "contentType" : "image/gif",
    "size" : 600,
    "fileName" : "image.gif"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "subject" : "profile image",
  "messageStatus" : "Sent",
  "smsSendingAttemptsCount" : 1,
  "conversationId" : 546998718833646400,
  "lastModifiedTime" : "2017-04-14T13:55:22.966Z"
}

Message List

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store

Get Message List

Since 1.0.2

Returns the list of messages from an extension mailbox.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadMessages Viewing user messages

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Query Parameters

Parameter Type Description
availability 'Alive' | 'Deleted' | 'Purged' Specifies the availability status for the resulting messages. Default value is 'Alive'. Multiple values are supported
conversationId string Specifies the conversation identifier for the resulting messages
dateFrom datetime The start datetime for resulting messages in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z. The default value is dateTo minus 24 hours
dateTo datetime The end datetime for resulting messages in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z. The default value is current time
direction 'Inbound' | 'Outbound' The direction for the resulting messages. If not specified, both inbound and outbound messages are returned. Multiple values are supported
distinctConversations boolean If 'True', then the latest messages per every conversation ID are returned
messageType 'Fax' | 'SMS' | 'VoiceMail' | 'Pager' | 'Text' The type of the resulting messages. If not specified, all messages without message type filtering are returned. Multiple values are supported
readStatus 'Read' | 'Unread' The read status for the resulting messages. Multiple values are supported
page integer Indicates the page number to retrieve. Only positive number values are allowed. Default value is '1'
perPage integer Indicates the page size (number of items). If not specified, the value is '100' by default
phoneNumber string The phone number. If specified, messages are returned for this particular phone number only

Request Body

None

Response Body

Property Type Description
records Collection of Message Info List of records with message information
navigation Navigation Info Information on navigation
paging Paging Info Information on paging

Example

Request example

GET /restapi/v1.0/account/400371259008/extension/400371259008/message-store?perPage=3&distinctConversations=true HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQUJFU3VOMlp2bjZFR2VwOWp4bXpkODhrWTV1UjNJV3JmRGVfb
Accept: application/json

Response example

HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 4536

{
  "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store?availability=Alive&dateFrom=2015-11-17T14:40:00.000Z&distinctConversations=true&page=1&perPage=3",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store/401060296008",
    "id" : 401060296008,
    "to" : [ {
      "phoneNumber" : "+1650875583254"
    } ],
    "from" : {
      "phoneNumber" : "+18883770028"
    },
    "type" : "SMS",
    "creationTime" : "2015-11-18T14:28:53.000Z",
    "readStatus" : "Read",
    "priority" : "Normal",
    "attachments" : [ {
      "id" : 401060296008,
      "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store/401060296008/content/401060296008",
      "type" : "Text",
      "contentType" : "text/plain"
    } ],
    "direction" : "Outbound",
    "availability" : "Alive",
    "subject" : "Test SMS message from Platform server",
    "messageStatus" : "Sent",
    "smsSendingAttemptsCount" : 1,
    "conversationId" : 2335508640601318644,
    "lastModifiedTime" : "2015-11-18T14:28:54.035Z"
  }, {
    "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store/401060294008",
    "id" : 401060294008,
    "to" : [ {
      "phoneNumber" : "+1650876583254"
    } ],
    "from" : {
      "phoneNumber" : "+18883770028"
    },
    "type" : "SMS",
    "creationTime" : "2015-11-18T14:28:28.000Z",
    "readStatus" : "Read",
    "priority" : "Normal",
    "attachments" : [ {
      "id" : 401060294008,
      "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store/401060294008/content/401060294008",
      "type" : "Text",
      "contentType" : "text/plain"
    } ],
    "direction" : "Outbound",
    "availability" : "Alive",
    "subject" : "Test SMS message from Platform server",
    "messageStatus" : "Sent",
    "smsSendingAttemptsCount" : 1,
    "conversationId" : 5226857014532753173,
    "lastModifiedTime" : "2015-11-18T14:28:28.413Z"
  }, {
    "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store/401060290008",
    "id" : 401060290008,
    "to" : [ {
      "phoneNumber" : "+16508783254"
    } ],
    "from" : {
      "phoneNumber" : "+18883770028"
    },
    "type" : "SMS",
    "creationTime" : "2015-11-18T14:28:18.000Z",
    "readStatus" : "Read",
    "priority" : "Normal",
    "attachments" : [ {
      "id" : 401060290008,
      "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store/401060290008/content/401060290008",
      "type" : "Text",
      "contentType" : "text/plain"
    } ],
    "direction" : "Outbound",
    "availability" : "Alive",
    "subject" : "Test SMS message from Platform server",
    "messageStatus" : "Sent",
    "smsSendingAttemptsCount" : 1,
    "conversationId" : 1817157275107994090,
    "lastModifiedTime" : "2015-11-18T14:28:19.126Z"
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 3,
    "perPage" : 3,
    "totalElements" : 9,
    "pageStart" : 0,
    "pageEnd" : 2
  },
  "navigation" : {
    "nextPage" : {
      "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store?availability=Alive&dateFrom=2015-11-17T14:40:00.000Z&distinctConversations=true&page=2&perPage=3"
    },
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store?availability=Alive&dateFrom=2015-11-17T14:40:00.000Z&distinctConversations=true&page=1&perPage=3"
    },
    "lastPage" : {
      "uri" : "https.../restapi/v1.0/account/400371259008/extension/400371259008/message-store?availability=Alive&dateFrom=2015-11-17T14:40:00.000Z&distinctConversations=true&page=3&perPage=3"
    }
  }
}

Delete Conversation(s) by ID

Since 1.0.25 (Release 8.1)

Deletes conversation(s) by conversation ID(s). Batch request is supported.

Method

DELETE

API Group

Medium

Required Permissions

Permission Description
EditMessages Viewing and updating user messages
ReadMessages Viewing user messages

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session

Query Parameters

Parameter Type Description
conversationId string Identifier of a conversation. Multiple values are supported

Request Body

None

Response Body

None

Example 1

Request example

DELETE /restapi/v1.0/account/3632358004/extension/3632358004/message-store?conversationId=7118033917873890173&conversationId=3292704822660695422 HTTP/1.1

Response example

HTTP/1.1 204 No Content

Example 2

Alternative Syntax: POST QueryString / X-HTTP-Method-Override: DELETE

Request example

POST /restapi/v1.0/account/3797107004/extension/3797107004/message-store HTTP/1.1

Content-Type: application/x-www-form-urlencoded
X-HTTP-Method-Override: DELETE

conversationId=35127351262&conversationId=35127351263

Response example

HTTP/1.1 204 No Content

Message(s) by ID

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/{messageId}

Get Message(s) by ID

Since 1.0.2

Returns individual message record(s) by the given message ID(s). The length of inbound messages is unlimited. Batch request is supported.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadMessages Viewing user messages

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral account or tilde (~) to indicate the account logged-in within the current session
extensionId string Internal identifier of an extension or tilde (~) to indicate the extension assigned to the account logged-in within the current session
messageId integer Internal identifier of a message

Request Body

None

Response Body

Parameter Type Description
id string Internal identifier of a message
uri string Canonical URI of a message
attachments Collection of Message Attachment Info The list of message attachments
availability 'Alive' | 'Deleted' | 'Purged' Message availability status. Message in 'Deleted' state is still preserved with all its attachments and can be restored. 'Purged' means that all attachments are already deleted and the message itself is about to be physically deleted shortly
conversationId string SMS and Pager only. Identifier of the conversation the message belongs to
conversation