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 Implied Permissions
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 client ID and client 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 client ID and client 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 Info

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

Response example

HTTP/1.1 200 OK

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

Response example

HTTP/1.1 200 OK

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

API Status

URI

/restapi/v1.0/status

Get Status

Since 1.0.27 (Release 8.3)

Returns the API status; status '200' means the API is working fine, and '503' means it is temporary unavailable.

Method

GET

API Group

Light

Request Body

None

Response Body

None

Example 1

Request example

GET restapi/v1.0/status HTTP/1.1

Response example

HTTP/1.1 200 OK

Example 2

Request example

GET restapi/v1.0/status HTTP/1.1

Response example

HTTP 503 Service Unavailable
Retry-After: 40

Call Log

User Call Log

URI

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

Get User Call Log

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. 'PSTN' specifies that a call leg is initiated from the PSTN network provider; 'VoIP' - from an RC phone. 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 Message Info For User Call Log only. Voicemail/Fax message data
type 'Voice' | 'Fax' Call type
transport 'PSTN' | 'VoIP' For 'Detailed' view only. Call transport type. 'PSTN' specifies that a call leg is initiated from the PSTN network provider; 'VoIP' - from an RC phone
direction 'Inbound' | 'Outbound' Call direction
action string Action status of a call event, see Action Status Values
result string Result status of a call event, see Result Status Values
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. 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

Message Info

Parameter Type Description
id string Internal identifier of a message
type 'VoiceMail' | 'Fax' Type of a message
uri string Link to a 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
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
action string Action status of a call event, see Action Status Values
result string Result status of a call event, see Result Status Values
from Caller Info Caller information
to Caller Info Callee information
transport 'PSTN' | 'VoIP' Call transport type. 'PSTN' specifies that a call leg is initiated from the PSTN network provider; 'VoIP' - from an RC phone
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

Action Status Values

Action Status Description Type of Event
Unknown Call status is undefined Voice call/Fax
Phone Call Incoming voice call Voice call/Fax
Incoming Fax Incoming fax Fax
Accept Call Incoming call is received and call processing has been already started Voice call
FindMe Incoming call is being processed according to 'Call Handling & Forwarding' user settings Voice call
Outgoing Fax Outgoing fax Fax
Call Return User is being called back by RC Voice call
Calling Card Outgoing call using RC Calling Card Voice call
CallOut-CallMe Call from RC Meetings Voice call
Ring Directly Direct RingOut call from softphone Voice call
RingOut Web RingOut call from RC Service Web Voice call
RingOut PC RingOut call from RC desktop application (softphone) Voice call
RingOut Mobile RingOut call from RC mobile application Voice call
VoIP Call Call from RC Digital Line Voice call
RingMe Incoming call from third party web site to RC system Voice call
Transfer Call is being transferred to another RC Digital Line or phone number Voice call
Emergency Emergency call Voice call
Call Park Call is put on hold to be retrieved from another phone (Call Park feature) Voice call
Park Location Call is located to the destination phone (Call Park feature) Voice call
Hunting Incoming call is distributed to a group of several telephone lines Voice call
Monitoring Call is taken over by a supervisor Voice call
External Application Call is redirected to RC user telephony application Voice call
Text Relay Voice call forwarded to UK text relay service Voice call
FreeSPDL Call to softphone which is not assigned to the Digital Line Voice call
SIP Forwarding Call is redirected to any non-RC phone number Voice call
911 Call to 911 emergency phone number Voice call
913 Call to 913 emergency phone number Voice call

Result Status Values

Result Status Description Type of Event
Unknown Call processing result is undefined Voice call/Fax
ResultInProgress Call is being processed currently Voice call/Fax
Missed Incoming voice call has been missed Voice call
Call Accepted Incoming call is received Voice call
Voicemail Incoming call is redirected to voicemail Voice call
Rejected Call is declined Voice call
Reply Voice reply based on predefined text Voice call
Received Incoming fax is received Fax
Receive Error Incoming fax has failed to be received Fax
Fax on Demand Sending faxed copy of a document Fax
Partial Receive Incoming fax is received partially Fax
Blocked Call to/from a blocked number Voice call
Call connected Call is connected and conversation is going on Voice call
No answer Outgoing call is not answered Voice call
International Disabled Call to an international number while International Calling feature is switched off Voice call
Busy Phone number is busy Voice call
Send Error Outgoing fax sending has failed Fax
Sent Outgoing fax is successfully sent Fax
No fax machine Outgoing fax has failed because there is no fax machine Fax
Call Failed Outgoing fax has failed because of no answer Fax
Internal Error Server error has occurred Voice call/Fax
IP Phone Offline RC Digital Line is unregistered Voice call/Fax
Restricted Number Call to a restricted number Voice call
Wrong Number Outgoing call to an incorrect phone number Voice call
Stopped Outgoing fax sending has been stopped Fax
Hang up Call recipient has hung up the call Voice call
Partially Sent Outgoing fax is sent partially Fax
International Restriction Call to an international phone number which is restricted Voice call
Abandoned Call has been lost Voice call
Declined Call is not taken (DND status is on) Voice call
Fax Receipt Error Internal error occurred when receiving fax Fax
Fax Send Error Internal error occurred when sending fax Fax

Example 1

If the view parameter value is 'Simple'

Request example

GET /restapi/v1.0/account/401494647008/extension/401494647008/call-log?page=1&perPage=2&view=Simple&withRecording=false HTTP/1.1

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/401494647008/extension/401494647008/call-log?view=Simple&showBlocked=true&dateFrom=2017-09-03T12:34:00.000Z&page=1&perPage=2",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/401494647008/extension/401494647008/call-log/IWvNToLkbo-7zUA?view=Simple",
    "id" : "IWvNToLkbo-7zUA",
    "sessionId" : "404036325008",
    "startTime" : "2017-09-04T12:31:50.441Z",
    "duration" : 5,
    "type" : "Voice",
    "direction" : "Outbound",
    "action" : "RingOut Web",
    "result" : "Call connected",
    "to" : {
      "phoneNumber" : "+16505556678"
    },
    "from" : {
      "phoneNumber" : "+18552001907",
      "name" : "John Smith"
    }
  }, {
    "uri" : "http:s.../restapi/v1.0/account/401494647008/extension/401494647008/call-log/8vsAH84JRCeg-DLA?view=Simple",
    "id" : "8vsAH84JRCeg-DLA",
    "sessionId" : "-40293491700800",
    "startTime" : "2017-09-04T12:03:24.842Z",
    "duration" : 32,
    "type" : "Fax",
    "direction" : "Outbound",
    "action" : "Outgoing Fax",
    "result" : "Sent",
    "to" : {
      "phoneNumber" : "+16504445566",
      "location" : "Palo Alto, CA"
    },
    "from" : {
      "phoneNumber" : "+18552001907",
      "name" : "John Smith"
    },
    "message" : {
      "uri" : "https.../restapi/v1.0/account/401494647008/extension/401494647008/message-store/401678422008",
      "id" : "401678422008",
      "type" : "Fax"
    }],
  "paging" : {
    "page" : 1,
    "perPage" : 2,
    "pageStart" : 0,
    "pageEnd" : 1
  },
  "navigation" : {
    "nextPage" : {
      "uri" : "https.../restapi/v1.0/account/401494647008/extension/401494647008/call-log?view=Simple&showBlocked=true&dateFrom=2017-09-03T12:34:00.000Z&page=2&perPage=2"
    },
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/401494647008/extension/401494647008/call-log?view=Simple&showBlocked=true&dateFrom=2017-09-03T12:34:00.000Z&page=1&perPage=2"
    }
  }
}           

Example 2
If the view parameter value is 'Detailed'

Request example

GET /restapi/v1.0/account/37439510/extension/61307231006/call-log?dateFrom=2017-04-04&dateTo=2017-06-06&direction=Inbound&type=Voice&perPage=2&view=Detailed&transport=PSTN HTTP/1.1
     

Response example

HTTP/1.1 200 OK

{
  "uri" : "https://.../restapi/v1.0/account/37439510/extension/61307231006/call-log?view=Detailed&type=Voice&direction=Inbound&transport=PSTN&showBlocked=true&dateFrom=2017-04-04T00:00:00.000Z&dateTo=2017-06-06T00:00:00.000Z&page=1&perPage=2",
  "records" : [ {
    "uri" : "https://.../restapi/v1.0/account/37439510/extension/61307231006/call-log/DN8jE39JNxZXY1Y?view=Detailed",
    "id" : "DN8jE39JNxZXY1Y",
    "sessionId" : "155608446020",
    "startTime" : "2017-05-23T17:37:18.227Z",
    "duration" : 14,
    "type" : "Voice",
    "direction" : "Inbound",
    "action" : "Phone Call",
    "result" : "Missed",
    "to" : {
      "phoneNumber" : "+16503947599",
      "name" : "Jane Smith"
    },
    "from" : {
      "phoneNumber" : "+14087302900",
      "name" : "PALO ALTO MED F",
      "location" : "Sunnyvale, CA"
    },
    "transport" : "PSTN",
    "lastModifiedTime" : "2017-05-23T17:41:48.107Z",
    "billing" : {
      "costIncluded" : 0.0,
      "costPurchased" : 0.0
    },
    "legs" : [ {
      "startTime" : "2017-05-23T17:37:18.227Z",
      "duration" : 14,
      "type" : "Voice",
      "direction" : "Inbound",
      "action" : "Phone Call",
      "result" : "Missed",
      "to" : {
        "phoneNumber" : "+16503947599",
        "name" : "Jane Smith"
      },
      "from" : {
        "phoneNumber" : "+14087302900",
        "name" : "PALO ALTO MED F",
        "location" : "Sunnyvale, CA"
      },
      "transport" : "PSTN",
      "billing" : { },
      "legType" : "Accept",
      "extension" : {
        "uri" : "https://.../restapi/v1.0/account/37439510/extension/61307231006",
        "id" : 61307231006
      }
    } ]
  }, {
    "uri" : "https://.../restapi/v1.0/account/37439510/extension/61307231006/call-log/DMM1e9wk5kaHSeE?view=Detailed",
    "id" : "DMM1e9wk5kaHSeE",
    "sessionId" : "154289579020",
    "startTime" : "2017-05-05T21:03:37.971Z",
    "duration" : 16,
    "type" : "Voice",
    "direction" : "Inbound",
    "action" : "Phone Call",
    "result" : "Voicemail",
    "to" : {
      "phoneNumber" : "+16503947599",
      "name" : "Jane Smith"
    },
    "from" : {
      "phoneNumber" : "+16692927940",
      "name" : "VILGELM,SERGEY",
      "location" : "San Jose (West), CA"
    },
    "message" : {
      "uri" : "https://.../restapi/v1.0/account/37439510/extension/61307231006/message-store/804265770020",
      "id" : "804265770020",
      "type" : "VoiceMail"
    },
    "transport" : "PSTN",
    "lastModifiedTime" : "2017-05-05T21:04:10.636Z",
    "billing" : {
      "costIncluded" : 0.0,
      "costPurchased" : 0.0
    },
    "legs" : [ {
      "startTime" : "2017-05-05T21:03:37.971Z",
      "duration" : 16,
      "type" : "Voice",
      "direction" : "Inbound",
      "action" : "Phone Call",
      "result" : "Voicemail",
      "to" : {
        "phoneNumber" : "+16503947599",
        "name" : "Jane Smith"
      },
      "from" : {
        "phoneNumber" : "+16692927940",
        "name" : "VILGELM,SERGEY",
        "location" : "San Jose (West), CA"
      },
      "message" : {
        "uri" : "https://.../restapi/v1.0/account/37439510/extension/61307231006/message-store/804265770020",
        "id" : "804265770020",
        "type" : "VoiceMail"
      },
      "transport" : "PSTN",
      "billing" : { },
      "legType" : "Accept",
      "extension" : {
        "uri" : "https://.../restapi/v1.0/account/37439510/extension/61307231006",
        "id" : 61307231006
      }
    } ]
  } ],
  "paging" : {
    "page" : 1,
    "perPage" : 2,
    "pageStart" : 0,
    "pageEnd" : 1
  },
  "navigation" : {
    "nextPage" : {
      "uri" : "https://.../restapi/v1.0/account/37439510/extension/61307231006/call-log?view=Detailed&type=Voice&direction=Inbound&transport=PSTN&showBlocked=true&dateFrom=2017-04-04T00:00:00.000Z&dateTo=2017-06-06T00:00:00.000Z&page=2&perPage=2"
    },
    "firstPage" : {
      "uri" : "https://.../restapi/v1.0/account/37439510/extension/61307231006/call-log?view=Detailed&type=Voice&direction=Inbound&transport=PSTN&showBlocked=true&dateFrom=2017-04-04T00:00:00.000Z&dateTo=2017-06-06T00:00:00.000Z&page=1&perPage=2"
    }
  }
}
    

User Call Log Record

URI

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

Get User Call Log Record

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

User Active Calls

URI

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

Get User 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. 'PSTN' specifies that a call leg is initiated from the PSTN network provider; 'VoIP' - from an RC phone. 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
           

Response example

HTTP/1.1 200 OK

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

Company Call Log

URI

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

Get Company Call Log

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

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. 'PSTN' specifies that a call leg is initiated from the PSTN network provider; 'VoIP' - from an RC phone. 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'
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
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
page integer Indicates the page number to retrieve. Only positive number values are allowed. The 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 1

If the view parameter value is 'Simple'

Request example

GET /restapi/v1.0/account/400643090008/call-log?view=Simple&dateFrom=2015-11-24T12:07:53.175Z&dateTo=2015-11-25T12:07:53.175Z&page=1&perPage=2 HTTP/1.1

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/400643090008/call-log?view=Simple&dateFrom=2015-11-24T12:07:53.175Z&dateTo=2015-11-25T12:07:53.175Z&page=1&perPage=2",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/400643090008/call-log/IWM7cJogEv7xlu8?view=Simple",
    "id" : "IWM7cJogEv7xlu8",
    "sessionId" : "403631628008",
    "startTime" : "2015-11-25T12:07:51.000Z",
    "duration" : 10,
    "type" : "Voice",
    "direction" : "Outbound",
    "action" : "VoIP Call",
    "result" : "Call connected",
    "to" : {
      "phoneNumber" : "+16505556678"
    },
    "from" : {
      "phoneNumber" : "+18883930031",
      "name" : "John Smith"
    }
  }, {
    "uri" : "https.../restapi/v1.0/account/400643090008/call-log/IWM7bHBPqeZTlu8?view=Simple",
    "id" : "IWM7bHBPqeZTlu8",
    "sessionId" : "403631625008",
    "startTime" : "2015-11-25T12:07:51.000Z",
    "duration" : 10,
    "type" : "Voice",
    "direction" : "Outbound",
    "action" : "VoIP Call",
    "result" : "Call connected",
    "to" : {
      "phoneNumber" : "+16504445567",
      "location" : "Palo Alto, CA"
    },
    "from" : {
      "phoneNumber" : "+18883930031",
      "name" : "John Smith"
    }
  } ],
  "paging" : {
    "page" : 1,
    "perPage" : 2,
    "pageStart" : 0,
    "pageEnd" : 1
  },
  "navigation" : {
    "nextPage" : {
      "uri" : "https.../restapi/v1.0/account/400643090008/call-log?view=Simple&dateFrom=2015-11-24T12:07:53.175Z&dateTo=2015-11-25T12:07:53.175Z&page=2&perPage=2"
    },
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/400643090008/call-log?view=Simple&dateFrom=2015-11-24T12:07:53.175Z&dateTo=2015-11-25T12:07:53.175Z&page=1&perPage=2"
    }
  }
}

Example 2

If the view parameter value is 'Detailed'

Request example

GET /restapi/v1.0/account/404350835008/call-log?dateFrom=2016-11-24T12%3A07%3A53.175Z&dateTo=2017-11-24T12%3A07%3A53.175Z&page=1&perPage=2&view=Detailed HTTP/1.1

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../account/404350835008/call-log?view=Detailed&showBlocked=true&dateFrom=2016-11-24T12:07:53.175Z&dateTo=2017-11-24T12:07:53.175Z&page=1&perPage=2",
  "records" : [ {
    "uri" : "https.../account/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"
    },
    "from" : {
      "phoneNumber" : "+16504445567",
      "location" : "Palo Alto, CA"
    },
    "transport" : "PSTN",
    "lastModifiedTime" : "2017-04-06T11:19:57.001Z",
    "billing" : {
      "costIncluded" : 1.560,
      "costPurchased" : 1.122
    },
    "legs" : [ {
      "startTime" : "2017-04-06T11:19:54.000Z",
      "duration" : 4,
      "type" : "Voice",
      "direction" : "Inbound",
      "action" : "Phone Call",
      "result" : "Accepted",
      "to" : {
        "phoneNumber" : "+18882011073"
      },
      "from" : {
        "phoneNumber" : "+16504445567",
        "location" : "Palo Alto, CA"
      },
      "transport" : "PSTN",
      "billing" : {
      "costIncluded" : 0.300,
      "costPurchased" : 0.000
    },
      "legType" : "Accept"
    }, {
      "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" : 1.260,
      "costPurchased" : 1.222
    },
      "legType" : "Accept",
      "extension" : {
        "uri" : "https.../restapi/v1.0/account/404350835008/extension/404350835008",
        "id" : 404350835008
      }
    } ]
  }, {
    "uri" : "https.../account/404350835008/call-log/IaDUlJVAhxBQKtI?view=Detailed",
    "id" : "IaDUlJVAhxBQKtI",
    "sessionId" : "406540521008",
    "startTime" : "2017-04-06T11:19:54.000Z",
    "duration" : 5,
    "type" : "Voice",
    "direction" : "Outbound",
    "action" : "VoIP Call",
    "result" : "Call connected",
    "to" : {
      "phoneNumber" : "+16504445567",
      "location" : "Palo Alto, CA"
    },
    "from" : {
      "phoneNumber" : "+18552011120",
      "name" : "John Doe"
    },
    "transport" : "VoIP",
    "lastModifiedTime" : "2017-04-06T11:19:57.001Z",
    "billing" : {
      "costIncluded" : 0.340,
      "costPurchased" : 0.025
    },
    "legs" : [ {
      "startTime" : "2017-04-06T11:19:54.000Z",
      "duration" : 5,
      "type" : "Voice",
      "direction" : "Outbound",
      "action" : "VoIP Call",
      "result" : "Call connected",
      "to" : {
        "phoneNumber" : "+16504445567",
        "location" : "Palo Alto, CA"
      },
      "from" : {
        "phoneNumber" : "+18552011120",
        "name" : "John Doe"
      },
      "transport" : "VoIP",
      "billing" : {
      "costIncluded" : 0.340,
      "costPurchased" : 0.025
    },
      "legType" : "SipToPstnMetered",
      "extension" : {
        "uri" : "https.../account/404350835008/extension/404350837008",
        "id" : 404350837008
      }
    } ]
  } ],
  "paging" : {
    "page" : 1,
    "perPage" : 2,
    "pageStart" : 0,
    "pageEnd" : 1
  },
  "navigation" : {
    "nextPage" : {
      "uri" : "https.../account/404350835008/call-log?view=Detailed&showBlocked=true&dateFrom=2016-11-24T12:07:53.175Z&dateTo=2017-11-24T12:07:53.175Z&page=2&perPage=2"
    },
    "firstPage" : {
      "uri" : "https.../account/404350835008/call-log?view=Detailed&showBlocked=true&dateFrom=2016-11-24T12:07:53.175Z&dateTo=2017-11-24T12:07:53.175Z&page=1&perPage=2"
    }
  }
} 

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

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 file in mp3 format
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...>      

Phone Numbers

Extension Phone Number List

URI

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

Get User Numbers

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' | 'ContactCenterNumber' Usage type of a 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 Extension data. Returned for 'IvrMenu' and 'Department' extension direct numbers with the 'CallerId' feature turned on
features Collection of string Indicates phone number features. 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' | 'ContactCenterNumber' 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 Extension short number (usually 3 or 4 digits)
name string IVR Menu/Call Queue name
type 'IvrMenu' | 'Department' Type of a phone number

Example

Request example

GET /restapi/v1.0/account/406266144008/extension/406266144008/phone-number HTTP/1.1

Response example

HTTP/1.1 200 OK

    {
      "uri" : "https.../restapi/v1.0/account/406266144008/extension/406266144008/phone-number?page=1&perPage=100",
      "records" : [ {
        "id" : 405665234008,
        "phoneNumber" : "+14034532006",
        "paymentType" : "Local",
        "location" : "Calgary, AB",
        "type" : "VoiceOnly",
        "usageType" : "DirectNumber",
        "status" : "Normal",
        "country" : {
          "uri" : "https.../restapi/v1.0/dictionary/country/39",
          "id" : "39",
          "name" : "Canada"
        },
        "features" : [ "InternationalSmsSender", "CallerId", "MmsSender", "SmsSender" ]
      }, {
        "id" : 405665241008,
        "phoneNumber" : "+17057350012",
        "paymentType" : "Local",
        "location" : "Barrie, ON",
        "type" : "VoiceOnly",
        "usageType" : "DirectNumber",
        "extension" : {
          "uri" : "https.../restapi/v1.0/account/406266144008/extension/406266152008",
          "id" : 406266152008,
          "extensionNumber" : "1000",
          "name" : "IVR Menu",
          "type" : "IvrMenu"
        },
        "status" : "Normal",
        "country" : {
          "uri" : "https.../restapi/v1.0/dictionary/country/39",
          "id" : "39",
          "name" : "Canada"
        },
        "features" : [ "CallerId" ]
      }, {
        "id" : 405665237008,
        "phoneNumber" : "+17787640710",
        "paymentType" : "Local",
        "location" : "Prince George, BC",
        "type" : "VoiceOnly",
        "usageType" : "DirectNumber",
        "extension" : {
          "uri" : "https.../restapi/v1.0/account/406266144008/extension/406266148008",
          "id" : 406266148008,
          "extensionNumber" : "1",
          "name" : "Sales",
          "type" : "Department"
        },
        "status" : "Normal",
        "country" : {
          "uri" : "https.../restapi/v1.0/dictionary/country/39",
          "id" : "39",
          "name" : "Canada"
        },
        "features" : [ "CallerId" ]
      }, {
        "id" : 405665233008,
        "phoneNumber" : "+18002022673",
        "paymentType" : "TollFree",
        "type" : "VoiceFax",
        "usageType" : "MainCompanyNumber",
        "status" : "Normal",
        "country" : {
          "uri" : "https.../restapi/v1.0/dictionary/country/1",
          "id" : "1",
          "name" : "United States"
        },
        "features" : [ "CallerId" ]
      } ],
      "paging" : {
        "page" : 1,
        "totalPages" : 1,
        "perPage" : 100,
        "totalElements" : 4,
        "pageStart" : 0,
        "pageEnd" : 3
      },
      "navigation" : {
        "firstPage" : {
          "uri" : "https.../restapi/v1.0/account/406266144008/extension/406266144008/phone-number?page=1&perPage=100"
        },
        "lastPage" : {
          "uri" : "https.../restapi/v1.0/account/406266144008/extension/406266144008/phone-number?page=1&perPage=100"
        }
      }
    }

Messages

SMS/MMS

URI

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

Send SMS/MMS

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

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 Datetime when the message was modified on server in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
smsDeliveryTime datetime 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/gz; application/zip; audio/mpeg; audio/amr; audio/m4a; image/bmp; image/gif; image/jpeg; image/png; image/bmp; image/svg+xml; image/tiff; text/vcard; 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",
    "width": 640,
    "height": 480
   } ],
  "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 1)

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",
    "width": 640,
    "height": 480
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "subject" : "profile image",
  "messageStatus" : "Sent",
  "smsSendingAttemptsCount" : 1,
  "conversationId" : 546998718833646400,
  "lastModifiedTime" : "2017-04-14T13:55:22.966Z"
}

Example 4

Send MMS message (multipart/form-data 2)

Request example

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

--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name = to; filename = file
Content-Type: text/plain
+14085505499

--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name = from; filename = file
Content-Type: text/plain
+17082000133

--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name = text; filename = file
Content-Type: text/plain
Text message

--Boundary_14_2952358_1361963763144
Content-Disposition: form-data; name = attachment; filename = png
Content-Type: image/png
<binary data>

                                    

Response example

HTTP/1.1 200 OK

{
    "uri": "https.../restapi/v1.0/account/402621387008/extension/402621387008/message-store/402394918008",
    "id": 402394918008,
    "to": [
        {
            "phoneNumber": "+14085505499",
            "location": "San Jose, West, CA"
        }
    ],
    "from": {
        "phoneNumber": "+17082000133"
    },
    "type": "SMS",
    "creationTime": "2017-05-19T13:36:54.000Z",
    "readStatus": "Read",
    "priority": "Normal",
    "attachments": [
        {
            "id": 402394918008,
            "uri": "https.../restapi/v1.0/account/402621387008/extension/402621387008/message-store/402394918008/content/402394918008",
            "type": "Text",
            "contentType": "text/plain"
        },
        {
            "id": 400923921008,
            "uri": "https.../restapi/v1.0/account/402621387008/extension/402621387008/message-store/402394918008/content/400923921008",
            "type": "MmsAttachment",
            "contentType": "image/png",
            "size": 13,
            "fileName": "png"
        }
    ],
    "direction": "Outbound",
    "availability": "Alive",
    "subject": "Text message",
    "messageStatus": "Queued",
    "smsSendingAttemptsCount": 1,
    "conversationId": 5800435923250009040,
    "conversation": {
        "id": "5800435923250009040",
        "uri": "https.../restapi/v1.0/conversation/5800435923250009040"
    },
    "lastModifiedTime": "2017-05-19T13:36:54.562Z"
}

Company Pager

URI

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

Send Internal 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

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

Send Fax

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

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
country Country Info Dialing plan country. If not specified then set by default based on the 'from' field value
faxResolution 'High' | 'Low' Fax resolution
sendTime datetime 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

Country Info

Parameter Type Description
isoCode string Country code in ISO 3166-1 alpha-2. If specified then country ID cannot be specified
id string Internal identifier of a country, see Country List. If specified then country ISO code cannot be specified

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 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'
filename string Name of a file attached
size integer Size of attachment in bytes

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
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888

--Boundary_1_14413901_1361871080888
Content-Type: application/json

{"to":[{"phoneNumber":"+18005630003"}],
 "faxResolution":"High",
 "country" : {
    "isoCode" : "IE"
  },
 "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 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
Content-Type: application/json

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

Fax Cover Pages

URI

/restapi/v1.0/dictionary/fax-cover-page

Get Available Fax Cover Pages

Since 8.2 (Release 1.0.26)

Returns fax cover pages available for the current extension.

Method

GET

API Group

Light

Request Body

None

Response Body

Parameter Type Description
uri string Canonical URI of fax cover pages resource
records Collection of Cover Page Info List of available cover pages

Cover Page Info

Parameter Type Description
id string Internal identifier of a fax cover page
name string Name of a fax cover page
paging Paging Info Information on paging
navigation Navigation Info Information on navigation

Example

Request example

GET /restapi/v1.0/dictionary/fax-cover-page HTTP/1.1

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/dictionary/fax-cover-page?page=1&perPage=100",
  "records" : [ {
    "id" : "0",
    "name" : "None"
  }, {
    "id" : "1",
    "name" : "Ancient"
  }, {
    "id" : "2",
    "name" : "Birthday"
  }, {
    "id" : "3",
    "name" : "Blank"
  }, {
    "id" : "4",
    "name" : "Clasmod"
  }, {
    "id" : "5",
    "name" : "Classic"
  }, {
    "id" : "6",
    "name" : "Confidential"
  }, {
    "id" : "7",
    "name" : "Contempo"
  }, {
    "id" : "8",
    "name" : "Elegant"
  }, {
    "id" : "9",
    "name" : "Express"
  }, {
    "id" : "10",
    "name" : "Formal"
  }, {
    "id" : "11",
    "name" : "Jazzy"
  }, {
    "id" : "12",
    "name" : "Modern"
  }, {
    "id" : "13",
    "name" : "Urgent"
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 100,
    "totalElements" : 14,
    "pageStart" : 0,
    "pageEnd" : 13
  },
  "navigation" : {
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/dictionary/fax-cover-page?page=1&perPage=100"
    },
    "lastPage" : {
      "uri" : "https.../restapi/v1.0/dictionary/fax-cover-page?page=1&perPage=100"
    }
  }
}

Message List

URI

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

Get Messages

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 Message Thread

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

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

URI

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

Get Message

Since 1.0.2

Returns individual message record(s) by 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 Conversation Info Deprecated. Supported for SMS and Pager for compatibility reasons only
creationTime datetime Message creation datetime in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
deliveryErrorCode string SMS only. Delivery error code returned by gateway
direction 'Inbound' | 'Outbound' Message direction. Note that for some message types not all directions are allowed. For example voicemail messages can be only inbound
faxPageCount integer Fax only. Page count in fax message
faxResolution 'High' | 'Low' Fax only. Resolution of fax message. ('High' for black and white image scanned at 200 dpi, 'Low' for black and white image scanned at 100 dpi)
coverIndex integer Fax only. Cover page identifier. For the list of available cover page identifiers please call the method Fax Cover Pages
coverPageText string Fax only. Cover page text, entered by the fax sender and printed on the cover page. Maximum length is limited to 1024 symbols
from Caller Info Sender information
lastModifiedTime datetime Datetime when the message was modified on server in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
messageStatus 'Queued' | 'Sent' | 'SendingFailed' | 'Delivered' | 'DeliveryFailed' | 'Received' Message status. 'Queued' - the 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)

Different message types may have different allowed status values. For outbound faxes the aggregated message status is returned:
  • If status for at least one recipient is 'Queued', then 'Queued' value is returned

  • If status for at least one recipient is 'SendingFailed', then 'SendingFailed' value is returned

  • In other cases Sent status is returned

pgToDepartment boolean Pager only. True if at least one of the message recipients is Department extension
priority 'Normal' | 'High' Message priority
readStatus 'Read' | 'Unread' Message read status
smsDeliveryTime datetime SMS only. 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
smsSendingAttemptsCount integer SMS only. Number of attempts made to send an outbound SMS to the gateway (if gateway is temporary unavailable)
subject string Message subject. For SMS and Pager messages it replicates message text which is also returned as an attachment
to Collection of Caller Info Recipient information
type 'Fax' | 'SMS' | 'VoiceMail' | 'Pager' | 'Text' Message type
vmTranscriptionStatus 'NotAvailable' | 'InProgress' | 'TimedOut' | 'Completed' | 'CompletedPartially' | 'Failed' Voicemail only. Status of voicemail to text transcription. If VoicemailToText feature is not activated for account, the 'NotAvailable' value is returned

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'
vmDuration integer Voicemail only Duration of the voicemail in seconds
width integer Image width in pixels
height integer Image height in pixels

Caller Info

Parameter Type Description
extensionNumber string Pager only. Extension number
phoneNumber string Phone number in a E.164 (with '+' sign) format
name string Symbolic name associated with a caller/callee. If the phone does not belong to the known extension, only the location is returned, the name is not determined then
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)
target boolean 'True' specifies that message is sent exactly to this recipient. Returned in to field for group MMS. Useful if one extension has several phone numbers
messageStatus 'Queued' | 'Sent' | 'SendingFailed' Message status. Returned for outbound fax messages only, in the from field. 'Queued' - the 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' Fax only. Error code returned in case of fax sending failure. Returned if messageStatus value is 'SendingFailed'

Conversation Info

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

Attachment Type Info

Message Type Attachment Type Description Supported Content Types
VoiceMail AudioRecording Auto recorded audio file

audio/x-wav

AudioTranscription Auto transcribed text file

text/plain

Fax RenderedDocument The file rendered from original format to TIFF or PDF; delivered to the recipient

application/pdf; image/vnd.adobe.photoshop; application/msword; application/vnd.ms-word.document.macroenabled.12; application/vnd.openxmlformats-officedocument.wordprocessingml.document; application/vnd.ms-excel; application/vnd.ms-excel.sheet.binary.macroenabled.12; application/vnd.ms-excel.sheet.macroenabled.12; application/vnd.openxmlformats-officedocument.spreadsheetml.sheet; application/vnd.ms-powerpoint; application/vnd.ms-powerpoint.presentation.macroenabled.12; application/vnd.openxmlformats-officedocument.presentationml.presentation; application/vnd.visioapplication/x-mspublisher; application/vnd.ms-works; application/x-mswrite; image/tiffimage/gif; image/jpeg; image/bmp; image/png; image/x-pcx; image/x-tga; application/vnd.wordperfect; application/rtf; text/plain; application/xml; text/html; text/csv; text/vcard

SMS/Pager Text Text format file

text/plain

MMS MmsAttachment MMS message attachment file

application/gz; application/rtf; application/zip; audio/mpeg; audio/amr; audio/m4a; image/bmp; image/gif; image/jpeg; image/png; image/svg+xml; image/tiff; text/html; text/plain; text/vcard; video/mp4; video/mpeg; video/msvideo; video/quicktime; video/x-flv; video/x-ms-wmv

Example 1

Get Voicemail message

Request example

GET /restapi/v1.0/account/14833636004/extension/14833636004/message-store/82063400004 HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFTzNXSmhtdUh0cUlRNENtT2NT
Accept: application/json  

Response example

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

{
  "uri" : "https.../restapi/v1.0/account/14833636004/extension/14833636004/message-store/82063400004",
  "id" : 82063400004,
  "to" : [ {
    "name" : "John Smith"
  } ],
  "from" : {
    "phoneNumber" : "+18664320079",
    "name" : "Generated voice message"
  },
  "type" : "VoiceMail",
  "creationTime" : "2015-04-01T04:39:19.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 82063400004,
    "uri" : "https.../restapi/v1.0/account/14833636004/extension/14833636004/message-store/82063400004/content/82063400004",
    "type" : "AudioRecording",
    "contentType" : "audio/x-wav",
    "vmDuration" : 30
  }, {
    "id" : 1897320004,
    "uri" : "https.../restapi/v1.0/account/14833636004/extension/14833636004/message-store/82063400004/content/1897320004",
    "type" : "AudioTranscription",
    "contentType" : "text/plain"
  } ],
  "direction" : "Inbound",
  "availability" : "Alive",
  "messageStatus" : "Received",
  "lastModifiedTime" : "2015-04-01T08:39:18.706Z",
  "vmTranscriptionStatus" : "Completed"
}             

Example 2

Get Pager message

Request example

GET /restapi/v1.0/account/400928048004/extension/400928050004/message-store/401081345004 HTTP/1.1
        

Response example

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

{
  "uri" : "https.../restapi/v1.0/account/400928048004/extension/400928050004/message-store/401081345004",
  "id" : 401081345004,
  "to" : [ {
    "extensionNumber" : "103"
    
  } ],
  "from" : {
    "extensionNumber" : "102",
    "name" : "Generated IM message"
  },
  "type" : "Pager",
  "creationTime" : "2014-09-01T19:26:45.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 401081345004,
    "uri" : "https.../restapi/v1.0/account/400928048004/extension/400928050004/message-store/401081345004/content/401081345004",
    "type" : "Text",
    "contentType" : "text/plain"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "subject" : "Sample message",
  "messageStatus" : "Sent",
  "conversationId" : 6951365551500,
  "lastModifiedTime" : "2014-09-01T12:26:44.114Z",
  "pgToDepartment" : false
}

Example 3

Get SMS message

Request example

GET /restapi/v1.0/account/12502999004/extension/12502999004/message-store/60279564004 HTTP/1.1
                

Response example

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

{
  "uri" : "https.../restapi/v1.0/account/12502999004/extension/12502999004/message-store/60279564004",
  "id" : 60279564004,
  "to" : [ {
    "phoneNumber" : "+16505393204",
    "location" : "San Mateo, CA"
  } ],
  "from" : {
    "phoneNumber" : "+18889450052"
  },
  "type" : "SMS",
  "creationTime" : "2015-02-18T13:24:50.000Z",
  "readStatus" : "Read",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 60279564004,
    "uri" : "https.../restapi/v1.0/account/12502999004/extension/12502999004/message-store/60279564004/content/60279564004",
    "type" : "Text",
    "contentType" : "text/plain"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "subject" : "Test SMS message from Platform server",
  "messageStatus" : "Sent",
  "smsSendingAttemptsCount" : 1,
  "conversationId" : 5578984350117917661,
  "lastModifiedTime" : "2015-02-18T13:24:50.300Z"
}

Example 4

Get MMS message

Request example

GET /restapi/v1.0/account/403391985008/extension/403391985008/message-store/403038404008 HTTP/1.1
                

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",
    "width": 640,
    "height": 480
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "subject" : "hello",
  "messageStatus" : "Sent",
  "smsSendingAttemptsCount" : 1,
  "conversationId" : 4671355828682655051,
  "lastModifiedTime" : "2017-04-14T13:46:54.838Z"
}

Example 5

Get Fax messages

Request example

GET /restapi/v1.0/account/1446856004/extension/1446856004/message-store/2147676004,2147694004 HTTP/1.1

Response example

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,
  "to" : [ {
    "phoneNumber" : "+79500123465",
    "messageStatus" : "SendingFailed",
    "faxErrorCode" : "InternationalDisabled"
  } ],
  "type" : "Fax",
  "creationTime" : "2015-11-30T11:04:49.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 2147676004,
    "uri" : "https.../restapi/v1.0/account/1446856004/extension/1446856004/message-store/2147676004/content/2147676004",
    "type" : "RenderedDocument",
    "contentType" : "application/pdf"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "messageStatus" : "SendingFailed",
  "faxResolution" : "High",
  "faxPageCount" : 2,
  "lastModifiedTime" : "2015-11-30T11:08:38.178Z",
  "coverIndex" : 7
}
--Boundary_4061_632833321_1448881816038
Content-Type: application/json

{
  "uri" : "https.../restapi/v1.0/account/1446856004/extension/1446856004/message-store/2147694004",
  "id" : 2147694004,
  "to" : [ {
    "phoneNumber" : "+18000675780",
    "messageStatus" : "Sent"
  } ],
  "type" : "Fax",
  "creationTime" : "2015-11-30T11:07:48.000Z",
  "readStatus" : "Unread",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 2147694004,
    "uri" : "https.../restapi/v1.0/account/1446856004/extension/1446856004/message-store/2147694004/content/2147694004",
    "type" : "RenderedDocument",
    "contentType" : "application/pdf"
  } ],
  "direction" : "Outbound",
  "availability" : "Alive",
  "messageStatus" : "Sent",
  "faxResolution" : "High",
  "faxPageCount" : 2,
  "lastModifiedTime" : "2015-11-30T11:09:30.845Z",
  "coverIndex" : 7
}
--Boundary_4061_632833321_1448881816038--

Update Message Read Status

Since 1.0.2

Updates message(s) by ID(s). Batch request is supported. Currently, only the message read status updating is supported.

Method

PUT

API Group

Medium

Required Permissions

Permission Description
EditMessages Viewing and updating 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 string Internal identifier of a message

Request Body

Parameter Type Description
readStatus 'Read' | 'Unread' Read status of a message to be changed. Multiple values are supported

Response Body

Message Info

Example 1

Request example

PUT /restapi/v1.0/account/1346632010/extension/1346632010/message-store/315433012010 HTTP/1.1

{"readStatus": "Read"}
                

Response example

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

{
    "uri" : ".../account/1346632010/extension/1346632010/message-store/1346632010/message-store/315433012010",
    "id" : 315433012010,
    "to" : [ {
        "phoneNumber" : "+18559100010"
    } ],
    "from" : {
        "phoneNumber" : "+16509101086"
    },
    "type" : "SMS",
    "creationTime" : "2012-09-13T14:46:37.000Z",
    "readStatus" : "Read",
    "priority" : "Normal",
    "attachments" : [ {
        "id" : 1,
        "uri" : ".../account/1346632010/extension/1346632010/message-store/1346632010/message-store/315433012010/content/1",
        "type" : "Text",
        "contentType" : "text/plain"
    } ],
    "direction" : "Inbound",
    "availability" : "Alive",
    "subject" : "This is a sample message",
    "messageStatus" : "Received",
    "conversationId" : 141549019326272744,
    "lastModifiedTime" : "2012-09-13T15:14:46.000Z"
}                

Example 2
Alternative Syntax

Request example

PUT /restapi/v1.0/account/404888975008/extension/404888975008/message-store/* HTTP/1.1
Content-Type: multipart/mixed; boundary=123456

--123456
Content-Type: application/json

["403679726008","403679698008"]
--123456
Content-Type: application/json

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

{"readStatus": "Read"}
--123456--  

Response example

HTTP/1.1 207 
Content-Type: multipart/mixed;boundary=Boundary_1_1993195661_1498731975173

--Boundary_1_1993195661_1498731975173
Content-Type: application/json

{
  "response" : [ {
    "href" : "https.../restapi/v1.0/account/404888975008/extension/404888975008/message-store/403679726008",
    "status" : 200,
    "responseDescription" : "OK"
  }, {
    "href" : "https.../restapi/v1.0/account/404888975008/extension/404888975008/message-store/403679698008",
    "status" : 200,
    "responseDescription" : "OK"
  } ]
}
--Boundary_1_1993195661_1498731975173
Content-Type: application/json

{
  "uri" : "https.../restapi/v1.0/account/404888975008/extension/404888975008/message-store/403679726008",
  "id" : 403679726008,
  "to" : [ {
    "name" : "James Bond"
  } ],
  "from" : {
    "phoneNumber" : "+18888984591",
    "name" : "Jane Bond"
  },
  "type" : "VoiceMail",
  "creationTime" : "2017-06-28T23:57:33.000Z",
  "readStatus" : "Read",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 403679726008,
    "uri" : "https.../restapi/v1.0/account/404888975008/extension/404888975008/message-store/403679726008/content/403679726008",
    "type" : "AudioRecording",
    "contentType" : "audio/x-wav",
    "vmDuration" : 42
  } ],
  "direction" : "Inbound",
  "availability" : "Alive",
  "subject" : "Welcome message",
  "messageStatus" : "Received",
  "lastModifiedTime" : "2017-06-29T10:26:15.174Z",
  "vmTranscriptionStatus" : "Unknown"
}
--Boundary_1_1993195661_1498731975173
Content-Type: application/json

{
  "uri" : "https.../restapi/v1.0/account/404888975008/extension/404888975008/message-store/403679698008",
  "id" : 403679698008,
  "to" : [ {
    "name" : "James Bond"
  } ],
  "from" : {
    "phoneNumber" : "+18882001178",
    "name" : "John Smith"
  },
  "type" : "VoiceMail",
  "creationTime" : "2017-06-28T23:57:28.000Z",
  "readStatus" : "Read",
  "priority" : "Normal",
  "attachments" : [ {
    "id" : 403679698008,
    "uri" : "https.../restapi/v1.0/account/404888975008/extension/404888975008/message-store/403679698008/content/403679698008",
    "type" : "AudioRecording",
    "contentType" : "audio/x-wav",
    "vmDuration" : 25
  } ],
  "direction" : "Inbound",
  "availability" : "Alive",
  "messageStatus" : "Received",
  "lastModifiedTime" : "2017-06-29T10:26:15.195Z",
  "vmTranscriptionStatus" : "NotAvailable"
}
--Boundary_1_1993195661_1498731975173--

Delete Message

Since 1.0.2

Deletes message(s) by the given message ID(s). The first call of this method transfers the message to the 'Delete' status. The second call transfers the deleted message to the 'Purged' status. If it is required to make the message 'Purged' immediately (from the first call), then set the query parameter purge to 'True'. Batch request is supported.

Method

DELETE

API Group

Medium

Required Permissions

Permission Description
EditMessages Viewing and updating 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 string Internal identifier of a message

Query Parameters

Parameter Type Description
purge boolean If the value is 'True', then the message is purged immediately with all the attachments. The default value is 'False'
conversationId string Internal identifier of a message thread

Request Body

None

Response Body

None

Example 1

Request example

DELETE /restapi/v1.0/account/1346632010/extension/1346632010/message-store/315433012010 HTTP/1.1

Response example

HTTP/1.1 204 No Content

Example 2
Alternative Syntax

Request example

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


[401350204008,401350202008]

Response example

HTTP/1.1 204 No Content

Message Attachment

URI

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

Get Message Attachment

Since 1.0.4 (Release 5.13)

Returns particular message attachment data as a media stream.

Method

GET

API Group

Medium

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
attachmentId string Internal identifier of a message attachment
messageId string Internal identifier of a message

Request Body

None

Response Body

The content of a message. For SMS messages the content is returned in .txt format with UTF-8 charset. For Fax messages the content is returned in TIFF (outcoming/incoming faxes) or PDF (incoming faxes)

Example

Request example

1.
GET /restapi/v1.0/account/1346632010/extension/1346632010/message-store/313600045010/content/1 HTTP/1.1
Authorization: Bearer U1BCMDFUMDRKV1MwMXwVVOaPwPu88hVU5oR0u-FQFVTmhA

2.
GET /restapi/v1.0/account/~/extension/~/message-store/402373285008/content/1 HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQV1MwM3w7y3hoN4VOvT1Vat2crMSnYJE6Sw
                

Response example

1.
HTTP/1.1 200 OK
Content-Type: text/plain;charset=utf-8

Test message from Platform server

2.
HTTP/1.1 200 OK
Content-Type: image/tiff
Content-Disposition: inline;filename=402373285008.tiff

<...binary...>
                

RingOut

The RingOut option enables users to make a call from any other outside number (not a RingCentral number) by means of their RingCentral account, when it is not convenient for them to use the RingCentral number. This feature is available for softphone, web and mobile applications. The RingCentral API allows to make and get RingOut calls.

Related Knowledge Base Articles

RingOut Call

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/ring-out

Please note: The URI /restapi/v1.0/account/{accountId}/extension/{extensionId}/ringout is deprecated, but still supported for backward compatibility.

Make RingOut Call

Since 1.0.7 (Release 5.16)

Makes RingOut call.

Method

POST

API Group

Heavy

Required Permissions

Permission Description
RingOut Performing two-legged ring-out phone calls

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 Phone number of the caller. This number corresponds to the 1st leg of the RingOut call. This number can be one of user's configured forwarding numbers or arbitrary number
to Caller Info Phone number of the callee. This number corresponds to the 2nd leg of the RingOut call
callerId Caller Info The number which will be displayed to the called party
playPrompt boolean The audio prompt that the calling party hears when the call is connected
country Country Info Optional. Dialing plan country data. If not specified, then extension home country is applied by default

Caller Info/ From

Parameter Type Description
phoneNumber string Phone number in E.164 format
forwardingNumberId string Internal identifier of a forwarding number; returned in response in the id field. Can be specified instead of the phoneNumber attribute

Caller Info/ To

Parameter Type Description
phoneNumber string Phone number in E.164 format

Country Info

Parameter Type Description
id string Dialing plan country identifier

Response Body

RingOut Info

Example 1

With the phoneNumber in 'from' field

Request example

POST /restapi/v1.0/account/1133926004/extension/1133926004/ring-out HTTP/1.1

{
    "from": {"phoneNumber": "+12053320032"},
    "to": {"phoneNumber": "+16052160005"},
    "playPrompt": true,
    "country": { "id" : "44" }
}

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/1133926004/extension/1133926004/ring-out/Y3MxNzE4NDI4NDkyODg0NDM5MDJAMTAuNjIuMjkuMzM",
  "id" : "Y3MxNzE4NDI4NDkyODg0NDM5MDJAMTAuNjIuMjkuMzM",
  "status" : {
    "callStatus" : "InProgress",
    "callerStatus" : "InProgress",
    "calleeStatus" : "InProgress"
  }
}

Example 2

With the forwardingNumberId in 'from' field

Request example

POST /restapi/v1.0/account/1133926004/extension/1133926004/ring-out HTTP/1.1

{
    "from": {"forwardingNumberId": "1472341004"},
    "to": {"phoneNumber": "+12052160005"},
    "playPrompt": true,
    "country": { "id" : "1" }
}

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/1133926004/extension/1133926004/ring-out/3MxNzE4NDI488NDkyODg0NDM5MDJAMTAuNjIuMjkuMzM",
  "id" : "3MxNzE4NDI488NDkyODg0NDM5MDJAMTAuNjIuMjkuMzM",
  "status" : {
    "callStatus" : "InProgress",
    "callerStatus" : "InProgress",
    "calleeStatus" : "InProgress"
  }
}

RingOut Call Status

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/ring-out/{ringoutId}

Please note: The URI /restapi/v1.0/account/{accountId}/extension/{extensionId}/ringout/{ringoutId} is deprecated, but still supported for backward compatibility.

Get Status of RingOut Call

Since 1.0.7 (Release 5.16)

Returns the status of a RingOut call.

Method

GET

API Group

Light

Required Permissions

Permission Description
RingOut Performing two-legged ring-out phone calls

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
ringoutId string Internal identifier of a RingOut call

Request Body

None

Response Body

Parameter Type Description
id string Internal identifier of a RingOut call
status RingOut Status Info RingOut status information

RingOut Status Info

Parameter Type Description
callStatus 'Success' | 'InProgress' | 'NoAnsweringMachine' | 'CannotReach' Status of a call. 'InProgress' - connection is being established; 'Success' - the call is connected (answered); 'CannotReach' - fail to connect a call (one of the parties is out of reach); 'NoAnsweringMachine' - internal server error
callerStatus 'Invalid' | 'Success' | 'InProgress' | 'Busy' | 'NoAnswer' | 'Rejected' | 'GenericError' | 'Finished' | 'InternationalDisabled' | 'DestinationBlocked' | 'NotEnoughFunds' | 'NoSuchUser' Status of a calling party
calleeStatus 'Invalid' | 'Success' | 'InProgress' | 'Busy' | 'NoAnswer' | 'Rejected' | 'GenericError' | 'Finished' | 'InternationalDisabled' | 'DestinationBlocked' | 'NotEnoughFunds' | 'NoSuchUser' Status of a called party

Example

Request example

GET /restapi/v1.0/account/~/extension/~/ring-out/Y3MxNzE4NDkyODg0NDM5MDJAMTAuNjIuMjkuMzM HTTP/1.1

Response example

HTTP/1.1 200 OK

{
  "uri" : "https:.../restapi/v1.0/account/400162076008/extension/400162076009/ring-out/2",
    "id" : "Y3MxNzE4NDkyODg0NDM5MDJAMTAuNjIuMjkuMzM",
    "status" : {
      "callStatus" : "Success",
      "callerStatus" : "Success",
      "calleeStatus" : "Success"
    }
}

Cancel RingOut Call

Since 1.0.7 (Release 5.16)

Cancels a RingOut call.

Method

DELETE

API Group

Heavy

Required Permissions

Permission Description
RingOut Performing two-legged ring-out phone calls

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
ringoutId string Internal identifier of a RingOut call

Request Body

None

Response Body

None

Example

Request example

DELETE /restapi/v1.0/account/~/extension/~/ring-out/Y3MxNzE4NDk HTTP/1.1

Response example

HTTP/1.1 204 No Content

User Contacts

User address book stores the detailed list of personal contacts.

Phone numbers are specified in E.164 format, may include DTMF sequences; vanity and short numbers are also supported, for example:

  • +16501234567

  • +16501234567#

  • +16501234567*101

  • +1800SURFERS

  • 1234

Both full country names and code names (ISO Alpha 3, ISO Alpha 2) are supported, for example:

  • Czech Republic

  • CZE

  • CZ

Even if request body contains a short country name, the full name correspondence will be returned in response.

Related Knowledge Base Articles

Contact List

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/address-book/contact

Get Contacts

Since 1.0.4 (Release 5.13)

Returns a list of user contacts.

Method

GET

API Group

Heavy

Required Permissions

Permission Description
ReadContacts Viewing user personal contacts

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
phoneNumber string Phone number in E.164 (11-digits) format with or without plus '+'. Multiple values are supported
startsWith string If specified, only contacts whose first name or last name start with the mentioned substring are returned. Case-insensitive
sortBy 'FirstName' | 'LastName' | 'Company' Sorts results by the specified property. The default is 'First Name'
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 Personal Contact Info List of personal contacts from the extension address book
navigation Navigation Info Information on navigation
paging Paging Info Information on paging

Example

Request example

GET /restapi/v1.0/account/403800692008/extension/403800692008/address-book/contact?sortBy=FirstName&page=1&phoneNumber=16502223344&phoneNumber=16503334455 HTTP/1.1

Response example

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

{
  "uri" : "https.../restapi/v1.0/account/403800692008/extension/403800692008/address-book/contact?phoneNumber=16502223344&phoneNumber=16503334455&sortBy=FirstName",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/403800692008/extension/403800692008/address-book/contact/405030022008",
    "availability" : "Alive",
    "id" : 405030022008,
    "firstName" : "Leo",
    "lastName" : "Wonders",
    "birthday" : "1970-01-01T00:00:00.000Z",
    "mobilePhone" : "+16503334455"
  }, {
    "uri" : "https.../restapi/v1.0/account/403800692008/extension/403800692008/address-book/contact/405030021008",
    "availability" : "Alive",
    "id" : 405030021008,
    "firstName" : "Paul",
    "lastName" : "Smith",
    "birthday" : "1970-01-01T00:00:00.000Z",
    "mobilePhone" : "+16502223344"
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 100,
    "totalElements" : 2,
    "pageStart" : 0,
    "pageEnd" : 1
  },
  "navigation" : {
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/403800692008/extension/403800692008/address-book/contact?phoneNumber=16502223344&phoneNumber=16503334455&sortBy=FirstName&page=1&perPage=100"
    },
    "lastPage" : {
      "uri" : "https.../restapi/v1.0/account/403800692008/extension/403800692008/address-book/contact?phoneNumber=16502223344&phoneNumber=16503334455&sortBy=FirstName&page=1&perPage=100"
    }
  },
  "groups" : {
    "uri" : "https.../restapi/v1.0/account/403800692008/extension/403800692008/address-book/group"
  }
}

Create Contact

Since 1.0.4 (Release 5.13)

Adds a new personal contact to the user address book.

Method

POST

API Group

Heavy

Required Permissions

Permission Description
Contacts Creating, viewing, editing and deleting user personal contacts

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
firstName string First name of a personal contact
lastName string Last name of a personal contact
middleName string Middle name of a personal contact
nickName string Nick name of a personal contact
company string Company name of a personal contact
jobTitle string Job title of a personal contact
homePhone string Home phone of a personal contact in E.164 format
homePhone2 string The 2-d home phone of a personal contact in E.164 format
businessPhone string Business phone of a personal contact in E.164 format
businessPhone2 string The 2-d business phone of a personal contact in E.164 format
mobilePhone string Mobile phone of a personal contact in E.164 format
businessFax string Business fax of a personal contact
companyPhone string Company phone of a personal contact in E.164 format
assistantPhone string Assistant phone of a personal contact in E.164 format
carPhone string Car phone of a personal contact in E.164 format
otherPhone string Other phone of a personal contact in E.164 format
otherFax string Other fax of a personal contact
callbackPhone string Callback phone of a personal contact in E.164 format
email string Email of a personal contact
email2 string The 2-d email of a personal contact
email3 string The 3-d email of a personal contact
homeAddress Contact Address Info Home address of a personal contact
businessAddress Contact Address Info Business address of a personal contact
otherAddress Contact Address Info Other address of a personal contact
birthday datetime Date of birth of a personal contact ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
webPage string Web page of a personal contact
notes string Notes of a personal contact

Response Body

Personal Contact Info

Example

Request example

POST /restapi/v1.0/account/401797460008/extension/401797460008/address-book/contact HTTP/1.1

{
  "firstName": "John",
  "lastName": "Smith",
  "businessPhone": "+16507893542",
  "businessAddress": {
    "city": "Manchester",
    "country": "GBR"
  }
}

Response example

HTTP/1.1 200 OK

{
  "uri" : "https://.../restapi/v1.0/account/401797460008/extension/401797460008/address-book/contact/402762719008",
  "availability" : "Alive",
  "id" : 402762719008,
  "firstName" : "John",
  "businessAddress" : {
    "city" : "Manchester",
    "country" : "United Kingdom"
  },
  "lastName" : "Smith",
  "businessPhone" : "+16507893542"
}

Contact

URI

/restapi/v1.0/account/{accountId}/extension/{extensionId}/address-book/contact/{contactId}

Get Contact

Since 1.0.4 (Release 5.13)

Returns contact(s) by ID. Batch request is supported.

Method

GET

API Group

Heavy

Required Permissions

Permission Description
ReadContacts Viewing user personal contacts

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
contactId string Internal identifier of a contact record in the RingCentral database

Request Body

None

Response Body

Parameter Type Description
id string Internal identifier of a contact
uri string Canonical URI of a contact
availability 'Alive' | 'Deleted' | 'Purged' This property has a special meaning only on Address Book Sync (e.g. a contact can be 'Deleted'). For simple contact list reading it has always the default value - 'Alive'
firstName string First name of a personal contact
lastName string Last name of a personal contact
middleName string Middle name of a personal contact
nickName string Nick name of a personal contact
company string Company name of a personal contact
jobTitle string Job title of a personal contact
homePhone string Home phone of a personal contact
homePhone2 string The 2-d home phone of a personal contact
businessPhone string Business phone of a personal contact in E.164 format
businessPhone2 string The 2-d business phone of a personal contact in E.164 format
mobilePhone string Mobile phone of a personal contact in E.164 format
businessFax string Business fax of a personal contact
companyPhone string Company phone of a personal contact
assistantPhone string Assistant phone of a personal contact
carPhone string Car phone of a personal contact
otherPhone string Other phone of a personal contact
otherFax string Other fax of a personal contact
callbackPhone string Callback phone of a personal contact
email string Email of a personal contact
email2 string The 2-d email of a personal contact
email3 string The 3-d email of a personal contact
homeAddress Contact Address Info Home address of a personal contact
businessAddress Contact Address Info Business address of a personal contact
otherAddress Contact Address Info Other address of a personal contact
birthday datetime Date of birth of a personal contact ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
webPage string Web page of a personal contact
notes string Notes of a personal contact

Example

Request example

GET /restapi/v1.0/account/~/extension/~/address-book/contact/3252939008 HTTP/1.1

Response example

HTTP/1.1 200 OK
 
 {
  "uri" : ".../restapi/v1.0/account/284818008/extension/284818008/address-book/contact/3252939008",
  "id" : 3252939008,
  "availability" : "Alive",
  "firstName" : "Mira",
  "lastName" : "Soul",
  "company" : "Copenhagen",
  "jobTitle" : "Manager",
  "homePhone" : "+1855576767635",
  "companyPhone" : "+1845648656565"
}

Update Contact

Since 1.0.4 (Release 5.13)

Updates personal contact(s) information by contact ID(s).

Method

PUT

API Group

Heavy

Required Permissions

Permission Description
Contacts Creating, viewing, editing and deleting user personal contacts

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
contactId string Internal identifier of a contact record in the RingCentral database

Request Body

Personal Contact Info with the changed fields. If a field is not specified in the request, its value is cleared (the already set old value is not preserved).

Response Body

Personal Contact Info with the updated fields.

Example

Request example

PUT /restapi/v1.0/account/401797460008/extension/401797460008/address-book/contact/402762719008 HTTP/1.1


{
    "firstName" : "John",
    "lastName" : "Smith",
    "company" : "MyCompany",
     "businessAddress": {
    "city": "Reykjavik",
    "country": "ISL"
  },
    "jobTitle" : "Musician",
    "homePhone" : "+18764545488"

}                

Response example

HTTP/1.1 200 OK

{
  "uri" : "https://.../restapi/v1.0/account/401797460008/extension/401797460008/address-book/contact/402762719008",
  "availability" : "Alive",
  "id" : 402762719008,
  "company" : "MyCompany",
  "firstName" : "John",
  "businessAddress" : {
    "city" : "Reykjavik",
    "country" : "Iceland"
  },
  "lastName" : "Smith",
  "jobTitle" : "Musician",
  "homePhone" : "+18764545488"
}      

Delete Contact

Since 1.0.4 (Release 5.13)

Deletes contact(s) by contact ID(s).

Method

DELETE

API Group

Heavy

Required Permissions

Permission Description
Contacts Creating, viewing, editing and deleting user personal contacts

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
contactId string Internal identifier of a contact record in the RingCentral database

Request Body

None

Response Body

None

Example

Request example

DELETE /restapi/v1.0/account/~/extension/~/address-book/contact/3252938008 HTTP/1.1
        

Response example

HTTP/1.1 204 No Content

Favorites

URI

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

Get Favorite Contacts

Since 1.0.25 (Release 8.1)

Returns favorite contacts of the current extension. Favorite contacts include both company contacts (extensions) and personal contacts (address book records).

Method

GET

API Group

Medium

Required Permissions

Permission Description
ReadContacts Viewing user personal contacts

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 Header

Client app may pass local ETag value in the If-None-Match header. If there were no changes of the favorite contacts (adding new / removal / change of order by ID) since the previous call of this method, the HTTP status code 304 Not Modified is returned. If there were changes and/or the value of the header is not specified, then full response is returned with the HTTP status code 200 OK and the current ETag value in the ETag response header.

Request Body

None

Response Header

The ETag value corresponding to the current state of the favorites contacts.

Response Body

Parameter Type Description
uri string Canonical URI of a favorite contacts resource
records Collection of Favorite Contact Info List of favorite contacts. The maximum number of favorites is 100 per extension

Favorite Contact Info

Parameter Type Description
id string Ordinal identifier of a favorite contact
extensionId string Internal identifier of an extension. Returned for company contacts
contactId string Internal identifier of a contact. Returned for personal contacts
accountId string Internal identifier of an account that contact is assigned to. Returned for extensions which do not belong to the current account

Example 1

The header 'If-None-Match' is not specified

Request example

GET /restapi/v1.0/account/401261011008/extension/401261011008/favorite HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQURIZjAzWFFySGpMMHpFRXkyWTZCbVhqcVFNM3JpY1E

Response example

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

{
  "uri" : "https.../restapi/v1.0/account/401261011008/extension/401261011008/favorite",
  "records" : [ {
    "id" : 1,
    "extensionId" : "401261014008",
    "accountId": "401261011008"
  }, {
    "id" : 2,
    "contactId" : "401889411008"
  }, {
    "id" : 3,
    "extensionId" : "401261013008"
  } ]
}

Example 2

The header 'If-None-Match' is specified and Favorites have been changed since the previous call of the method

Request example

PUT https.../restapi/v1.0/account/401261011008/extension/401261011008/favorite HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQURIZjAzWFFySGpMMHpFRXkyWTZCbVhqcVFNM3JVRGtE
Content-Type: application/json
If-None-Match: 1459865426724
Content-Length: 87

{
  "records" : [
   
    
    { "id" : 1,
      "extensionId": "401261013008",
      "accountId: "401261011008"}
  ]
}

Response example

HTTP/1.1 201 Created
ETag: "1459868017953"
Content-Language: en-US
Content-Type: application/json; charset=UTF-8

{
  "uri" : "https.../restapi/v1.0/account/401261011008/extension/401261011008/favorite",
  "records" : [ {
    "id" : 1,
    "extensionId" : "401261013008",
    "accountId: "401261011008"
  } ]
}

Example 3

The header 'If-None-Match' is specified and Favorites have not been changed since the previous call of the method

Request example

GET /restapi/v1.0/account/401261011008/extension/401261011008/favorite HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwMXxBQURIZjAzWFFySGpMMHpFRXkyWTZCbVhq
If-None-Match: "1459865439200"

Response example

HTTP/1.1 304 Not Modified
ETag: "1459865439200"
Content-Language: en-US

Update Favorite Contacts

Since 1.0.25 (Release 8.1)

Updates favorite contacts of the current extension. Favorite contacts include both company contacts (extensions) and personal contacts (address book records).

Method

PUT

API Group

Medium

Required Permissions

Permission Description
Contacts Creating, viewing, editing and deleting user personal contacts

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
records Collection of Favorite Contact Info List of favorite contacts

Response Header

The ETag value corresponding to the current state of the favorites contacts.

Response Body

Parameter Type Description
uri string Canonical URI of a favorite contacts resource
records Collection of Favorite Contact Info List of favorite contacts. The maximum number of favorites is 100 per extension

Example

Request example

PUT /restapi/v1.0/account/401261011008/extension/401261011008/favorite HTTP/1.1
If-None-Match: 


{
  "records" : [
    {
      "id" : 3,
      "extensionId": "401261014008",
      "accountId" : "401261011008"
    },
    { "id" : 1,
      "extensionId": "401261013008"},
    {
      "id" : 2,
      "contactId": "401889411008"
    }
  ]
}

Response example

HTTP/1.1 201 Created
ETag: "1459865100548"

{
  "uri" : "https.../restapi/v1.0/account/401261011008/extension/401261011008/favorite",
  "records" : [ {
    "id" : 1,
    "extensionId" : "401261013008"
  }, {
    "id" : 2,
    "contactId" : "401889411008"
  }, {
    "id" : 3,
    "extensionId" : "401261014008",
    "accountId" : "401261011008"
  } ]
}

Company Contacts

Extension List

URI

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

Get Extensions

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' | 'Bot' 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

Response example

HTTP/1.1 200 OK


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

Presence

User Presence

URI

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

Get User Status

Since 1.0.2

Returns presence status of an extension or several extensions by their ID(s).

The presenceStatus is returned as Offline (the parameters telephonyStatus, message, userStatus and dndStatus are not returned at all) for the following extension types: Department, Announcement Only, Take Messages Only (Voicemail), Fax User, Paging Only Group, Shared Lines Group, IVR Menu, Application Extension.

If the user requests his/her own presence status, the response contains actual presence status even if the status publication is turned off.

Batch request is supported. For batch requests the number of extensions in one request is limited to 30. If more extensions are included in the request, the error code 400 Bad Request is returned with the logical error code InvalidMultipartRequest and the corresponding message 'Extension Presence Info multipart request is limited to 30 extensions'.

Method

GET

API Group

Light

Required Permissions

Permission Description
ReadPresence Getting user presence information

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
detailedTelephonyState boolean If 'True' detailed presence information (including active calls) is returned
sipData boolean If 'True' sip data is returned

Request Body

None

Response Body

Property Type Description
uri string Canonical URI of a presence info resource
dndStatus 'TakeAllCalls' | 'DoNotAcceptAnyCalls' | 'DoNotAcceptDepartmentCalls' | 'TakeDepartmentCallsOnly' Extended DnD (Do not Disturb) status. Cannot be set for Department/Announcement/Voicemail (Take Messages Only)/Fax User/Shared Lines Group/Paging Only Group/IVR Menu/Application Extension/Park Location extensions. The 'DoNotAcceptDepartmentCalls' and 'TakeDepartmentCallsOnly' values are applicable only for extensions - members of a Department; if these values are set for department outsiders, the 400 Bad Request error code is returned. The 'TakeDepartmentCallsOnly' status can be set through the old RingCentral user interface and is available for some migrated accounts only
extension Extension Info Information on extension, for which this presence data is returned
message string Custom status message (as previously published by user)
presenceStatus 'Offline' | 'Busy' | 'Available' Aggregated presence status, calculated from a number of sources
allowSeeMyPresence boolean If 'True' enables other extensions to see the extension presence status
pickUpCallsOnHold boolean If 'True' enables the extension user to pick up a monitored line on hold
ringOnMonitoredCall boolean If 'True' enables to ring extension phone, if any user monitored by this extension is ringing
telephonyStatus 'NoCall' | 'CallConnected' | 'Ringing' | 'OnHold' | 'ParkedCall' Telephony presence status
userStatus 'Offline' | 'Busy' | 'Available' User-defined presence status (as previously published by the user)
activeCalls Collection of Active Call Info Information on active calls

Active Call Info

Parameter Type Description
id string Internal identifier of a call
direction 'Inbound' | 'Outbound' Call direction
from string Phone number or extension number of a caller
to string Phone number or extension number of a callee
telephonyStatus 'NoCall' | 'CallConnected' | 'Ringing' | 'OnHold' | 'ParkedCall' Telephony call status. See Telephony Status Values for detailed status description
sessionId string Internal identifier of a call session
sipData SIP Data SIP connection settings

SIP Data

Parameter Type Description
toTag string Recipient data
fromTag string Sender data
remoteUri string Remote address URL
localUri string Local address URL

Extension Info

Value Type Description
id string Internal identifier of an extension
uri string Canonical URI of an extension
extensionNumber string Extension number (usually 3 or 4 digits)

Telephony Status Values

Value Description
CallConnected Telephony connection has been established and the call is active
NoCall The call is disconnected
OnHold The call is put on hold
Ringing Telephony connection is being established, destination phone is ringing, and source phone receives long tones
ParkedCall The call is put on hold at one telephone set to be continued from any other telephone set

Example

Request example

GET /restapi/v1.0/account/11262119004/extension/11262126004/presence?detailedTelephonyState=true&sipData=true HTTP/1.1
     

Response example

HTTP/1.1 200 OK

{
   "uri": "https.../restapi/v1.0/account/11262119004/extension/11262126004/presence",
   "extension":    {
      "uri": "https.../restapi/v1.0/account/11262119004/extension/11262126004",
      "id": 11262126004,
      "extensionNumber": "103"
   },
   "presenceStatus": "Busy",
   "telephonyStatus": "CallConnected",
   "userStatus": "Available",
   "dndStatus": "TakeAllCalls",
   "allowSeeMyPresence": true,
   "ringOnMonitoredCall": false,
   "pickUpCallsOnHold": false,
   "activeCalls": [   {
      "id": "bce9fb7f62ec4b2c905b82ae0d5e39f0",
      "direction": "Inbound",
      "from": "102",
      "to": "103",
      "telephonyStatus": "CallConnected",
      "sipData":       {
         "toTag": "32185be3190742b5a08ae8c01abf15bd",
         "fromTag": "10.62.30.234-5070-8a7127fe15ed45",
         "remoteUri": "sip:102@ringcentral.com",
         "localUri": "sip:103@ringcentral.com"
      },
      "sessionId": "31730613004"
   }]
}
         

Update User Status

Since 1.0.2

Updates user-defined extension(s) presence status, status message and DnD status by extension ID(s). Supports only regular User extensions. Batch request is supported.

The extension types listed do not support presence status: Department, Announcement Only, Take Messages Only (Voicemail), Fax User, Paging Only Group, Shared Lines Group, IVR Menu, Application Extension.

Method

PUT

API Group

Medium

Required Permissions

Permission Description
EditPresence Getting and modifying user presence information

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
userStatus 'Available' | 'Busy' | 'Offline' User-defined presence status
dndStatus 'TakeAllCalls'| 'DoNotAcceptAnyCalls'| 'DoNotAcceptDepartmentCalls' | 'TakeDepartmentCallsOnly' Extended DnD (Do not Disturb) status. Cannot be set for Department/Announcement/Voicemail (Take Messages Only)/Fax User/Shared Lines Group/Paging Only Group/IVR Menu/Application Extension extensions. The 'DoNotAcceptDepartmentCalls' and 'TakeDepartmentCallsOnly' values are applicable only for extensions - members of a Department; if these values are set for department outsiders, the 400 Bad Request error code is returned. The 'TakeDepartmentCallsOnly' status can be set through the old RingCentral user interface and is available for some migrated accounts only
message string Custom status message
allowSeeMyPresence boolean 'True' enables other extensions to see the extension presence status. Allowed only for account owner/admin
pickUpCallsOnHold boolean 'True' enables the extension user to pick up a monitored line on hold. Allowed only for account owner/admin
ringOnMonitoredCall boolean 'True' enables to ring extension phone, if any user monitored by this extension is ringing. Allowed only for account owner/admin

Response Body

Presence Info

Example

Request example

PUT /restapi/v1.0/account/3227902004/extension/3227902004/presence HTTP/1.1


{
           "userStatus": "Available",
           "dndStatus": "TakeAllCalls",
           "message": "Available till 7 pm",
           "allowSeeMyPresence": true,
           "ringOnMonitoredCall": true,
           "pickUpCallsOnHold": true
}
     

Response example

HTTP/1.1 200 OK

{
  "uri" : "https.../restapi/v1.0/account/3227902004/extension/3227902004/presence",
  "extension" : {
    "uri" : "https.../restapi/v1.0/account/3227902004/extension/3227902004",
    "id" : 3227902004,
    "extensionNumber" : "101"
  },
  "presenceStatus" : "Available",
  "telephonyStatus" : "NoCall",
  "userStatus" : "Available",
  "dndStatus" : "TakeAllCalls",
  "message" : "Available till 7 pm",
  "allowSeeMyPresence" : true,
  "ringOnMonitoredCall" : true,
  "pickUpCallsOnHold" : true
}            

Glip [Beta]

Glip Companies

URI

/restapi/v1.0/glip/companies/{companyId}

Get Company Info

Since 1.0.28 (Release 8.4)

Returns a company by ID.

Method

GET

API Group

Light

Required Permissions

Permission Description
Glip Availability of Glip

Path Parameters

Parameter Type Description
companyId string Internal identifier of an RC account/Glip company, or tilde (~) to indicate a company the current user belongs to

Request Body

None

Response Body

Parameter Type Description
id string Internal identifier of an RC account/Glip company, or tilde (~) to indicate a company the current user belongs to
name string Name of a company
domain string Domain name of a company
creationTime string Datetime of creation in ISO 8601 format
lastModifiedTime string Datetime of last modification in ISO 8601 format

Example

Request example

GET /restapi/v1.0/glip/companies/2345678 HTTP/1.1

Response example

HTTP/1.1 200 OK

{
  "id" : "2345678",
  "name" : "MyCompany Inc.",
  "domain" : "mycompany.example.com",
  "creationTime" : "2016-12-15T12:00:00Z",
  "lastModifiedTime" : "2016-12-15T12:00:00Z"
}
      

Glip Groups

URI

/restapi/v1.0/glip/groups

Get User Groups

Since 1.0.28 (Release 8.4)

Returns the list of groups associated with the user.

Method

GET

API Group

Medium

Required Permissions

Permission Description
Glip Availability of Glip

Query Parameters

Parameter Type Description
type 'PrivateChat' | 'Group' | 'Team' Type of a group. 'PrivateChat' is a group of 2 members. 'Group' is a chat of 2 and more participants, the membership cannot be changed after group creation. 'Team' is a chat of 1 and more participants, the membership can be modified in future
pageToken string Token of a page to be returned, see Glip Navigation Info
recordCount integer Max numbers of records to be returned. The default/maximum value is 250

Request Body

None

Response Body

Parameter Type Description
records Collection of Glip Group Info List of groups/teams/private chats
navigation Glip Navigation Info Information on navigation

Glip Navigation Info

Parameter Type Description
prevPageToken string Previous page token. To get previous page, user should pass one of returned token in next request and, in turn, required page will be returned with new tokens
nextPageToken string Next page token. To get next page, user should pass one of returned token in next request and, in turn, required page will be returned with new tokens

Example

Request example

GET /restapi/v1.0/glip/groups HTTP/1.1

Response example

HTTP/1.1 200 OK
{
  "records" : [ {
    "id": "87654321",
    "type": "Team",
    "name":"My Team",
    "isPublic": true,
    "description": "Best team ever",
    "creationTime": "2017-01-23T17:00:00Z",
    "lastModifiedTime": "2017-02-1-T17:09:00Z",
    "members": ["12345678", "glip-43218765"]
  }, {
    "id": "43218765",
    "type": "PrivateChat",
    "creationTime": "2017-01-25T17:00:00Z",
    "lastModifiedTime": "2017-01-11T16:39:00Z",
    "members": ["12345678", "56781234"]
  } ],
  "navigation" : {
    "prevPageToken" : "fgghjsdgfsjf",
    "nextPageToken" : "62hdfjhq87xjh"
  }
}
      

Create Group

Since 1.0.28 (Release 8.4)

Creates a group.

Method

POST

API Group

Medium

Required Permissions

Permission Description
Glip Availability of Glip

Request Body

Parameter Type Description
type 'PrivateChat' | 'Team' Type of a group to be created. 'PrivateChat' is a group of 2 members. 'Team' is a chat of 1 and more participants, the membership can be modified in future
isPublic boolean For 'Team' group type only. Team access level
name string For 'Team' group type only. Team name
description string For 'Team' group type only. Team description
members Collection of string Identifier(s) of group members. For 'PrivateChat' group type 2 members only are supported

Response Body

Glip Group Info

Example

Request example

POST /restapi/v1.0/glip/groups
{
  "type": "Team",
  "isPublic": true,
  "name": "My Team",
  "description": "Best team ever",
  "members": ["12345678", "johndoe@example.com"]
}

Response example

HTTP 200 OK

{
  "id": "87654321",
  "type": "Team",
  "name":"My Team",
  "isPublic": true,
  "description": "Best team ever",
  "creationTime": "2017-01-23T17:00:00Z",
  "lastModifiedTime": "2017-01-23T17:09:00Z",
  "members": ["12345678", "glip-43218765"]
} 

Glip Group

URI

/restapi/v1.0/glip/groups/{groupId}

Get Group

Since 1.0.28 (Release 8.4)

Returns a group or few groups by ID(s). Batch request is supported.

Method

GET

API Group

Light

Required Permissions

Permission Description
Glip Availability of Glip

Path Parameters

Parameter Type Description
groupId string Internal identifier of a group to be returned, the maximum number of IDs is 30

Request Body

None

Response Body

Parameter Type Description
id string Internal identifier of a group
type 'PrivateChat' | 'Group' | 'Team' Type of a group. 'PrivateChat' is a group of 2 members. 'Group' is a chat of 2 and more participants, the membership cannot be changed after group creation. 'Team' is a chat of 1 and more participants, the membership can be modified in future
isPublic boolean For 'Team' group type only. Team access level
name string For 'Team' group type only. Team name
description string For 'Team' group type only. Team description
members Collection of string Identifier(s) of group members
creationTime datetime Group creation datetime in ISO 8601 format
lastModifiedTime datetime Group last change datetime in ISO 8601 format

Example 1

Get single group

Request example

GET /restapi/v1.0/glip/groups/567890 HTTP/1.1

Response example

HTTP/1.1 200 OK

{
  "id": "567890",
  "type": "Team",
  "name":"My Team",
  "isPublic": true,
  "description": "Best team ever",
  "creationTime": "2017-01-23T17:00:00Z",
  "lastModifiedTime": "2017-01-23T17:09:00Z",
  "members": ["12345678", "glip-43218765"]
}
      

Example 2

Get several groups

Request example

GET /restapi/v1.0/glip/groups/6090235906,6090244098 HTTP/1.1

Response example

HTTP/1.1 207 Multi-Status

--glboundary_EFtjbFdNp9tDZmrUa3LQZJ7dYyL5tpsMJgJ7
Content-type: application/json; charset=utf-8
Content-length: 44

{"response":[{"status":200},{"status":200}]}
--glboundary_EFtjbFdNp9tDZmrUa3LQZJ7dYyL5tpsMJgJ7
Content-type: application/json; charset=utf-8
Content-length: 218

{"id":6090235906,
"name":"jane.smith+john.smith",
"type":"Group",
"members":["986580011","61307231006"],
"isPublic":false,
"creationTime":"2015-10-06T12:39:43.471Z",
"lastModifiedTime":"2015-12-01T22:29:06.753Z"}
--glboundary_EFtjbFdNp9tDZmrUa3LQZJ7dYyL5tpsMJgJ7
Content-type: application/json; charset=utf-8
Content-length: 220

{"id":6090244098,
"name":"joe.black+jane.smith",
"type":"Group",
"members":["207846020","61307231006"],
"isPublic":false,
"creationTime":"2015-10-06T12:40:11.489Z",
"lastModifiedTime":"2015-10-07T03:36:00.146Z"}
--glboundary_EFtjbFdNp9tDZmrUa3LQZJ7dYyL5tpsMJgJ7--

      

Edit Glip Group

URI

/restapi/v1.0/glip/groups/{groupId}/bulk-assign

Edit Group Members

Since 1.0.28 (Release 8.4)

Updates group members. Please note: Only groups of 'Team' type can be updated. Currently only one operation at a time (either adding or removal) is supported.

Method

POST

API Group

Medium

Required Permissions

Permission Description
Glip Availability of Glip

Path Parameters

Parameter Type Description
groupId string Internal identifier of a group to be edited

Request Body

Parameter Type Description
addedPersonIds Collection of string List of users to be added to the team
addedPersonEmails Collection of string List of user email addresses to be added to the team (i.e. as guests)
removedPersonIds Collection of string List of users to be removed from the team

Response Body

Glip Group Info

Example 1

Add members to a group

Request example

POST /restapi/v1.0/glip/groups/12345678/bulk-assign
 
{
   "addedPersonIds": ["444555666", "112345678"],
   "addedPersonEmails": [ "john.doe@example.com" ]
}

Response example

HTTP 200 OK
 
{
  "id": "12345678",
  "type": "Team",
  "name":"My Team",
  "isPublic": true,
  "description": "Best team ever",
  "creationTime": "2017-01-23T17:00:00Z",
  "lastModifiedTime": "2017-01-23T17:09:00Z",
  "members": ["111222333", "444555666", "112345678", "777888999"]
}

Example 2

Remove members from a group

Request example

POST /restapi/v1.0/glip/groups/12345678/bulk-assign
 
{
   "removedPersonIds": [ "777888999" ]
}

Response example

HTTP 200 OK
 
{
  "id": "12345678",
  "type": "Team",
  "name":"My Team",
  "isPublic": true,
  "description": "Best team ever",
  "creationTime": "2017-01-23T17:00:00Z",
  "lastModifiedTime": "2017-01-23T17:09:00Z",
  "members": ["111222333", "444555666", "112345678"]
}

Glip Person

URI

/restapi/v1.0/glip/persons/{personId}

Get Person

Since 1.0.28 (Release 8.4)

Returns a user or few users by ID(s). Batch request is supported.

Method

GET

API Group

Light

Required Permissions

Permission Description
Glip Availability of Glip

Path Parameters

Parameter Type Description
personId string Internal identifier of a user to be returned, the maximum number of IDs is 30

Request Body

None

Response Body

Parameter Type Description
id string Internal identifier of a user
firstName string First name of a user
lastName string Last name of a user
email string Email of a user
avatar string Photo of a user
companyId string Internal identifier of a company
creationTime datetime Time of creation in ISO 8601 format
lastModifiedTime datetime Time of last modification in ISO 8601 format

Example 1

Get single user

Request example

GET /restapi/v1.0/glip/persons/123456

Response example

HTTP 200 OK

{
  "firstName" : "John",
  "lastName" : "Doe",
  "companyId" : "456789",
  "lastModifiedTime" : "2016-12-15T12:00:00Z",
  "creationTime" : "2016-12-15T12:00:00Z",
  "id" : "123456",
  "avatar" : "https://glip-prod.s3.amazonaws.com/web/customer_files/123456/ava.jpg",
  "email" : "john.doe@example.com"
}
 

Example 2

Get several users

Request example

GET /restapi/v1.0/glip/persons/207846020,1561574010,986580011 HTTP/1.1

Response example

HTTP/1.1 207 Multi-Status

--glboundary_ra08P31TSV3q70pPgdwc9UKlfihy9q
Content-type: application/json; charset=utf-8
Content-length: 59

{"response":[{"status":200},{"status":200},{"status":200}]}
--glboundary_ra08P31TSV3q70pPgdwc9UKlfihy9q
Content-type: application/json; charset=utf-8
Content-length: 492

{"id":"207846020",
"firstName":"Joe",
"lastName":"Black",
"gender":"male",
"email":"joe.black@example.com",
"location":"Saint-Petersburg",
"avatar":"https://glip-prod.s3.amazonaws.com/web/customer_files/19143229452/avatar.png",
"companyId":"37439510",
"creationTime":"2015-07-13T10:04:51.348Z",
"lastModifiedTime":"2017-03-14T05:39:08.247Z"}
--glboundary_ra08P31TSV3q70pPgdwc9UKlfihy9q
Content-type: application/json; charset=utf-8
Content-length: 448

{"id":"1561574010",
"firstName":"Jack",
"lastName":"White",
"gender":"male",
"email":"jack.white@example.com",
"location":"San Francisco",
"avatar":"https://glip-prod.s3.amazonaws.com/web/customer_files/25325084684/image.png",
"companyId":"37439510",
"creationTime":"2015-09-18T04:30:59.122Z",
"lastModifiedTime":"2017-03-14T16:53:58.412Z"}
--glboundary_ra08P31TSV3q70pPgdwc9UKlfihy9q
Content-type: application/json; charset=utf-8
Content-length: 442

{"id":"986580011",
"firstName":"John",
"lastName":"Smith",
"gender":"male",
"email":"john.smith@example.com",
"location":"St. Petersburg",
"avatar":"https://glip-prod.s3.amazonaws.com/web/customer_files/16055050252/ava.png",
"companyId":"37439510",
"creationTime":"2015-05-22T14:32:25.036Z",
"lastModifiedTime":"2017-03-15T06:56:30.116Z"}
--glboundary_ra08P31TSV3q70pPgdwc9UKlfihy9q--

Glip Posts

URI

/restapi/v1.0/glip/posts

Get Posts

Since 1.0.28 (Release 8.4)

Returns list of posts.

Method

GET

API Group

Light

Required Permissions

Permission Description
Glip Availability of Glip

Query Parameters

Parameter Type Description
groupId string Identifier of a group to filter posts
pageToken string Token of a page to be returned, see Glip Navigation Info
recordCount integer Max numbers of records to be returned. The default/maximum value is 250

Request Body

None

Response Body

Parameter Type Description
records Collection of Glip Post Info List of posts
navigation Glip Navigation Info Information on navigation

Example

Request example

GET /restapi/v1.0/glip/posts?groupId=456775

Response example

HTTP 200 OK
 
{
  "navigation" : {
    "prevPageToken" : "fgghjsdgfsjf",
    "nextPageToken" : "62hdfjhq87xjh"
  },
  "records" : [ {
    "lastModifiedTime" : "2016-12-15T12:00:00Z",
    "creationTime" : "2016-12-15T12:00:00Z",
    "groupId" : "456775",
    "creatorId" : "5574664564",
    "id" : "637468356",
    "text" : "Hi there!",
    "type": "TextMessage",
    "attachments": [ {
    "id": "12345678",
    "type": "File",
    "contentUri": "https://glip-vault-1.s3.amazonaws.com/web/customer_files/151037468684/Screenshot.jpg?Expires=2075494478&AWSAccessKeyId=AKIAJROPQDFTIHBTLJJQ&Signature=Gnh617oaoxVsj9jHRz%2BuIZO%2Fo%2FM%3D&response-content-disposition=attachment",
"name": "Screenshot.jpg"
  }
  }, {
    "lastModifiedTime" : "2017-02-09T12:00:00Z",
    "creationTime" : "2017-02-09T12:00:00Z",
    "groupId" : "456775",
    "id" : "583748574",
    "creatorId" : "5574664564",
    "type": "PersonsAdded",
    "addedPersonIds": [ "473856", "glip_293485" ]
  } ]
      

Create Post

Since 1.0.28 (Release 8.4)

Creates a post.

Method

POST

API Group

Light

Required Permissions

Permission Description
Glip Availability of Glip

Request Body

Parameter Type Description
groupId string Internal identifier of a group to send post to
text string Text of a post, the maximum is 10000 characters
attachments Collection of Attachment Info List of attachments to be posted

Attachment Info

Property Type Description
id string Internal identifier of an attachment
attachmentType string Type of an attachment

Response Body

Parameter Type Description
id string Internal identifier of a post
groupId string Internal identifier of a group a post belongs to
type 'TextMessage' | 'PersonJoined' | 'PersonsAdded' Type of a post
text string For 'TextMessage' post type only. Message text
attachments Collection of Attachment Info List of posted attachments
creatorId string Internal identifier of a user - author of a post
addedPersonIds Collection of string For PersonsAdded post type only. Identifiers of persons added to a group
creationTime datetime Post creation datetime in ISO 8601 format
lastModifiedTime datetime Post last modification datetime in ISO 8601 format

Attachment Info

Property Type Description
id string Internal identifier of an attachment
type string Type of an attachment
contentUri string Link to binary content
name string Name of a file

Example 1
Create simple post

Request example

POST /restapi/v1.0/glip/posts
 
{
  "groupId" : "456775",
  "text" : "Hi there!"
}

Response example

HTTP 200 OK
 
{
  "lastModifiedTime" : "2016-12-15T12:00:00Z",
  "creationTime" : "2016-12-15T12:00:00Z",
  "groupId" : "456775",
  "creatorId" : "5574664564",
  "id" : "637468356",
  "text" : "Hi there!",
  "type": "TextMessage"
}

Example 2
Create post with file(s) attached

Request example

POST /restapi/v1.0/glip/posts
 
{
  "groupId": "456775",
  "attachments": [ {
    "id": "12345678",
    "attachmentType": "File"
  } ]
}

Response example

HTTP 200 OK
 
{
  "lastModifiedTime" : "2017-03-20T12:00:00Z",
  "creationTime" : "2017-03-20T12:00:00Z",
  "groupId" : "456775",
  "creatorId" : "5574664564",
  "id" : "637468356",
  "type": "TextMessage",
  "attachments": [ {
    "id": "12345678",
    "attachmentType": "File",
    "contentUri": "https://glip-vault-1.s3.amazonaws.com/web/customer_files/151037468684/Screenshot.jpg?Expires=2075494478&AWSAccessKeyId=AKIAJROPQDFTIHBTLJJQ&Signature=Gnh617oaoxVsj9jHRz%2BuIZO%2Fo%2FM%3D&response-content-disposition=attachment",
"name": "Screenshot.jpg"
  } ]
}

Glip Files

URI

/restapi/v1.0/glip/files

Upload File

Since 1.0.31 (Release 9.2)

Posts a file.

Method

POST

API Group

Heavy

Request Header

The header Content-Disposition should contain the value attachment; filename="<filename.ext>".

Required Permissions

Permission Description
Glip Availability of Glip

Query Parameters

Parameter Type Description
groupId string Internal identifier of a group the post with file attached will be added to
name string Name of a file attached

Request Body

Glip file as binary data.

Response Body

Parameter Type Description
id string Internal identifier of a file
contentUri string Link to binary content
name string Name of a file

Example 1

Post a file with Content-Disposition header

Request example

POST /restapi/v1.0/glip/files
Content-Disposition: attachment; filename="Screenshot.jpg"

<binary data>

Response example

HTTP 200 OK

{
  "id": "12345678",
  "contentUri": "https://glip-vault-1.s3.amazonaws.com/web/customer_files/151037468684/Screenshot.jpg",
  "name": "Screenshot.jpg"
} 

Example 2

Post a file with query parameters

Request example

POST /restapi/v1.0/glip/files?groupId=456775&name=Screenshot.jpg

<binary data>

Response example

HTTP 200 OK

{
  "id": "12345678",
  "contentUri": "https://glip-vault-1.s3.amazonaws.com/web/customer_files/151037468684/Screenshot.jpg",
  "name": "Screenshot.jpg"
} 

Glip File

URI

/restapi/v1.0/glip/files/{fileId}

Get File Info

Since 1.0.31 (Release 9.2)

Returns a file.

Method

GET

API Group

Medium

Required Permissions

Permission Description
Glip Availability of Glip

Query Parameters

Parameter Type Description
fileId string Internal identifier of a file

Request Body

None

Response Body

File Info

Example

Request example

GET /restapi/v1.0/glip/files/12345678

Response example

HTTP 200 OK

{
  "id": "12345678",
  "contentUri": "https://glip-vault-1.s3.amazonaws.com/web/customer_files/151037468684/Screenshot.jpg?Expires=2075494478&AWSAccessKeyId=AKIAJROPQDFTIHBTLJJQ&Signature=Gnh617oaoxVsj9jHRz%2BuIZO%2Fo%2FM%3D&response-content-disposition=attachment",
  "name": "Screenshot.jpg"
} 

Meetings [Beta]

Meetings List

URI

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

Get Scheduled Meetings

Since 1.0.25 (Release 8.1)

Returns a list of meetings for a particular extension. The list of meetings does not include meetings of 'Instant' type.

Method

GET

API Group

Light

Required Permissions

Permission Description
Meetings Creating, viewing, editing and deleting meetings

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 meetings resource
records Collection of Meeting Info List of extension meetings
paging Paging Info Information on paging
navigation Navigation Info Information on navigation

Meeting Info

Parameter Type Description
uri string Canonical URI of a meeting resource
id string Internal identifier of a meeting
topic string Topic of a meeting
meetingType 'Scheduled' | 'Instant' | 'Recurring' Type of a meeting
password string Password required to join a meeting
status 'NotStarted' | 'Started' Current status of a meeting
links Links Info Links to start/join the meeting
schedule Meeting Schedule Info Schedule of a meeting
host Host Info Information on a host of a meeting
allowJoinBeforeHost boolean If 'True' then the meeting can be joined and started by any participant (not host only). Supported for the meetings of 'Scheduled' and 'Recurring' type
startHostVideo boolean Enables starting video when host joins the meeting
startParticipantsVideo boolean Enables starting video when participants join the meeting
audioOptions Collection of string Meeting audio options. Possible values are 'Phone', 'ComputerAudio'

Links Info

Parameter Type Description
startUri string Link to start a meeting
joinUri string Link to join a meeting

Meeting Schedule Info

Parameter Type Description
startTime datetime Start time of a meeting in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
durationInMinutes integer Duration of a meeting in minutes
timeZone Timezone Info Timezone of a meeting

Timezone Info

Parameter Type Description
id string Identifier of a timezone

Host Info

Parameter Type Description
id string Internal identifier of an extension which is assigned to be a meeting host
uri string Link to a host extension resource

Example

Request example

GET /restapi/v1.0/account/402946441008/extension/402946441008/meeting HTTP/1.1
Authorization: Bearer QU1TMDJQMDFQQVMwM3xBQURIZjAzWFFySGpMMHpFRXkyWTZCbweWJQT2N0NHc

Response example

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

{
  "uri" : "https.../restapi/v1.0/account/402946441008/extension/402946441008/meeting/?page=1&perPage=100",
  "records" : [ {
    "uri" : "https.../restapi/v1.0/account/402946441008/extension/402946441008/meeting/1497110573",
    "id" : "1497110573",
    "topic" : "My meeting #1",
    "meetingType" : "Scheduled",
    "password" : "123456",
    "status" : "NotStarted",
    "links" : {
      "startUri" : "https.../1497110573?zpk=l044IGCQxRe4hZMsobr02CzB15ZxZqhx7P4beQiruY8.BwYAAAFUXLh6BgAAHCAkOWJkNAMNDAyOTQ2NDQxMDA4AAIB",
      "joinUri" : "https.../1497110573?pwd=tWzAHHXJzXQ%3D"
    },
    "schedule" : {
      "startTime" : "2015-11-03T12:00:00Z",
      "durationInMinutes" : 30,
      "timeZone" : {
        "id" : "57" }
      },
    "host" : {
    "id" : "12739583004",
    "uri" : "https.../restapi/v1.0/account/12739583004/extension/12739583004"
    },
    "allowJoinBeforeHost" : true,
    "startHostVideo" : true,
    "startParticipantsVideo" : true,
    "audioOptions" : [ "Phone", "ComputerAudio" ]
  }, {
    "uri" : "https.../restapi/v1.0/account/402946441008/extension/402946441008/meeting/1482027796",
    "id" : "1482027796",
    "topic" : "My meeting #2",
    "meetingType" : "Scheduled",
    "password" : "123456",
    "status" : "NotStarted",
    "links" : {
      "startUri" : "https.../1482027796?zpk=l044IGCQxRe4hZMsobr02CzB15ZxZqhx7P4beQiruY8.BwYAAAFUXLh6BgAAHAdGQUtFX1RLAAAMNDAyOTQ2NDQxMDA4AAIB",
      "joinUri" : "https.../j/1482027796?pwd=tWzAHHXJzXQ%3D"
    },
    "schedule" : {
      "startTime" : "2015-11-03T12:00:00Z",
      "durationInMinutes" : 30,
      "timeZone" : {
        "id" : "57"
      },
    
  "host" : {
    "id" : "12539583004",
    "uri" : "https.../restapi/v1.0/account/12539583004/extension/12539583004"
    },
    "allowJoinBeforeHost" : true,
    "startHostVideo" : true,
    "startParticipantsVideo" : true,
    "audioOptions" : [ "Phone", "ComputerAudio" ]
  }, {
    "uri" : "https.../restapi/v1.0/account/402946441008/extension/402946441008/meeting/1488807342",
    "id" : "1488807342",
    "topic" : "My meeting",
    "meetingType" : "Scheduled",
    "password" : "123456",
    "status" : "NotStarted",
    "links" : {
      "startUri" : "https.../1488807342?zpk=l044IGCQxRe4hZMsobr02CzB15ZxZqhx7P4beQiruY8.BwYAAAFww0MDI5NDY0NDEwMDhiAAdGQUtFX1RLAAAMNDAyOTQ2NDQxMDA4AAIB",
      "joinUri" : "https.../1488807342?pwd=tWzAHHXJzXQ%3D"
    },
    "schedule" : {
      "startTime" : "2015-11-03T12:00:00Z",
      "durationInMinutes" : 30,
      "timeZone" : {
        "id" : "57"
      },
   "host" : {
    "id" : "12739586004",
    "uri" : "https.../restapi/v1.0/account/12739583804/extension/12739586004"
  },
    
    "allowJoinBeforeHost" : true,
    "startHostVideo" : true,
    "startParticipantsVideo" : true,
    "audioOptions" : [ "Phone", "ComputerAudio" ]
  } ],
  "paging" : {
    "page" : 1,
    "totalPages" : 1,
    "perPage" : 100,
    "totalElements" : 3,
    "pageStart" : 0,
    "pageEnd" : 2
  },
  "navigation" : {
    "firstPage" : {
      "uri" : "https.../restapi/v1.0/account/402946441008/extension/402946441008/meeting/?page=1&perPage=100"
    },
    "lastPage" : {
      "uri" : "https.../restapi/v1.0/account/402946441008/extension/402946441008/meeting/?page=1&perPage=100"
    }
  }
}          

Create Meeting

Since 1.0.25 (Release 8.1)

Creates a new meeting.

Method

POST

API Group

Medium

Required Permissions

Permission Description
Meetings Creating, viewing, editing and deleting meetings

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
topic string Topic of a meeting
meetingType 'Scheduled' | 'Instant' | 'Recurring' Type of a meeting. 'Instant' - meeting that is instantly started as soon as the host creates it; 'Scheduled' - common scheduled meeting; 'Recurring' - a recurring meeting. If the specified meeting type is 'Scheduled' then schedule property is mandatory for request
password string Password required to join a meeting. Max number of characters is 10
schedule Meeting Schedule Info Schedule of a meeting
host Host Info Host data. By default the currently logged-in extension is set a host of a meeting. However you can assign another extension to be a host (if the assigned extension allows it)
allowJoinBeforeHost boolean If 'True' then the meeting can be joined and started by any participant (not host only). Supported for the meetings of 'Scheduled' and 'Recurring' type
startHostVideo boolean Enables starting video when host joins the meeting
startParticipantsVideo boolean Enables starting video when participants join the meeting
audioOptions Collection of string Meeting audio options. Possible values are 'Phone', 'ComputerAudio'

Meeting Schedule Info

Parameter Type Description
startTime datetime Start time of a meeting in ISO 8601 format including timezone, for example 2016-03-10T18:07:52.534Z
durationInMinutes integer Duration of a meeting in minutes. For 'Scheduled' meetings only. Max duration is 1440 minutes
timeZone Timezone Info Timezone of a meeting. For 'Scheduled' meetings only

Host Info

Parameter Type Description
id string Internal identifier of an extension which is assigned to be a meeting host. The default value is currently logged-in extension identifier

Response Body

Meeting Info

Example 1
Scheduled Meeting

Request example

POST /restapi/v1.0/account/402946441008/extension/402946441008/meeting HTTP/1.1


{
  "topic": "My meeting",
  "meetingType": "Scheduled",
  "schedule": {
    "startTime": "2015-11-03T12:00:00Z",
    "durationInMinutes": 30,
    "timeZone": {"id" : "57"}
  },
  "host" : {
    "id" : "12842669005"},
  "password": "123456",
  "allowJoinBeforeHost": true,
  "startHostVideo": true,
  "startParticipantsVideo": true,
  "audioOptions": [
    "Phone",
    "ComputerAudio"
   ]
}    

Response example

HTTP/1.1 201 Created

{
  "uri" : "https.../restapi/v1.0/account/12842669004/extension/12842669004/meeting/1488594899",
  "id" : "1488594899",
  "topic" : "My meeting",
  "meetingType" : "Scheduled",
  "password" : "123456",
  "status" : "NotStarted",
  "links" : {
    "startUri" : "https://ringcentral.zoom.us/s/1488594899?zpk=pxIaDEjL7CAUYEoc0GM9_2s_Vu1dKo0Alhg96sy4AYM.BwYAAAFYi29uewAAHCAkNWIwNAACAQ",
    "joinUri" : "https://ringcentral.zoom.us/j/1488594899?pwd=tWzAHHXJzXQ%3D"
  },
  "schedule" : {
    "startTime" : "2015-11-03T12:00:00Z",
    "durationInMinutes" : 30,
    "timeZone" : {
      "id" : "57" }
  },
  "host" : {
    "id" : "12842669005",
    "uri" : "https.../restapi/v1.0/account/12842669004/extension/12842669005"
  },
  "allowJoinBeforeHost" : true,
  "startHostVideo" : true,
  "startParticipantsVideo" : true,
  "audioOptions" : [ "Phone", "ComputerAudio" ]
}           

Example 2
Instant Meeting

Request example

POST /restapi/v1.0/account/12842669004/extension/12842669004/meeting HTTP/1.1


{
  "topic": "My meeting",
  "meetingType": "Instant"
}

Response example

HTTP/1.1 201 Created

{
  "uri" : "https.../restapi/v1.0/account/12842669004/extension/12842669004/meeting/1485075831",
  "id" : "1485075831",
  "topic" : "My meeting",
  "meetingType" : "Instant",
  "password" : "123456",
  "status" : "NotStarted",
  "links" : {
    "startUri" : "https://ringcentral.zoom.us/s/1485075831?zpk=oxEuhLmu1ZURtpukJdByLTLPKVt6w1-GFRImFPjhNG4.BwYAAAFYi1FPWgAAHCAkODIxODg3YmYtZWQ3NS00YWI5LWJjZDYtMjk2ZmJkMjcwNmQyFmRwWndLb29YU3ZLRWZEaXg1Zm1Ma3cWZHBad0tvb1hTdktFZkRpeDVmbUxrdwsxMjg0MjY2OTAwNGIAB0ZBS0VfVEsAAAsxMjg0MjY2OTAwNAACAQ",
    "joinUri" : "https://rcdev.zoom.us/j/1485075831"
  },
  "host" : {
    "id" : "12842669004",
    "uri" : "https.../restapi/v1.0/account/12842669004/extension/12842669004"
  },
  "allowJoinBeforeHost" : false,
  "startHostVideo" : true,
  "startParticipantsVideo" : true,
  "audioOptions" : [ "Phone", "ComputerAudio" ]
}            

Meeting

URI

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

Get Meeting Info

Since 1.0.25 (Release 8.1)

Returns a particular meetings details by ID.

Method

GET

API Group

Medium

Required Permissions

Permission Description
Meetings Creating, viewing, editing and deleting meetings

Path Parameters

Parameter Type Description
accountId string Internal identifier of a RingCentral