1. business and industrial

RingCentral Connect Platform
Developer's Guide
RingCentral Connect Platform: Developer's Guide
Rev.1.0.16.a.[79434afda268+]
Publication date Apr 14, 2015 (API version 1.0.16, Service version 7.1)
Copyright © 2012-2015 RingCentral, Inc.
All rights reserved.
RingCentral is a registered trademark of RingCentral, Inc.
CONFIDENTIAL
ii
Rev.1.0.16.a.[79434afda268+]
Preface ............................................................................................................................. v
I. Developing with RingCentral Connect Platform .................................................................... 1
1. REST Overview ..................................................................................................... 2
Resources and Parameters .................................................................................... 2
HTTP Methods .................................................................................................. 4
Object Representation ......................................................................................... 5
User Agent Identification ..................................................................................... 6
Languages Support ............................................................................................. 7
HTTP Status Codes ............................................................................................ 7
Logical Error Codes ............................................................................................ 9
Batch Requests ................................................................................................. 11
2. API Usage Plans ................................................................................................... 14
What is Usage Plan .......................................................................................... 14
Default Usage Plan & Organization .................................................................... 14
Usage Plan Details ........................................................................................... 14
3. Authentication ...................................................................................................... 15
OAuth 2.0 Authorization .................................................................................... 15
Tokens ............................................................................................................ 15
Two-legged Authorization Flow .......................................................................... 16
Token Revocation ............................................................................................. 19
Application Permissions ..................................................................................... 20
4. Exploring Account and Extension Settings ................................................................. 21
Account and Extension Information ..................................................................... 21
5. Accessing Call Log ............................................................................................... 25
Call Log Access Rules ...................................................................................... 25
Commonly Used Call Actions and Results ............................................................ 25
6. Working with Messages ......................................................................................... 28
Message Attributes ........................................................................................... 28
Message Availability and Life Cycle .................................................................... 29
SMS and Pager Messages .................................................................................. 30
Fax Messages ................................................................................................... 32
7. RingOut ............................................................................................................... 38
Two-Legged RingOut Call ................................................................................. 38
8. Notifications and Subscriptions ................................................................................ 41
Subscription Flow ............................................................................................. 41
Notifications Transport ...................................................................................... 44
PubNub ................................................................................................... 44
9. Dictionary: Getting Static Data ................................................................................ 46
II. API Reference .............................................................................................................. 50
10. Common Data Types and Structures ....................................................................... 51
Data Types ...................................................................................................... 51
Resource Identification Properties ........................................................................ 52
Common Collection Properties ............................................................................ 52
Generic Path Parameters .................................................................................... 53
Common Query Parameters in Collection Resources ............................................... 53
Caller Info ....................................................................................................... 54
Standard Error Response .................................................................................... 55
11. Authentication ..................................................................................................... 56
Get Token ....................................................................................................... 56
Resource Owner Password Credentials Flow .................................................. 56
Refresh Token Flow .................................................................................. 58
Revoke Token .................................................................................................. 59
12. API Versioning ................................................................................................... 60
Get API Versions ............................................................................................. 60
CONFIDENTIAL
iii
Rev.1.0.16.a.[79434afda268+]
RingCentral Connect Platform
Get Version Info ............................................................................................... 61
13. Account and Extension Information ........................................................................ 63
Get Account Info .............................................................................................. 63
Get Extension Info ............................................................................................ 65
Get Extension List ............................................................................................ 74
14. Call Log ............................................................................................................ 76
Get Call Log Record ......................................................................................... 76
Get Call Log Records by Filter ........................................................................... 79
Get Active Calls ............................................................................................... 83
15. Messaging .......................................................................................................... 86
Get Message .................................................................................................... 86
Get Message List .............................................................................................. 91
Update Message ............................................................................................... 93
Delete Message ................................................................................................ 95
Delete Messages in a Thread .............................................................................. 96
Get Message Attachment Data ............................................................................ 97
Create SMS Message ......................................................................................... 98
Create Fax Message .......................................................................................... 99
Create Pager Message ...................................................................................... 102
16. RingOut ........................................................................................................... 105
Make RingOut Call ......................................................................................... 105
Get Status of RingOut Call ............................................................................... 107
Cancel RingOut Call ........................................................................................ 108
17. Presence ........................................................................................................... 109
Get Extension Presence Status ........................................................................... 109
18. Notifications: Subscription API ............................................................................ 112
Create Subscription ......................................................................................... 112
Get Subscription ............................................................................................. 116
Renew Subscription ......................................................................................... 117
Modify Event Filters ........................................................................................ 118
Cancel Subscription ......................................................................................... 119
Notifications Event Types ................................................................................. 120
Messages Event ...................................................................................... 120
Presence Event ....................................................................................... 121
Detailed Presence Event ........................................................................... 122
Presence Line Event ............................................................................... 124
19. Dictionary ......................................................................................................... 126
Get Single Country .......................................................................................... 126
Get Countries ................................................................................................. 127
Get Single State .............................................................................................. 128
Get States of a Country .................................................................................... 129
Get All Locations ............................................................................................ 131
Get Single Timezone ....................................................................................... 133
Get All Timezones .......................................................................................... 134
Get Language List ........................................................................................... 136
Get Single Language ....................................................................................... 137
CONFIDENTIAL
iv
Rev.1.0.16.a.[79434afda268+]
Preface
This guide is intended to help developers build applications using the RingCentral API. The API allows
development of customized software solutions based on the RingCentral business phone service.
What is RingCentral?
RingCentral provides a cloud-based virtual business phone system that is connected to the Public Switched
Telephone Network (PSTN), the traditional global telephone network. RingCentral clients can access and
configure their phone system on a Service Web, and also via free mobile apps running on tablets and
smartphones. No additional phone hardware is required as the clients can use RingCentral softphones or
redirect calls to their existing phones. All phones are connected through a single corporate phone number
provided by RingCentral, or through an existing phone, thus unifying all phone communication services.
This enables companies to be more responsive to their customers and facilitate internal communication.
A call to a client is usually processed as follows:
1. The caller is greeted by an auto-attendant reporting company name and available extensions.
2. The call may be forwarded to an extension the caller has selected from a directory.
3. If the extension user does not pick up the phone, the call may be forwarded to the user's home or mobile
phone (if the time is appropriate, as defined by the user).
4. If the call is not picked up, the caller will be asked to record a voicemail message.
5. The caller's number will be logged in the system even if the caller hangs up the phone without leaving
a message.
Thus the companies are able to stay in touch with their customers, even if the employees are out of
office. The service is flexible and provides nearly limitless possible configurations. RingCentral clients
are typically small and medium size companies, or individuals who require a professional but low-cost
business communications solution. These businesses have highly diverse requirements and not all of them
can be met by RingCentral standard web and mobile services.
The Purpose of the RingCentral API.
RingCentral API was created to cover additional business requirements and improve customer experience.
The API is a powerful yet simple interface allowing development of customized and integrated solutions
including web, mobile, and desktop applications with full access to the RingCentral phone service.
Organization.
This Developer's Guide is organized into two major parts: Developing with RingCentral Connect Platform
and API Reference.
• Part 1: Developing with RingCentral Connect Platform
This part will introduce you to the RingCentral REST API. It starts with the REST architecture basics
and its usage in terms of RingCentral API. The next chapter provides information on API Authorization
using OAuth. The other chapters describe basic principles of the RingCentral API; its functionality is
demonstrated by a few examples.
• Part 2: API Reference
The sections in this part describe in detail every API endpoint with path and query parameters, their
possible values, and examples of requests and responses.
CONFIDENTIAL
v
Rev.1.0.16.a.[79434afda268+]
Part I. Developing with
RingCentral Connect Platform
CONFIDENTIAL
1
Rev.1.0.16.a.[79434afda268+]
Chapter 1. REST Overview
The RingCentral API is based on the Representational State Transfer (REST) architecture. REST is not a
standard but an architectural style, and it uses the following standards:
• HTTP
• URL
• XML/HTML/GIF/JPEG/etc. (resource representations)
• text/xml, text/html, application/json, image/jpeg, etc. (MIME types)
REST allows you to access the API in the same way you would access a web server. Whenever you want
to access any API service, send a standard HTTP command to a particular resource that represents the
required functionality. Every API service is represented by a specific endpoint that is accessed by its own
URI via sending standard requests using HTTP methods (GET, POST, PUT, DELETE).
One of the key advantages of REST architecture is simplicity. You can build your application on the fly
without any additional tools, development kits or specifications. If you know how to interact with a simple
web server, then you are ready to use the RingCentral API.
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.
CONFIDENTIAL
2
Rev.1.0.16.a.[79434afda268+]
REST Overview
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
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 [https://tools.ietf.org/html/rfc1738]. 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):
CONFIDENTIAL
3
Rev.1.0.16.a.[79434afda268+]
REST Overview
/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
HTTP 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.
Note
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 API Reference.
Let's consider a simple example of a GET method — retrieving the version of the RingCentral REST API.
GET /restapi/v1.0 HTTP/1.1
Accept: application/json
Authorization: Bearer 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"
}
CONFIDENTIAL
4
Rev.1.0.16.a.[79434afda268+]
REST Overview
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.
Important
Tunneling HTTP methods is a last resort that 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.
CONFIDENTIAL
5
Rev.1.0.16.a.[79434afda268+]
REST Overview
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 ContentType 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
JSON
application/
json
HTML Form Data application/
(only for token
request body
as governed
by OAuth 2.0
specification)
HTTP request/response body example
{
"uri": "https://platform.ringcentral.com/restapi/
v1.0",
"versionString": "1.0.0",
"releaseDate": "2012-06-14T00:00:00.000Z",
"uriString": "v1.0"
}
grant_type=password&username=18887776655&password=987654
x-www-formurlencoded
Note
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.
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.).
CONFIDENTIAL
6
Rev.1.0.16.a.[79434afda268+]
REST Overview
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 [https://tools.ietf.org/html/rfc1945] and
RFC-2068 [https://tools.ietf.org/html/rfc2068].
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
{...}
HTTP Status Codes
The RingCentral API uses standard HTTP response status codes. Following the standard REST principles,
the API preserves the general meaning of the HTTP codes as described in RFC-2616 [https://tools.ietf.org/
html/rfc2616]. The most frequently used codes are given in the table below.
Response Status Codes
HTTP
Status
Code
Description
Meaning in terms of RingCentral API
2xx
Success
Any successfully completed operation
200
OK
Response to most of operations that return data
201
Created
New resource has been created, specified by the server in the
Location header field.
204
No Content
Response to operations that do not return data (for example,
DELETE)
207
Multi-status
Response to successful batch operations (see the section
called Batch Requests)
CONFIDENTIAL
7
Rev.1.0.16.a.[79434afda268+]
REST Overview
HTTP
Status
Code
Description
Meaning in terms of RingCentral API
4xx
Client Error
Improper use of API
400
Bad Request
The request could not be understood by the server due to
malformed syntax
401
Unauthorized
Request credentials are invalid, expired, or compromised/
revoked earlier
403
Forbidden
Access to given resource requires additional rights and
cannot be granted
404
Not Found
The requested resource cannot be found
405
Method Not Allowed
Endpoint does not support the requested HTTP method
406
Not Acceptable
Request came with the unsupported Accept header
408
Request Timeout
The server timed out waiting for the request. The client did
not produce a request within the time that the server was
prepared to wait. The client may repeat the request without
modifications at any time later
409
Conflict
Request cannot be implemented due to resource conflict. For
example, it may appear when the client attempts to add a
new record violating the unique constraint
413
Request Entity Too
Large
The request is larger than the server is willing or able to
process
415
Unsupported Media Type Entity of the request is of unsupported content type
429
Too Many Requests
The number of requests is exceeded. It typically means that
the client is throttled by the server due to too high request
rate. Specific retry period in seconds may be specified in
Retry-After response header
5xx
Server Error
Various server errors
500
Internal Server Error
Server is unable to process the request due to internal error
502
Bad Gateway
Server is unable to process the request due to overload or
maintenance
503
Service Unavailable
Server is unable to process the request due to overload
or maintenance. Specific retry period in seconds may be
specified in Retry-After response header
504
Gateway Timeout
Server is unable to process the request due to overload or
maintenance
For example:
HTTP/1.1 200 OK
Content-Type: application/json
In the case of an error response the server can also return a text description of an error in response body,
in the message field. Let's consider the example:
HTTP/1.1 403 Forbidden
Content-Type: application/json
CONFIDENTIAL
8
Rev.1.0.16.a.[79434afda268+]
REST Overview
{
"message" : "Attempt to access another extension."
}
It may also contain logical error code (see Logical Error Codes) and other attributes which simplify the
understanding of the error reason.
Logical Error Codes
The API uses specific logical error codes to make error processing for client applications more simple and
effective. The client application should use startsWith comparison mode when comparing documented
error codes with actual value. In the future error code names may contain suffixes for more granularity
of error codes.
Authorization Errors Codes.
The following logical error codes can be returned in error responses for authorization requests.
Authorization logical error codes appear only along with the error 401 Unauthorized.
Logical Error Code
Description
TokenExpired
Access/refresh token passed in the request has already expired.
Access token expiration can also be caused by the user's password
change on the service site.
TokenInvalid
Session associated with access/refresh token has been invalidated
either because of being compromised by inappropriate access
by another application, or because of user deletion/migration/
deactivation
InsufficientPermissions
Application tries to access a feature which requires special
API permission that it does not have. Key reasons may be the
following: application does not have the permission for registration,
application explicitly requested access token without such
permission, or the user explicitly denied such permission at
application authorization step. The additional field 'Permission'
containing the missing permission may be introduced into the
response
AuthorizationRevoked
User explicitly revoked authorization for the application
Let's see the example below:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{ ...
"errorCode": "InsufficientPermissions",
... }
Error Codes in Regular API Calls.
The following logical codes can be returned as a part of error responses in different API calls.
Logical Error Code
RejectedByRecipient
CONFIDENTIAL
Description
The recipient cannot accept text/pager
message and explicitly rejects it
9
HTTP Code
400 Bad Request
Rev.1.0.16.a.[79434afda268+]
REST Overview
Logical Error Code
Description
HTTP Code
InternationalProhibited Sending messages or calling to international
403 Forbidden
numbers is not allowed for this extension/
account
InsufficientFunds
The account balance is insufficient for
performing the action
403 Forbidden
FeatureNotAvailable
The account does not support the feature.
Extension is forbidden to send/receive
messages
403 Forbidden
InvalidParameter
One or more request parameters are invalid.
400 Bad Request
Additional attributes parameterName and
parameterValue can be provided in response
InvalidContent
The request body content is invalid (empty,
too long, syntactically malformed, etc.)
MaintenanceMode
The system is under maintenance. Request
503 Service
may be retried. Specific retry period in
Unavailable
seconds is specified in Retry-After response
header
OldThreadReply
Text message reply is forbidden for old
message threads
403 Forbidden
OutOfThreadReply
Text message reply is denied for this user,
who is no longer a conversation thread
participant
403 Forbidden
400 Bad Request, 415
Unsupported Media
Type
Let's see the example below:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message": "Parameter [to] is invalid [no phone number]",
"errorCode": "InvalidParameter",
"parameterName": "to",
"description": "no phone number"
}
Batch Request Error Codes.
The following logical error codes can be returned in error responses for batch (multipart, bulk) requests.
Logical Error Code
InvalidMultipartRequest
Description
Batch request is incorrect, refer
to error message
HTTP Code
400 Bad Request
Let's see the example below:
GET /restapi/v1.0/account/~/
extension/400426991001,400426927002,400426975003,400426927004,400426927005,
400426927006,400426927007,400426927008,400426927009,400426927010,400426927011,
400426927012,400426927013,400426927014,400426927015,400426927016,400426927017,
400426927018,400426927019,400426927020,400426927021,400426927022,400426927023,
400426927024,400426927025,400426927026,400426927027,400426927028,400426927029,
400426927030,400426927031/presence HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFKV1MwMXzoIqjx7VtLOXOxQt1j8rswGMt-LA
CONFIDENTIAL
10
Rev.1.0.16.a.[79434afda268+]
REST Overview
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"message" : "Extension Presence Info multipart request is limited to 30 extensions",
"errorCode" : "InvalidMultipartRequest"
}
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 [http://
restpatterns.org/HTTP_Status_Codes/207_-_Multi-Status]) is returned in every multipart response object
and indicates a batch request.
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
CONFIDENTIAL
11
Rev.1.0.16.a.[79434afda268+]
REST Overview
{
"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"}
CONFIDENTIAL
12
Rev.1.0.16.a.[79434afda268+]
REST Overview
--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--
CONFIDENTIAL
13
Rev.1.0.16.a.[79434afda268+]
Chapter 2. API Usage Plans
What is Usage Plan
The Usage Plan is a scheme specifying limits of using the API resources.
Applying usage plans enables consistent load allocation through correct interaction with RingCentral
Connect Platform.
Default Usage Plan & Organization
The Organization is a company enabled to create several API based client applications. The usage plan
for each Organization is specified by RingCentral Connect Platform administrator. The API usage plan
for each next client application developed by the Organization is the same by default.
If you need to change the usage plan you should apply to administartors and request it.
Usage Plan Details
Each usage plan features rates specifying how many requests to each API group are allowed. Currently
four API groups are distiguished:
• 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 in API Reference is marked as
heavy, medium, light or auth under the header Usage Plan Group.
Your Usage Plan details are displayed as shown in the table below. It informs you how many requests of
each API group the usage plan supports and what is the time frame in seconds for every request.
Rate Limits (Example)
API group
Request limit
Heavy
10 requests/60 seconds
Medium
40 requests/60 seconds
Light
50 requests/60 seconds
Auth
5 requests/60 seconds
Let's consider the given rate limits. Within the presented usage plan your client application is allowed
to send 10 heavy, 40 medium, 50 light and 5 authtorization requests 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. Specific retry period in seconds, after which the requests
can be sent, is specified in Retry-After response header.
CONFIDENTIAL
14
Rev.1.0.16.a.[79434afda268+]
Chapter 3. Authentication
Your application and its users must be authorized by RingCentral in order to eliminate any possibility of
abuse. The RingCentral API uses OAuth 2.0 protocol for authentication and authorization, which is widely
supported by the majority of cloud API providers. For more details see OAuth 2.0 protocol specification
[http://oauth.net/2/].
According to OAuth 2.0 the following is to be ensured:
• The API client must be authenticated as a legitimate application registered at RingCentral.
• If the application accesses some data on behalf of the RingCentral customer, the user of your application
must be authenticated at RingCentral.
• The application must be authorized by the user to perform the required actions (to access the messages
of this user, to perform calls on his behalf, etc.)
OAuth 2.0 Authorization
OAuth 2.0 offers various ways (authorization flows) in which an application may be authorized to access
required resources. Once an authorization flow has been successfully passed, your application is provided
with the token which is required to access API resources.
Basically each authorization flow includes the following roles and steps:
• Application supplies its credentials and provides a way for the user (Resource Owner) to supply his/
her credentials to Authorization Server.
• Resource owner (the user of your application) is authenticated as a RingCentral user and authorizes
the application, provided with the access grant.
• Authorization Server authenticates the users and the applications and provides tokens which regulate
authorization flow and should be used further to access API resources.
• Resource Server provides the Application with access to API resources (including resources that serve
as entry points for authorization facilities).
Currently the RingCentral API supports the mobile application flow in which application itself will obtain
the user's credentials.
Note
In order to prevent eavesdropping and tampering, the RingCentral API requires Transport
Layer Security. This means that API resources are accessible only through HTTPS
connections.
Tokens
OAuth 2.0 protocol defines a number of tokens used to provide a context in each request for authorization
or authentication. It is important to understand distinctions between token types:
• Access token is a special token issued by authorization server and used by the application to make
requests to all endpoints which require authentication.
CONFIDENTIAL
15
Rev.1.0.16.a.[79434afda268+]
Authentication
• Refresh token can be provided along with access token once your application successfully passes the
authorization. It can be used only once to refresh short-lived access token. The refresh token itself cannot
be used to access protected resources.
To prevent possible abuse by means of intercepting tokens and using them illegally, access and refresh
token lifetimes are limited. For instance, by default access token is expired in one hour. Refresh token
lifetime is typically limited to one week. Actual lifetimes of access and refresh tokens are returned in
expires_in and refresh_token_expires_in attributes of a token endpoint response.
The API requests which include expired access tokens are rejected with HTTP 401 Unauthorized
response. So an application is forced to obtain a new access token using a refresh token or by passing the
authorization flow once again.
Both access and refresh tokens may also be revoked by the user at any time. In this case the application
is required to pass the authorization flow again.
If the user who authorized the OAuth session changes his/her credentials (using RingCentral Service Web,
Mobile Web or Admin Interface sites), all issued tokens are invalidated immediately, and all established
sessions are terminated.
Two-legged Authorization Flow
This is the simplest OAuth 2.0 authorization flow. It is mostly applicable for native mobile and desktop
applications. Typically the user enters credentials in the form which is provided by the application itself
(instead of being redirected to the RingCentral website to enter credentials through Web Browser). Such
native applications are considered to be more trustworthy because users themselves install them on their
devices and provide the required permissions. Furthermore, user credentials will not be stored on a thirdparty website, but on the device owned by the user. Please note that this flow is considered to be less secure
and requires an additional level of trust between you and the application.
Two-legged authorization flow uses Resource Owner Password Credentials OAuth grant type. Refresh
Token grant type can be used to refresh a previously issued pair of tokens.
Two steps are required for this flow:
1. The application by itself obtains user credentials from the user.
2. The application supplies user credentials and application credentials in a request to a token endpoint.
Once the credentials are successfully verified, the application receives the access token and the refresh
token in HTTP response.
Once the access token has expired, your application will not be able to use it to access the RingCentral
API resources. Even though token lifetime is enough to perform tasks, your application may still require
additional time. In order to extend time for accessing RingCentral API resources without going through
authorization flow once again, you may use the refresh token to obtain a new access token.
Here is an example and complete step-by-step instructions on how to perform two-legged authorization
using the RingCentral API.
1.
You have to implement a way of obtaining user credentials from the users of your application. Note
that you must provide adequate security measures since your application will be dealing with user
credentials directly.
2.
Once your application has obtained credentials from the user, it can send a specific request to token
endpoint in order to receive the access token. This request must be in the application/x-wwwform-urlencoded format by passing the following parameters in the HTTP request body:
CONFIDENTIAL
16
Rev.1.0.16.a.[79434afda268+]
Authentication
• grant_type
Required. Must be set to password.
• username
Required. Login of RingCentral user (phone number in E.164 format with or without leading "+"
sign).
• extension
Optional. Extension number to log in. This parameter can be omitted when logging in as system
extension providing company phone number as the login name, or when providing an extension
direct number as the login name.
• password
Required. Password of the RingCentral user.
Each application that tries to perform requests to token endpoint must be authenticated. To
authenticate the application we use an application key and an application secret issued during
application registration. They are passed to the token endpoint as username and password using the
HTTP Basic authentication scheme.
For example you have obtained application key YourAppKey and application secret YourAppSecret.
Combine them in a string with a colon YourAppKey:YourAppSecret and encode with Base64; thus
you will get the following authorization token WW91ckFwcEtleTpZb3VyQXBwU2VjcmV0.
POST /restapi/oauth/token HTTP/1.1
Host: platform.ringcentral.com
Authorization: Basic WW91ckFwcEtleTpZb3VyQXBwU2VjcmV0
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=password&username=18887776655&extension=102&password=987654321
Example values are:
• platform.ringcentral.com - name of the RingCentral API server
• WW91ckFwcEtleTpZb3VyQXBwU2VjcmV0 - Base64 encoded HTTP Basic string generated from
application credentials (application key and secret)
• 18887776655 - RingCentral customer login (phone number)
• 102 - particular extension number
• 987654321 - password to log in as the extension 102 of the account 18887776655
If authentication has been passed successfully, you will get a response similar to the following:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"expires_in": 3600,
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
"refresh_token_expires_in": 604800
CONFIDENTIAL
17
Rev.1.0.16.a.[79434afda268+]
Authentication
}
Token response contains the following information:
• 2YotnFZFEjr1zCsicMWpAA - access token to use for making API calls;
• 3600 - access token lifetime in seconds;
• tGzv3JOkF0XG5Qx2TlKWIA - refresh token which can be used to obtain a new access token.
3.
Now your application should use the issued access token to perform the required actions. Each request
must pass the access token using one of the following ways:
• access_token query parameter with the issued access token specified as a value:
GET /restapi/v1.0/account/1110475004/extension/1110475004/address-book/
contact/29874662828?access_token=2YotnFZFEjr1zCsicMWpAA
Host: platform.ringcentral.com
Accept: application/json
Connection: keep-alive
• Bearer authentication scheme followed by access token in the Authorization header.
For example, to get a specific address-book entry, you need to perform the following request:
GET /restapi/v1.0/account/1110475004/extension/1110475004/address-book/
contact/29874662828
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Host: platform.ringcentral.com
Accept: application/json
Connection: keep-alive
4.
Once the access token lifetime has expired, your application will no longer be able to use it to access
RingCentral API resources. To prevent eavesdropping, token lifetime is limited by default. If your
application is required to perform tasks longer than the token lifetime you may need to extend time for
accessing RingCentral API resources. This can be done easily via token refreshment without going
through the authorization flow once again.
This request must be done using the application/x-www-form-urlencoded format by passing the
following parameters in the HTTP request entity-body:
• grant_type
Required. Must be set to refresh_token.
• refresh_token
Required. Refresh token issued previously.
Here is the sample of refresh token request:
POST /restapi/oauth/token HTTP/1.1
Host: platform.ringcentral.com
Authorization: Basic WW91ckFwcEtleTpZb3VyQXBwU2VjcmV0
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
Where
CONFIDENTIAL
18
Rev.1.0.16.a.[79434afda268+]
Authentication
• WW91ckFwcEtleTpZb3VyQXBwU2VjcmV0 - HTTP Basic string, Base64 encoded and generated from
client credentials: the application key and secret ("userid" and "password" in terms of RFC-2617
[https://tools.ietf.org/html/rfc2617]) - AppKey:AppSecret.
• tGzv3JOkF0XG5Qx2TlKWIA - refresh token, issued previously, together with the now expired
access token.
On success, the server responds with the new access token and refresh token which you may use for
accessing resources and for refreshing the access token, respectively, for example:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "Ejr1zCsicM2YosdfFZFWpAA",
"expires_in": 3600,
"refresh_token": "ZJOkF0X2TlKWIAG5Gzv3Qx",
"refresh_token_expires_in": 604800
}
Where
• Ejr1zCsicM2YosdfFZFWpAA - new (refreshed) access token to be used for making RingCentral
API calls.
• 3600 - token lifetime.
• ZJOkF0X2TlKWIAG5Gzv3Qx - new refresh token to receive new access token after this one expires.
Token Revocation
There are some situations when the user may want to revoke the already granted access in order to stop
application activity. To revoke access/refresh token the following request is used:
POST/restapi/oauth/revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic WW91ckFwcEtleTpZb3VyQXBwU2VjcmV0
token=U0pDMDFQMDFKV1MwMXwJ_W7L1fG4eGXBW9Pp-otywzriCw
HTTP/1.1 200 OK
The request must contain HTTP Basic authorization string Base64 encoded and generated from client
credentials: the application key ("userid" in terms of RFC-2617 [https://tools.ietf.org/html/rfc2617]) and
application secret ("password" in terms of RFC-2617 [https://tools.ietf.org/html/rfc2617]). The request
should contain the token form (preferred) or query parameter, which holds the value of an access or refresh
token. The server returns HTTP 204 No Content when the request has been successfully processed.
Please note that due to security reasons (to prevent eavesdropping) successful response is returned even if
revocation was not successful (for instance if a token passed was issued to another application, expired, or
by other means malformed. For additional details see RFC-7009: OAuth 2.0 Token Revocation [https://
tools.ietf.org/html/rfc7009].
CONFIDENTIAL
19
Rev.1.0.16.a.[79434afda268+]
Authentication
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
Included
Permissions
EditMessages
Viewing and updating user messages
Read and
Update
ReadMessages
Faxes
Sending and receiving faxes
Special
operation
ReadMessages
InternalMessages
Sending and receiving intra-company text
messages
Special
operation
ReadMessages
ReadAccounts
Viewing user account info (including name, Read Only
business name, address and phone number/
account number)
ReadCallLog
Viewing user call logs
Read Only
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
CONFIDENTIAL
20
ReadMessages
Rev.1.0.16.a.[79434afda268+]
Chapter 4. Exploring Account and
Extension Settings
The RingCentral service allows its customers to create and register an account that is usually associated
with the customer's company. After registering the account with the company main number the user can
create extensions of different types and functionality. The extensions can further be assigned with the
phone numbers and phone devices.
The account and its extensions can be configured in accordance with the user demands.
Processing account and extensions requires certain permissions, different for each functionality. The
permissions are listed so that each next includes the previous:
1. Retrieving account and extension data requires the "ReadAccounts" permission.
2. Modifying extension settings requires the "EditExtensions" permission.
3. Modifying account (including creating, modifying and deletion of extensions) requires the
"EditAccounts" permission.
4. Creating new accounts requires the "Accounts" permission.
This chapter provides general information on account/extension and describes the way to retrieve it. The
description of other functionality is given in detail in further chapters (corresponding to the permissions
list).
A typical consumer application authenticates using credentials supplied by the RingCentral user to get
access to the user's data. The application needs to know various details about the user account to function
properly.
Through the API the following account settings can be read:
• Basic customer account information (main phone number, service plan, available features, etc.)
• The list of extensions and each extension details
• The list of assigned phone numbers (per extension or globally per account)
Common access control rules are based on user credentials and are enforced in API as follows:
• access is allowed only to the information related to the authenticated account;
• any user may access public information about the account and all information about their own extension;
• users with administrator rights may access all information about account and all of its extensions.
Account and Extension Information
Retrieving Account Data
RingCentral API allows to retrieve information about a particular account.
To retrieve the information about a particular account use the following request:
CONFIDENTIAL
21
Rev.1.0.16.a.[79434afda268+]
Exploring Account and Extension Settings
GET /restapi/v1.0/account/{accountId}
You may provide either explicit accountId or use simplified syntax with tilde (~). The examples of request
and response are provided below.
GET /restapi/v1.0/account/~ HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/account/401145624008",
"id" : 401145624008,
"serviceInfo" : {
"uri" : "https.../restapi/v1.0/account/401145624008/service-info",
"brand" : {
"id" : "1210",
"name" : "MyCompany Inc.",
"homeCountry" : {
"id" : "1",
"uri" : "https.../restapi/v1.0/dictionary/country/1"
}
},
"servicePlan" : {
"id" : "1216",
"name" : "Professional"
},
"billingPlan" : {
"id" : "159",
"name" : "Monthly - 14.99 - Pro 101503",
"durationUnit" : "Month",
"duration" : 1,
"type" : "Regular"
}
},
"operator" : {
"uri" : "https.../restapi/v1.0/account/401145624008/extension/401145624008",
"id" : 401145624008,
"extensionNumber" : "101"
},
"mainNumber" : "18555440014",
"status" : "Confirmed"
}
Retrieving Extension Data
The RingCentral API allows retrieval of information on extensions that belong to a particular account. All
types of extensions are supported, namely:
• User ('User', 'Fax User','VirtualUser', 'DigitalUser') extension
• Department extension
• TakeMessageOnly (or Voicemail) extension
• AnnouncementOnly extension
• SharedLinesGroup extension
• PagingOnlyGroup extension
• IvrMenu extension
• ApplicationExtension extension
CONFIDENTIAL
22
Rev.1.0.16.a.[79434afda268+]
Exploring Account and Extension Settings
Extension types supported for a particular account depend on the service plan the account is subscribed
to. RingCentral accounts differ depending on a service plan (tier) that they are subscribed to. Currently
all the service plans are divided into UBP (User Based Pricing) and non-UBP. Major RingCentral nonUBP service plans are: Fax, Professional and Office. The following extension types are supported for
the accounts subscribed to these service plans: User, Department, Take Messages Only (Voicemail)
and Announcement Only. Unlike non-UBP service plans, UBP assumes support for distinctive and
chargeable user extension types: FaxUser (Fax Only), VirtualUser (Fax/Calling) and DigitalUser (Fax/
Calling/Deskphones). The regular ‘User’ extension type is no longer supported for UBP service plans. In
UBP service plans, non-chargeable Department, Take Message and Announcement Only extensions are
still supported.
As in the case of account ID, it is possible to use tilde (~) to refer to the currently logged-in extension
instead of specifying its numeric ID. Here is an example of the API call. Please note that the response
contains navigation links and standard collection metadata on paging.
GET /restapi/v1.0/account/159048008/extension HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri": ".../account/159048008/extension?page=1&perPage=100"
"records": [
{
"uri": ".../account/159048008/extension/159048008",
"id": 159048008,
"extensionNumber": "101",
"name": "John Smith",
"type": "User"
"contact" :
{ "firstName" : "John"
"lastName" : "Smith"
"company" : "MyCompany Inc."
"email" : "[email protected]" }
"status": "Enabled"
},
{
"uri": ".../account/159048008/extension/1201056008",
"id": 1201056008,
"extensionNumber": "110",
"name": "AO Ext",
"type": "Announcement"
"contact" :
{ "company" : "MyCompany"
"email" : "[email protected]"
"businessAddress" : {
"country" : "USA"
"city" : "Washington" }
} ],
"paging":
{
"page": 1,
"totalPages": 1,
"perPage": 100,
"totalElements": 2,
"pageStart": 0,
"pageEnd": 1
},
"navigation":
{
"firstPage": {"uri": ".../account/159048008/extension?page=1},
"lastPage": {"uri": ".../account/159048008/extension?page=1}
}
}
It is also possible to get the data about a particular extension. As well as in case of an account ID, you can
use tilde (~) to refer to a currently logged-in extension instead of specifying its numeric ID, as follows:
CONFIDENTIAL
23
Rev.1.0.16.a.[79434afda268+]
Exploring Account and Extension Settings
GET /restapi/v1.0/account/~/extension/~
Please refer to Extension Service Feature Info [68] for more details.
Note
Every RingCentral account has a special system extension. The user of this extension has
full administrative rights for the given account. Due to internal reasons, the ID of a system
extension is always the same as the ID of account itself.
Please refer to Account and Extension Information in the API Reference section for a complete
specification of these API endpoints.
CONFIDENTIAL
24
Rev.1.0.16.a.[79434afda268+]
Chapter 5. Accessing Call Log
Every inbound and outbound call connected through the RingCentral service is logged in the database.
Every extension on RingCentral account has an assigned Call Log that stores all inbound and outbound
calls for the extension. Users are able to access all of their calls to get reliable information on callers'
names, phone numbers, etc.
The RingCentral API enables the developer's application to access account (for all account extensions)
and extension (personal) call logs and perform the following:
• Retrieve a filtered list of call log records for an extension or the whole account;
• Retrieve an individual call log record;
Each call log entry returned by the API contains a number of properties describing the call. Most of them
are self-descriptive such as direction, startTime or duration.
There are two important fields: action and result which have to be specially described. These values
provide the detailed information on the call and may hold many different internally defined constant values
(result depends on action). In the table below you can find the values which are returned in common
cases.
Call Log Access Rules
Access to extension call-log is available for any user; access to account call-log is available for Admin
user only.
Account call log can be retrieved and deleted by Admin user via the following endpoints:
GET/restapi/v1.0/account/{accountId}/call-log
DELETE/restapi/v1.0/account/{accountId}/call-log
If a user (without admin rights) tries to access the account call log, the 403 Forbidden error is returned.
Extension call log can be got and deleted by any user (including Admin user) via the following endpoints:
GET/restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log
DELETE/restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log
Commonly Used Call Actions and Results
Call Actions
Action Name
Unknown
Phone Call
Phone Login
Incoming Fax
Accept Call
CONFIDENTIAL
25
Rev.1.0.16.a.[79434afda268+]
Accessing Call Log
Action Name
FindMe
FollowMe
Outgoing Fax
Call Return
Calling Card
Ring Directly
RingOut Web
VoIP Call
RingOut PC
RingMe
Transfer
411 Info
Emergency
E911 Update
Support
RingOut Mobile
Call Results
Result Name
Unknown
ResultInProgress
Missed
Call accepted
Voicemail
Rejected
Reply
Received
Receive Error
Fax on Demand
Partial Receive
Blocked
Call #onnected
No Answer
International Disabled
Busy
Send Error
Sent
No fax machine
CONFIDENTIAL
26
Rev.1.0.16.a.[79434afda268+]
Accessing Call Log
Result Name
ResultEmpty
Account Suspended
Call Failed
Call Failure
Internal Error
IP Phone offline
Restricted Number
Wrong Number
Stopped
Hang up
Poor Line Quality
Partially Sent
International Disabled
International Restriction
Abandoned
Declined
Fax Receipt Error
Fax Send Error
CONFIDENTIAL
27
Rev.1.0.16.a.[79434afda268+]
Chapter 6. Working with Messages
A wide range of telecommunication tools are used by business today: cell phones, desk phones, laptops,
PDAs, fax machines, voice mailboxes, etc. the RingCentral service functions as a unified messaging system
and provides customers with a seamless interface to interact with various communication media. Using the
API you can create applications enabled to work with all kinds of messages available to the RingCentral
customers:
• SMS — text messages sent via standard SMS communication technology;
• Fax — facsimile messages sent via fax-rendering system;
• Pager — text messages sent from one extension to another within a single RingCentral account;
• Voicemail — audio messages recorded by the caller when the called party is temporary unavailable.
Every RingCentral extension has an assigned mailbox that is used to store all the incoming and outgoing
messages for this extension. You can access all messages available for a certain extension via the unified
message store endpoint. In addition, for convenience there are endpoints available for specific types of
messages: SMS, Faxes and Pager messages.
Unified message-store endpoint allows:
• retrieving a list of messages filtered by a specific criteria from an extension mailbox;
• retrieving content and metadata of a message;
• changing the status of a message (read/unread);
• removing a message from an extension mailbox.
Dedicated fax, sms and company-pager endpoints allow working with messages of the particular type
including creating and sending new messages out.
Message Attributes
The message metadata retrieved through the API contains various information. Some metadata properties
are returned for each message, others depend on message type and direction. One of the most important
fields is status which can hold the following values:
• Received — standard status for all inbound messages.
• Queued — status for outbound fax and SMS messages, meaning the message was queued for sending.
• Sent — status for all outbound messages, meaning the message was sent successfully.
• SendingFailed — status for outbound fax and SMS messages, meaning the sending attempt has failed.
• Delivered — status for outbound SMS messages, meaning the SMS was successfully delivered to the
recipient's handset (not supported by the US mobile carriers).
• DeliveryFailed — status for outbound SMS messages, meaning the SMS was not delivered to the
recipient's handset by some reason (not supported by the US mobile carriers).
Each message also has a readStatus property which may store Read or Unread value. This status
indicates whether the user has already viewed or played a particular message. The convention is
CONFIDENTIAL
28
Rev.1.0.16.a.[79434afda268+]
Working with Messages
that whenever the application supplies the message content to the user, it should update readStatus
accordingly.
Apart from common message attributes which can be returned for a message of any type, there are some
specific properties which make sense only for particular types of messages. By convention such fields
contain special prefixes in their names.
• fax — appears only in Fax messages; example: faxResolution
• vm — appears only in Voicemail messages; example: vmDuration
• sms — appears only in SMS messages; example: smsDeliveryTime
• pg — appears only in Pager messages; example: pgToDepartment
See the API Reference section for the full list of supported message attributes.
Let's consider the example request below. GET Message Info request allows retrieving the Message
Info [86] object. In the example below the message type is SMS. The other message types: Fax, Pager,
Voicemail and Text are retrieved via the same request with the corresponding type value.
GET /restapi/v1.0/account/~/extension/~/message-store/320272588010 HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri": ".../account/1346632010/extension/1346632010/message-store/320272588010",
"id": 320272588010,
"to": [{"phoneNumber": "18551003732"}],
"from": {"phoneNumber": "18559100010"},
"type": "SMS",
"creationTime": "2012-10-18T10:40:31.000Z",
"readStatus": "Unread",
"priority": "Normal",
"attachments": [
{
"id": 1,
"uri": ".../account/1346632010/extension/1346632010/message-store/320272588010/content/1",
"contentType": "text/plain"
}],
"direction": "Outbound",
"availability": "Alive",
"subject": "Test SMS message from Platform server",
"messageStatus": "Delivered",
"smsDeliveryTime": "2012-10-18T10:40:42.000Z",
"conversationId": 4178398077955743750,
"lastModifiedTime": "2012-10-18T10:40:42.000Z"
}
Message Availability and Life Cycle
Every outbound or inbound message is created in the system in alive state. This state is tracked using the
availability property, which is returned as a part of message metadata, and contains the Alive value
by default.
Once the message is deleted by the user, its availability is changed to Deleted, but it still remains in the
extension mailbox and can be restored by the user.
After being Deleted for a certain time (by default, 5 days) the system erases message data (attachments)
and automatically switches its availability to Purged. Purged messages cannot be restored but their
CONFIDENTIAL
29
Rev.1.0.16.a.[79434afda268+]
Working with Messages
metadata is stored in the system for some time (by default, 5 days). After that all information about such
messages is physically removed from the system.
There is a separate constraint defining the maximum number of messages which can be stored in a mailbox.
If this threshold is exceeded the system will delete some old messages automatically.
The user is able to filter out the messages by their availability. By default, unless a specific availability
value is passed in the query, all message retrieval endpoints hide the deleted or purged messages.
SMS and Pager Messages
There are two types of short text messages supported by RingCentral: SMS and Pager.
SMS messages can be received by the extension types: User and Take Messages Only (Voicemail).
Pager messages can be received by the extension types: User, Take Messages Only (Voicemail) and
Department.
SMS/pager message length limitation is 160 symbols.
SMS messages can be sent out to or received from the handsets operated by most mobile carriers (all
major US carriers are currently supported). Each SMS is a peer-to-peer message from one phone number
to another. There is a special sms API endpoint to create and send SMS messages. See example below.
POST /restapi/v1.0/account/~/extension/~/sms HTTP/1.1
Content-Type: application/json
Content-Length: ACTUAL_CONTENT_LENGTH_HERE
{
"to": [{"phoneNumber": "14151003732"}],
"from": {"phoneNumber": "16509100010"},
"text": "Test SMS message"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri": ".../account/1346632010/extension/1346632010/message-store/320270670010",
"id": 320270670010,
"to": [{"phoneNumber": "14151003732"}],
"from": {"phoneNumber": "16509100010"},
"type": "SMS",
"creationTime": "2012-10-16T06:34:58.000Z",
"readStatus": "Unread",
"priority": "Normal",
"attachments": [
{
"id": 1,
"uri": ".../account/1346632010/extension/1346632010/message-store/320270670010/content/1",
"contentType": "text/plain"
}],
"direction": "Outbound",
"availability": "Alive",
"subject": "Test SMS message",
"messageStatus": "Sent",
"conversationId": 4178398077955743750,
"lastModifiedTime": "2012-10-16T06:34:59.000Z"
}
Pager messages are RingCentral specific types of text messages which can be sent between extensions of
one account. Unlike SMS, pager messages can be sent to multiple recipients, so the API allows several
extension numbers in the to field. Another difference from SMS is that the pager message that is sent to
the department extension is automatically forwarded to all department members. This allows setting up
CONFIDENTIAL
30
Rev.1.0.16.a.[79434afda268+]
Working with Messages
dedicated mailing lists within the organization. The endpoint company-pager is designed to handle pager
messages. The example below demonstrates sending new pager messages via the API.
POST /restapi/v1.0/account/~/extension/~/company-pager HTTP/1.1
Content-Type: application/json
Content-Length: ACTUAL_CONTENT_LENGTH_HERE
{
"to": [{"extensionNumber": "102"},
{"extensionNumber": "103"}],
"from": {"extensionNumber": "101"},
"text": "Hello!"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri": ".../account/1346632010/extension/1346632010/message-store/320272670010",
"id": 320272670010,
"to":
[
{"extensionNumber": "101"},
{"extensionNumber": "102"},
{"extensionNumber": "103"}
],
"from": {"extensionNumber": "101"},
"type": "Pager",
"creationTime": "2012-10-18T13:18:24.000Z",
"readStatus": "Unread",
"priority": "Normal",
"attachments": [
{
"id": 1,
"uri": "http:.../restapi/v1.0/account/1346632010/extension/1346632010/messagestore/320272670010/content/1",
"contentType": "text/plain"
}],
"direction": "Outbound",
"availability": "Alive",
"subject": "Hello!",
"messageStatus": "Sent",
"conversationId": 320272670010,
"lastModifiedTime": "2012-10-18T13:18:24.000Z",
"pgToDepartment": false
}
Sending SMS messages on behalf of Department extensions is allowed. To send an SMS message from the
Department direct phone number, the user should be logged in as the department manager (with department
credentials). When requesting a phone number list for a Department extension type, SmsSender flag set
for department numbers is returned.
Sending pager messages on behalf of a Department is not allowed; in the case of such an attempt, the
department manager is notified that sending pages is not allowed for the Department extension type.
Sending pager/SMS messages to Disabled and Frozen extension types is not allowed. When an SMS
message is sent to a Disabled/Frozen extension, it is dropped. The dropped message is saved only in the
sender's outbox. When the page is sent to a Disabled/Frozen extension or to the list of extensions containing
at least one Disabled/Frozen extension, the server immediately responds with the 400 Bad Request error
code and the explanatory message. But if the page is sent to a Department extension list containing any
Disabled/Frozen extensions, the error is not returned, and this pager message is received only by active
extensions of the Department.
Pager Messaging Threads
The API supports pager messaging threads for the User extensions, including Department extensions.
Those internal message conversations are not accessible for reading or writing by users which were
CONFIDENTIAL
31
Rev.1.0.16.a.[79434afda268+]
Working with Messages
removed from the explicit or implicit list of recipients in this conversation. For example, a user extension
included in a Department extension is able to participate in the Department conversation, sending and
receiving messages. Once this particular user is removed from the department, he/she is not able to reply
to previous messages, nor send or receive new messages. It means that, when somebody posts a reply to
a particular conversation (by indicating replyOn in API requests), the server checks if the user belongs
to the actual list of recipients (implicitly, through Department membership, or explicitly). If the user does
not belong to the recipient list, the server returns the 403 Forbidden error code with the appropriate logical
code.
Fax Messages
RingCentral supports working with fax messages.
Fax messages can be sent by User extensions only and can be received by all extension types. Phonenumber types that are available to send and receive Faxes are Fax Only, Voice And Fax.
The system allows sending a fax immediately or scheduled for a specific time; and tracking the status of
an outgoing message (Sent).
The Fax API allows creating, sending and retrieving fax messages. The Fax general description in JSON
format and the fax contents (attachments) are retrieved separately, by different requests.
Send Fax
The API allows sending a fax message with a multipart request, incorporating two or more parts. The first
part of the request is a general fax message description in json format, including the following parameters:
• to [phone number, name, location]
Required. Fax message recipients, their names, numbers and locations
• sendTime
Optional. Schedule time, which is set if the fax is to be sent at a specific time
• faxResolution
Resolution of the fax message
• coverIndex
Optional. Cover page index.
• coverPageText
Optional. Text entered by the fax sender and printed on fax cover page. The value is limited to 1024
symbols
The second and subsequent parts of the request are binary attachments in the formats JPEG, TIFF, DOCX,
etc. Every attachment is provided according to MIME multipart (RFC-1341 [https://tools.ietf.org/html/
rfc1341]) standard. Fax attachments are rendered into a single document.
A fax message can be sent to several recipients that are listed in the to field. As a response to a sent fax
request the server returns fax message representation, including id and uri.
Fax Attachment Limitations
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.
CONFIDENTIAL
32
Rev.1.0.16.a.[79434afda268+]
Working with Messages
Note
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.
To send a fax request with attachments, it is necessary to specify Content-Type header either "application/
octet-stream", or any supported explicit MIME type (Fax Attachments. MIME Types ).
If Content-Type is set to application/octet-stream it is necessary to specify the file name in the
Content-Disposition header. If the file name does not exist or is empty in Content-Disposition
header, the server returns the 400 Bad Request error with the logical error code InvalidParameter
("No content disposition").
If the Content-Type of a fax attachment is set to any supported explicit MIME type, then ContentDisposition is optional. If Content-Disposition header is specified, the file name is taken from it.
If Content-Disposition header is absent, a file name is auto-generated, and a file extension is derived
from the Content-Type header.
Please consider the examples below, describing different methods of sending fax requests.
1. Request: Passing attachments in a fax by specifying the Content-Type of fax attachments as a MIME
type (see Fax Attachments. MIME Types for details)
POST /restapi/v1.0/account/~/extension/~/fax HTTP/1.1
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888
Content-Length: ACTUAL_CONTENT_LENGTH_HERE
--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: text/plain
Hello, World!
--Boundary_1_14413901_1361871080888--
2. Request: Passing attachments in a fax by specifying the Content-Type of fax attachments as a MIME
type (see Fax Attachments. MIME Types for details) and a filename in the Content-Disposition header.
CONFIDENTIAL
33
Rev.1.0.16.a.[79434afda268+]
Working with Messages
POST /restapi/v1.0/account/~/extension/~/fax HTTP/1.1
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888
Content-Length: ACTUAL_CONTENT_LENGTH_HERE
--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: text/plain
Content-Disposition: attachment; filename="fax.txt"
Hello, World!
--Boundary_1_14413901_1361871080888--
3. Request: Passing attachments in a fax by specifying the Content-Type "application/octet-stream" and
a filename in the Content-Disposition header.
POST /restapi/v1.0/account/~/extension/~/fax HTTP/1.1
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888
Content-Length: ACTUAL_CONTENT_LENGTH_HERE
--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: application/octet-stream
Content-Disposition: attachment; filename="fax.txt"
Hello, World!
--Boundary_1_14413901_1361871080888--
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri": ".../account/284818008/extension/284822008/message-store/3291497008",
"id": 3291497008,
"to": [{"phoneNumber": "18005630003"}],
"type": "Fax",
"creationTime": "2013-02-26T08:35:04.000Z",
"readStatus": "Unread",
"priority": "Normal",
"attachments": [
{
"id": 1,
"uri": ".../account/284818008/extension/284822008/message-store/3291497008/content/1",
"contentType": "image/tiff"
}],
"direction": "Outbound",
"availability": "Alive",
"messageStatus": "Queued",
"faxResolution": "High",
"faxPageCount": 0,
"lastModifiedTime": "2013-02-26T08:35:04.000Z"
}
CONFIDENTIAL
34
Rev.1.0.16.a.[79434afda268+]
Working with Messages
Get Fax Message
The fax API allows to retrieve a fax message, general information. As a result of get fax request the server
returns the general fax message description in JSON format. The fax content (attachments) is not returned
in that case but the main attachment parameters id, uri and contentType are returned. If a fax message
is not found by its ID, the server returns 404 Not Found error.
Let's consider the example below:
GET /restapi/v1.0/account/~/extension/~/fax/7269038008 HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri": ".../account/130253008/extension/130253008/message-store/7269038008",
"id": 7269038008,
"to": [{"phoneNumber": "18559100010"}],
"type": "Fax",
"creationTime": "2013-01-29T06:22:09.000Z",
"readStatus": "Unread",
"priority": "Normal",
"attachments": [{
"id": 1,
"uri": ".../account/130253008/extension/130253008/message-store/7269038008/
content/1",
"contentType": "image/tiff" }]
}
Get Fax Content
The fax API also allows getting the fax content. Outbound fax content is always retrieved in TIFF format.
Inbound fax content is always retrieved in TIFF or PDF formats.
If fax message is not found by ID, the server returns 404 Not Found error.
Let's consider the example below:
GET /restapi/v1.0/account/~/extension/~/fax/7269038008/content/1 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: image/tiff
<...binary...>
Fax Attachments. MIME Types
The API supports all the MIME Types listed in the table below:
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
docm
application/vnd.ms-word.document.macroenabled.12
Microsoft Word
docx
application/vnd.openxmlformatsofficedocument.wordprocessingml.document
Microsoft Word
xls
application/vnd.ms-excel
Microsoft Excel
CONFIDENTIAL
35
Rev.1.0.16.a.[79434afda268+]
Working with Messages
File
Extension
MIME Type
Application Type
xlsb
application/vnd.msexcel.sheet.binary.macroenabled.12
Microsoft Excel
xlsm
application/vnd.ms-excel.sheet.macroenabled.12
Microsoft Excel
xlsx
application/vnd.openxmlformatsofficedocument.spreadsheetml.sheet
Microsoft Excel
ppt
application/vnd.ms-powerpoint
Microsoft PowerPoint
pptm
application/vnd.mspowerpoint.presentation.macroenabled.12
Microsoft PowerPoint
pptx
application/vnd.openxmlformatsofficedocument.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
Fax Error Codes.
The following logical error codes can be returned in error responses for fax requests.
CONFIDENTIAL
36
Rev.1.0.16.a.[79434afda268+]
Working with Messages
Logical Error Code
InvalidParameter
Description
HTTP Code
1. No recipients are indicated in the request
400 Bad Request
2. Recipient phone number is empty
3. The coverIndex parameter is invalid: greater
than zero (0) and not within the list of values
available for cover pages (0-16)
InvalidContent
1. The size of all the fax message attachments
400 Bad Request
(TotalMessageSize) exceeds the limitation (20Mb
by default)
2. Any single attachment size exceeds the limitation
(20 Mb by default)
FeatureNotAvailable
1. Fax feature is not supported for the account
403 Forbidden
2. Extension is not allowed to send/receive fax
messages
CONFIDENTIAL
37
Rev.1.0.16.a.[79434afda268+]
Chapter 7. RingOut
The RingOut option enables the users to make a call from any other outside number (not RingCentral
number) by means of the RingCentral account, when it is not convenient for them to use the RingCentral
number. This feature is available for softphone, web service and mobile applications.
The user specifies a certain number under the forwarding number list, starts RingOut and enters the
required called number. RingCentral makes a call to the specified forwarding number and connects the
user with the called number.
The API treats a two-legged RingOut call as a resource that can be created, retrieved, or deleted via the
POST, GET and DELETE methods correspondingly.
Note
RingOut API cannot be called on behalf of Department/Announcement Only/Take
Messages Only (Voicemail)/FaxUser (Fax only) extension types; the server responds with
the 403 Forbidden error code in this case.
Two-Legged RingOut Call
1. The two-legged RingOut call can be created via the following request:
POST /restapi/v1.0/account/~/extension/~/ringout
Content-Type: application/json
Authorization: Bearer <access-token>
{
"from": {"phoneNumber": "13443334444"}, /* from parameter is optional if there is a
default number in user's forwarding numbers */
"to": {"phoneNumber": "13453443434"}, /* to parameter is required */
"callerId": {"phoneNumber": "13443334444"}, /* optional field*/
"playPrompt": true /* optional field */
}
Where:
• from
Refers to the number of the calling party. Required field only if there is no default number in the user's
forwarding number list. The phoneNumber attribute should comply with the E.164 standard. As a result
of validation of the phoneNumber attribute the server may return the error code: 400 Bad Request phoneNumber specified in the field is empty or invalid.
• to
Refers to the called party number. Required field. If this field is missing from the request, the 400
Bad Request error is returned. The phoneNumber attribute should comply with the E.164 standard.
As a result of validation of the phoneNumber attribute the server may return the error code: 400 Bad
Request - phoneNumber specified in the field is empty or invalid.
• callerId
The number which is displayed to the called party. Optional field. If the field is specified and invalid
the 403 Forbidden error code is returned. If the field is not specified in the request then it is based
CONFIDENTIAL
38
Rev.1.0.16.a.[79434afda268+]
RingOut
on the CallerId parameter specified in RingCentral application (Main phone Number/Current Location
Number/Blocked).
Caller ID Validation Rules:
• callerId is the same as the user's extension number;
• Get all phone numbers associated with the mailbox. Phone is the default and callerId is the same
as this number;
• Get a list of all forwarded phone numbers for the user. callerId is the same as one of the local or
toll-free numbers.
• playPrompt
The audio prompt that the calling party hears when the call is connected. Optional field. It corresponds to
the setting in the RingCentral application "Prompt me to dial 1 before connecting" (When selected, the
system will ask you to press "1" on your phone's key pad before connecting to the destination number).
The response can be as follows:
200 OK
Content-Type: application/json
{
"id": 234343434,
"uri": "/restapi/v1.0/account/~/extension/~/ringout/234343434",
"status": {
"callStatus": "Success",
"callerStatus": "Success",
"calleeStatus": "Success"
}
}
Where:
• callStatus can take the following values: 'Invalid' | 'Success' | 'InProgress' | 'CannotReach' | 'Error' |
'NoAnsweringMachine' | 'NoSessionFound'
• callerStatus, calleeStatus can take the following values: 'Invalid' | 'Success' | 'InProgress' | 'Busy'
| 'GenericError' | 'NoAnswer' | 'Rejected' | 'Finished' | 'InternationalDisabled' | 'DestinationBlocked'
| 'NotEnoughFunds' | 'NoSuchUser'. In case the callerStatus or calleeStatus is set to
InternationalDisabled or NotEnoughFunds, the 403 Forbidden error is returned in response.
2. The API allows getting the status of a two-legged RingOut call using the URI returned on its creation:
GET/restapi/v1.0/account/~/extension/~/ringout/234343434
The response will be as follows:
200 OK
Content-Type: application/json
{
"id": 234343434,
"uri": "/restapi/v1.0/account/~/extension/~/ringout/234343434",
"status": {
"callStatus": "Success",
"callerStatus": "Success",
CONFIDENTIAL
39
Rev.1.0.16.a.[79434afda268+]
RingOut
"calleeStatus": "Success"
}
}
3. Delete the existing two-legged RingOut call is available by the following request:
DELETE /restapi/v1.0/account/~/extension/~/ringout/234343434
204 No Content
CONFIDENTIAL
40
Rev.1.0.16.a.[79434afda268+]
Chapter 8. Notifications and
Subscriptions
There are two strategies of client-service interaction providing data renewal: poll and push. Polling implies
that the client periodically queries the server in order to get the updated data. Pushing implies that the server
immediately sends notifications to the client on any data update. RingCentral API supports both types of
data renewal. However in case of rarely changing data push notifications are evidently more effective, as
they reduce client-server traffic, server load and improve user experience by notifying client applications
on-the-fly with a minimal delay about important events.
For example, for getting new messages the client application can periodically poll the server in order to get
updates via incremental synchronization. However push notifications delivered immediately when the new
messages appear are much more convenient. To start receiving push notifications the client application
should subscribe for the required events; in this case, for the new messages.
The RingCentral API supports receiving push notifications for its clients of any type, including but not
limited to mobile applications (smartphones and tablets running Android/iOS), desktop applications (for
example, softphone for Windows/Mac), server-side applications hosted in a cloud, HTML5 applications,
etc.
The typical subscription flow is performed as follows:
• A client application subscribes to the required events through the RingCentral API. In response the
server provides all necessary information for the application to connect to the transport facilities that
deliver the notifications: channel address; if required - credentials to access the channel, and notification
payload encryption keys.
• The server starts to push events to the dedicated channel after the subscription is created. The delivery
mechanism PubNub queues a certain amount of notifications, awaiting a client to get them.
• The client can unsubscribe explicitly at any time through the API. In this case the server immediately
stops sending push notifications for this client.
• Each subscription has an expiration time and needs to be renewed explicitly by the client through the
API call. If subscription is expired, the server silently stops sending push notifications for this client. The
server may change any information it has to provide to client upon subscription renewal. Any changes
are provided in the renewal response.
Subscription Flow
To use RingCentral Push Notifications the client application can create a notifications subscription that can
further be retrieved, changed or deleted by the client via the API requests. Let's consider the subscription
flow step-by-step:
1. Authorization
2. Subscription creation
3. Notifications handling
4. Subscription renewal
5. Event Filters Modification
CONFIDENTIAL
41
Rev.1.0.16.a.[79434afda268+]
Notifications and Subscriptions
6. Unsubscribing
Authorization
When a client creates a subscription it must be authenticated and authorized to use the RingCentral API.
It includes, at least, application authentication. Certain event filter requires the client to be authorized to
access specific extension data, so the client needs to pass a valid access token in the request. For more
details please refer to the Authentication section.
Subscription Creation
To create a subscription the client application should send the following request:
POST /restapi/v1.0/subscription HTTP/1.1
In request body the client should specify event filters and delivery mode.
By setting event filters the client specifies the notifications it wants to receive. The event filter is exposed
as a URL, pointing to the RingCentral API resource which represents the data for which a notification is
sent. Currently the following event types are available: messages and presence (Event Types).
The delivery mode specifies the certain mechanism used to deliver event notification from the
RingCentral service to the client application. Delivery mechanism can be selected by specifying
deliveryMode.transportType attribute; currently only one transport channel is supported: the PubNub
cloud service (http://www.pubnub.com), which utilizes HTTP(s) long polling, web socket, and APNS
transports for delivering push notifications (for more details see PubNub).
In response the server provides the client with:
• identity of the subscription created, and its creation and expiration time; the exact event filters used for
the subscription (in case it substituted the default value for some event attribute);
• delivery mode, including:
• transport type;
• address - channel name to subscribe to;
• subscriber key and secret key - subscriber credentials required to subscribe to the channel;
• encryption information.
Some event types provide sensitive data in the notification payload, which should be protected from
unauthorized access. Whenever such an event type is requested in eventFilters, encryption is forced
on the notifications channel, resulting in all notifications (including those that do not contain sensitive
data) to be encrypted. To indicate the encryption mode for a new or renewed subscription, the server
specifies the following attributes under deliveryMode: encryptionAlgorithm — name of the specific
encryption mechanism, "None" by default. Available encryption mechanisms: encryptionKey — key
to be used by the client to decode the notification payload. Encryption can also be forced by specifying
deliveryType.encryption = true in subscription creation request.
Consider the following subscription creation request:
POST .../restapi/v1.0/subscription
{
CONFIDENTIAL
42
Rev.1.0.16.a.[79434afda268+]
Notifications and Subscriptions
"eventFilters": [
"/restapi/v1.0/account/~/extension/401550809004/presence?detailedTelephonyState=true"
],
"deliveryMode": {
"transportType": "PubNub"
}
}
In response to this request the client application will get all the required information to subscribe to a
certain PubNub channel (see PubNub section below to get more information about PubNub subscribing)
and receive push notifications for the selected event (extension presence in this case):
HTTP/1.1 200 OK
{
"eventFilters" : [ "/restapi/v1.0/account/~/extension/401550809004/presence?
detailedTelephonyState=true" ],
"id" : "78c53776-6aa5-4089-b080-150089c097bf",
"deliveryMode" : {
"transportType" : "PubNub",
"encryption" : true,
"address" : "96830102602705_0d0115d5",
"subscriberKey" : "sub-c-b8b9cd8c-e906-11e2-b383-02ee2ddab7fe",
"secretKey" : "sec-c-ZDNlYjY0OWMtMWFmOC00OTg2LWJjMTMtYjBkMzgzOWRmMzUz",
"encryptionAlgorithm" : "AES",
"encryptionKey" : "fNP0fszFJdc/thDO90/B3A=="
},
"expirationTime" : "2013-09-13T13:58:57.187Z",
"status" : "Active",
"creationTime" : "2013-09-13T13:43:57.187Z",
"uri" : "/restapi/v1.0/subscription/78c53776-6aa5-4089-b080-150089c097bf"
}
Notifications Handling
Push notifications will be delivered to the client application via the delivery mechanism specified in
subscription. Each notification has the same common structure, which can be easily described with a
simple example:
{
"uuid":"ed1cf00c-0420-4bf5-a0ae-e659bb9f77e0",
"event": "/restapi/v1.0/account/~/extension/823476228762/message-store",
"timestamp": "2013-06-14T12:00:00.000Z",
"body": {
/* depends on event type, may even be omitted, if event does not need a payload. */
}
}
According to received notification the client application should either update local data or notify user about
data changes (for example, new messages received).
Subscription Renewal
Created subscription should be renewed according to its expiration time by special request, otherwise it
would not be sent to the client application after subscription expiration. After renewal any parameter of
subscription may be changed, so it should be updated on a client side as well. To renew the subscription
use the following request:
PUT /restapi/v1.0/subscription/{subscriptionId}
{}
CONFIDENTIAL
43
Rev.1.0.16.a.[79434afda268+]
Notifications and Subscriptions
Note
It is recommended to renew a subscription around 1-2 minutes before it is expired.
The client should be aware that there may be strict throttling settings on subscriptions
operations.
Event Filters Modification
In order to subscribe to any other events the client application can create additional subscriptions, but it is
preferable to update the already existing subscription with the new event filters. To make this subscription
modification the following request should be used:
PUT /restapi/v1.0/subscription/{subscriptionId}
{
"eventFilters": [
"/restapi/v1.0/account/~/extension/12345/presence",
"/restapi/v1.0/account/~/extension/98765/presence",
"/restapi/v1.0/account/~/extension/~/message-store"
]
}
Unsubscribing
If the application does not need to receive push notifications anymore due to some reason, it should
unsubscribe from notifications through special API call. The existing subscription can be deleted as
follows:
DELETE /restapi/v1.0/subscription/78c53776-6aa5-4089-b080-150089c097bf HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFKV1MwMnxXEhpuK23FJtRSi_rafOgPSMOorQ
The response will be the following:
HTTP/1.1 204 No Content
Notifications Transport
The system requires a certain transportation mechanism to deliver event notifications from the RingCentral
service to the client application. Currently the API uses the PubNub cloud service as a transportation
channel.
PubNub
The delivery mode uses external service provider PubNub. This provider uses WebSocket, HTTP longpolling, or Apple Push Notifications transports to deliver notifications. It is specifically well suited for
web, standalone and mobile applications, and provides an extensive set of client libraries for all of these
platforms.
To use this mechanism the client should specify PubNub as a value of deliveryMode.transportType
attribute. In response the server provides the following information to be used to connect to PubNub
channel:
CONFIDENTIAL
44
Rev.1.0.16.a.[79434afda268+]
Notifications and Subscriptions
• address — PubNub channel name to subscribe to;
• subscriberKey and optional secretKey — PubNub subscriber credentials required to subscribe to
the channel.
The client uses this information to properly configure the PubNub client library and subscribe to the
channel.
PubNub provides SDKs for many popular operating systems and frameworks: iOS, Android, Ruby,
JavaScript, Java, Objective C, .Net etc. You can find full list of SDKs on the page http://www.pubnub.com/
developers/. PubNub HTTP REST API can be also used as well. For example, to subscribe for push
notifications with channel (address) and credentials (subscriberKey) provided by RingCentral API as it
described above, you can use the following HTTP request:
GET http://pubsub.pubnub.com/subscribe/{subscriberKey}/{address}/{callback}/{timetoken}
You can find full PubNub REST API description on this page http://www.pubnub.com/http-rest-push-api/.
CONFIDENTIAL
45
Rev.1.0.16.a.[79434afda268+]
Chapter 9. Dictionary: Getting Static
Data
The RingCentral API allows to retrieve data on all the countries available for calling. It is implemented in
order to provide the API clients with the access to the taxonomy of all countries, states, locations (cities)
and timezones. This information changes very rarely. The client application is free to cache the data for
a long period of time.
Dictionary API exposes the following data:
1. List of countries that are available for this client, and the service information about each of them can
be retrieved by the following request:
GET /restapi/v1.0/dictionary/country
The server will return the list of countries sorted by official name of the country in ascending order. The
list also contains 2-letter codes of the countries according to the ISO 3166 [http://en.wikipedia.org/wiki/
ISO_3166]. You may limit the list returned in the response by setting the perPage and page parameters.
Let's consider the example below:
GET /restapi/v1.0/dictionary/country?page=8&perPage=2 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXxLLQ6JlTXrScjYNTqqwQ56h7o8wA
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/country?page=8&perPage=2",
"records" : [ {
"uri" : "https.../restapi/v1.0/dictionary/country/15",
"id" : "15",
"name" : "Australia",
"isoCode" : "AU",
"callingCode" : "61"
}, {
"uri" : "https.../restapi/v1.0/dictionary/country/16",
"id" : "16",
"name" : "Austria",
"isoCode" : "AT",
"callingCode" : "43"
} ],
"paging" : {
"page" : 8,
"totalPages" : 124,
"perPage" : 2,
"totalElements" : 247,
"pageStart" : 14,
"pageEnd" : 15
},
"navigation" : {
"nextPage" : {
"uri" : "https.../restapi/v1.0/dictionary/country?page=9&perPage=2"
},
"previousPage" : {
"uri" : "https.../restapi/v1.0/dictionary/country?page=7&perPage=2"
},
"firstPage" : {
"uri" : "https.../restapi/v1.0/dictionary/country?page=1&perPage=2"
},
"lastPage" : {
"uri" : "https.../restapi/v1.0/dictionary/country?page=124&perPage=2"
}
}
CONFIDENTIAL
46
Rev.1.0.16.a.[79434afda268+]
Dictionary: Getting Static Data
}
The API also allows retrieving data on a particular country, by specifying its Id in the request body
as follows:
GET /restapi/v1.0/dictionary/country/{countryId}
2. List of states of a particular country, the internal identifier of which should be specified in the request:
GET /restapi/v1.0/dictionary/state
The server will return the list of states for the specified country, also containing the 2-letter codes of
these states. You may limit the list returned in the response by setting the perPage and page parameters.
Let's consider the example:
GET /restapi/v1.0/dictionary/state?countryId=39&perPage=2 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXwpFKvx9Iz1xWLuiVfUxwkPp66yOQ
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/state?countryId=39&page=1&perPage=2",
"records" : [ {
"uri" : "https.../restapi/v1.0/dictionary/state/501",
"id" : "501",
"name" : "Alberta",
"isoCode" : "AB",
"country" : {
"uri" : "https.../restapi/v1.0/dictionary/country/39"
}
}, {
"uri" : "https.../restapi/v1.0/dictionary/state/505",
"id" : "505",
"name" : "British Columbia",
"isoCode" : "BC",
"country" : {
"uri" : "https.../restapi/v1.0/dictionary/country/39"
}
} ],
"paging" : {
"page" : 1,
"totalPages" : 7,
"perPage" : 2,
"totalElements" : 13,
"pageStart" : 0,
"pageEnd" : 1
},
"navigation" : {
"nextPage" : {
"uri" : "https.../restapi/v1.0/dictionary/state?countryId=39&page=2&perPage=2"
},
"firstPage" : {
"uri" : "https.../restapi/v1.0/dictionary/state?countryId=39&page=1&perPage=2"
},
"lastPage" : {
"uri" : "https.../restapi/v1.0/dictionary/state?countryId=39&page=7&perPage=2"
}
}
}
The API also allows retrieving data on a particular state, by specifying its Id in the request body as
follows:
GET /restapi/v1.0/dictionary/state/{stateId}
CONFIDENTIAL
47
Rev.1.0.16.a.[79434afda268+]
Dictionary: Getting Static Data
3. List of locations (cities) with the area/central office phone codes for a particular state, which ID should
be specified as query parameter for the following request:
GET /restapi/v1.0/dictionary/location
The server will return the list of locations (that means cities, or some other location entities) for the state
specified. The list will also contain all NPA and NXX phone codes for all the cities of this state (refer
to North American Numbering Plan [http://en.wikipedia.org/wiki/North_American_Numbering_Plan]
for details on phone codes). All the locations are sorted depending on the query parameter, by default
it is set to the city name. You may sort the list either by the location name or by the area phone code.
You may also limit the list returned in the response by setting the perPage and page parameters. Let's
consider the example:
GET /restapi/v1.0/dictionary/location?stateId=501&page=1&orderBy=NPA&perPage=3 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXwpFKvx9Iz1xWLuiVfUxwkPp66yOQ
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/location?
stateId=501&orderBy=NPA&page=1&perPage=3",
"records" : [ {
"city" : "Calgary",
"npa" : "403",
"nxx" : "null",
"state" : {
"uri" : "https.../restapi/v1.0/dictionary/state/501"
}
}, {
"city" : "Calgary",
"npa" : "403",
"nxx" : "800",
"state" : {
"uri" : "https.../restapi/v1.0/dictionary/state/501"
}
}, {
"city" : "Calgary",
"npa" : "403",
"nxx" : "775",
"state" : {
"uri" : "https.../restapi/v1.0/dictionary/state/501"
}
} ],
"paging" : {
"page" : 1,
"totalPages" : 4,
"perPage" : 3,
"totalElements" : 10,
"pageStart" : 0,
"pageEnd" : 2
},
"navigation" : {
"nextPage" : {
"uri" : "https.../restapi/v1.0/dictionary/location?
stateId=501&orderBy=NPA&page=2&perPage=3"
},
"firstPage" : {
"uri" : "https.../restapi/v1.0/dictionary/location?
stateId=501&orderBy=NPA&page=1&perPage=3"
},
"lastPage" : {
"uri" : "https.../restapi/v1.0/dictionary/location?
stateId=501&orderBy=NPA&page=4&perPage=3"
}
}
}
CONFIDENTIAL
48
Rev.1.0.16.a.[79434afda268+]
Dictionary: Getting Static Data
4. List of timezones can be retrieved by the following request:
GET /restapi/v1.0/dictionary/timezone
The server will return all available timezones - their names and brief descriptions. Besides you may
limit the response by setting the perPage and page parameters, as in the example:
GET /restapi/v1.0/dictionary/timezone?perPage=1 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXzK9iQu0XSysn38K_JF7p4cImVcNw
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/timezone?page=1&perPage=1",
"records" : [ {
"uri" : "https.../restapi/v1.0/dictionary/timezone/1",
"id" : "1",
"name" : "GMT",
"description" : "Casablanca, Monrovia, Reykjavik"
} ],
"paging" : {
"page" : 1,
"totalPages" : 90,
"perPage" : 1,
"totalElements" : 90,
"pageStart" : 0,
"pageEnd" : 0
},
"navigation" : {
"nextPage" : {
"uri" : "https:.../restapi/v1.0/dictionary/timezone?page=2&perPage=1"
},
"firstPage" : {
"uri" : "https.../restapi/v1.0/dictionary/timezone?page=1&perPage=1"
},
"lastPage" : {
"uri" : "https.../restapi/v1.0/dictionary/timezone?page=90&perPage=1"
}
}
}
The API also allows retrieving data on a particular timezone, by specifying its ID in the request body
as follows:
GET /restapi/v1.0/dictionary/timezone/{timezoneId}
Note
If any ID specified by user in the request is invalid (does not exist; is not available; is
incorrect for this particular request) the server will return the error message "Object not
found".
CONFIDENTIAL
49
Rev.1.0.16.a.[79434afda268+]
Part II. API Reference
This part of the Developer's Guide gives information on the API endpoints with a detailed description of all of the
parameters and examples.
CONFIDENTIAL
50
Rev.1.0.16.a.[79434afda268+]
Chapter 10. Common Data Types and
Structures
There are some common primitive and complex data types which are used in different API methods. This
chapter contains information about such structures which will be cross-referenced from other sections.
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 [http://www.w3.org/TR/NOTEdatetime] .
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
MM
DD
hh
mm
ss
s
second
TZD
=
=
=
=
=
=
=
four-digit year
two-digit month (01=January, etc.)
two-digit day of month (01 through 31)
two digits of hour (00 through 23) (am/pm NOT allowed)
two digits of minute (00 through 59)
two digits of second (00 through 59)
one or more digits representing a decimal fraction of a
= 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).
CONFIDENTIAL
51
Rev.1.0.16.a.[79434afda268+]
Common Data Types and Structures
Data Type
Description
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"
}
Common Collection Properties
The table below describes properties which are supported by all collection resources.
Parameter
Type
Description
paging.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)
paging.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
paging.pageStart
integer
The zero-based number of the first element on the current
page. Omitted if the page is omitted or result is empty
CONFIDENTIAL
52
Rev.1.0.16.a.[79434afda268+]
Common Data Types and Structures
Parameter
Type
Description
paging.pageEnd
integer
The zero-based index of the last element on the current
page. Omitted if the page is omitted or result is empty
paging.totalPages
integer
The total number of pages in a dataset. May be omitted for
some resources due to performance reasons
paging.totalElements
integer
The total number of elements in a dataset. May be omitted
for some resource due to performance reasons
navigation.firstPage
URI string
The canonical URI for the first page of the list
navigation.nextPage
URI string
The canonical URI for the next page of the list
navigation.previousPage
URI string
The canonical URI for the previous page of the list
navigation.lastPage
URI string
The canonical URI for the last page of the list
Generic Path Parameters
Most of the API resources require specifying the following path parameters.
Parameter
Type
Description
accountId
integer
Internal identifier of a RingCentral account or tilde (~) to indicate
the account which was logged-in within the current session
extensionId
integer
Internal identifier of an extension or tilde (~) to indicate the
extension assigned to the account logged-in within the current
session
partnerId
string
For Partner Applications Internal identifier of an account or
extension created by partner. RingCentral supports the mapping of
accounts and stores the corresponding accountId/extensionId
for each partnerId of a client application. In request URIs
partnerIds are accepted instead of regular RingCentral native IDs
as path parameters using pid = XXX clause. Though in response
URIs contain the corresponding accountIds and extensionIds.
In all request and response bodies these values are reflected via
"partnerId" attributes of account and extension
Common Query Parameters in Collection
Resources
All collection resources which support paging allow using the following standard query parameters.
Parameter
Type
Description
page
integer
Optional. Indicates the page number to retrieve. Only
positive number values are allowed. Default value is '1'.
perPage
integer
Optional. Indicates the page size (number of items). If not
specified, the value is '100' by default. If perPage value is:
• perPage > 0
- particular page is returned, if it is possible to return the
subset of results according to given parameters
CONFIDENTIAL
53
Rev.1.0.16.a.[79434afda268+]
Common Data Types and Structures
Parameter
Type
Description
- no records are returned (collection paging metadata is
returned, page is omitted, default perPage is returned)
• perPage = 0
- such requests are used to get default navigation
metadata
- no records are returned
- collection paging metadata is returned as for request
without paging parameters (default values), page value is
omitted
• perPage = max (special string value)
- perPage is set to maximum value (that may vary for
different resources). The server behavior is as if perPage
is set explicitly to the maximum possible value. In
returned paging metadata perPage is explicitly set, but
URIs are built with perPage=max
• if other values are set, then the server returns 400 Bad
Request error
Caller Info
All API resources which deal with messages and call logs use the Caller Info data structure to represent
parties which are involved in communication. The table below describes properties which can be returned
as a part of the Caller Info. Please note that not all properties listed are guaranteed to be returned: it depends
on a particular use case.
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)
CONFIDENTIAL
54
Rev.1.0.16.a.[79434afda268+]
Common Data Types and Structures
Parameter
Type
string
name
Description
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
Standard Error Response
In case of unsuccessful request the API returns an error. Standard error response generally contains these
two parameters: errorCode and message.
Also, there are some parameters that are returned for certain HTTP error status codes. For example, the
eventId parameter is returned in error response body in case of 500 Internal Server Error HTTP
status code. This parameter has been introduced in order to simplify detection of error reasons by logging.
All the parameters that may occur in the error response body are given in the table below.
Response Body
Parameter
Type
Description
message
string
Human-readable text describing the error reason
errorCode
string
High level logical error code
parameterName
string
For 400 Bad Request only Name of incorrect parameter
parameterValue
string
For 400 Bad Request only Specified parameter value
description
string
For 400 Bad Request only Description of an error
eventId
string
For 500 Internal server Error only Internal identifier of an
error
Example
Response example
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"message": "Specified recipient [78083672] isn't a US phone number",
"errorCode": "InternationalProhibited"
}
CONFIDENTIAL
55
Rev.1.0.16.a.[79434afda268+]
Chapter 11. Authentication
The RingCentral API supports OAuth 2.0 authentication flows as described in RFC-6749: The OAuth 2.0
Authorization Framework [https://tools.ietf.org/html/rfc6749], RFC-6750: The OAuth 2.0 Authorization
Framework: Bearer Token Usage [https://tools.ietf.org/html/rfc6750] and RFC-7009: OAuth 2.0 Token
Revocation [https://tools.ietf.org/html/rfc7009].
Get Token
Resource Owner Password Credentials Flow
Since 1.0.4 (Release 5.13)
Issues new access and refresh tokens. Requests to this endpoint must be authenticated with HTTP Basic
scheme using the application key and application secret as login and password, correspondingly.
Method/URI
POST /restapi/oauth/token
The following request parameters are passed when using Resource Owner Credentials flow.
Usage Plan Group
Auth
Request Body
Content Type: application/x-www-form-urlencoded
Parameter
Type
Description
grant_type
string
Must hold password value for Resource Owner
Credentials flow
access_token_ttl
integer
Optional. 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
Optional. 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.
username
string
Phone number linked to account or extension in account
in E.164 format with or without leading "+" sign
extension
string
Optional. 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
CONFIDENTIAL
56
Rev.1.0.16.a.[79434afda268+]
Authentication
Parameter
Type
Description
password
string
User's password
scope
string
Optional. List of API permissions to be used with access
token (see Application Permissions). Can be omitted
when requesting all permissions defined during the
application registration phase
endpoint_id
string
Optional. Unique identifier of a client application
generated by the client and valid during the application
lifetime
Response Body
Content Type: application/json, application/xml
Token Info
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. Use this parameter in Authorization
header of requests
owner_id
string
Extension identifier
endpoint_id
string
Optional. Unique identifier of a client application
generated by the client and valid during the application
lifetime
Example 1
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",
CONFIDENTIAL
57
Rev.1.0.16.a.[79434afda268+]
Authentication
"expires_in" : 7199,
"refresh_token" : "U1BCMDFUMDRKV1MwMXxzLFL4ec6A0XMsUv9wLriecyxS_w",
"refresh_token_expires_in" : 604799,
"scope" : "AccountInfo CallLog ExtensionInfo Messages SMS",
"owner_id" : "256440016"
}
Example 2
If the application brand ID does not match the account brand ID, then the OAU-101 error is returned with
the following message: "Parameter [brandId] is invalid" and HTTP status code 403 Forbidden.
Request example
POST /restapi/oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic WW91hguitkcEtleTpZb3VyQXBwU2VjcmV0
Accept: application/json
access_token_ttl=7200&grant_type=client_credentials&brand_id=654321
Response example
{
"error": "invalid_client",
"error_description": "Access to account denied"
"errors" : [ {
"errorCode" : "OAU-101",
"message" : "Parameter [brandId] is invalid",
"parameters": [ {
"parameterName" : "brandId",
"parameterValue" : "123456" //account brand ID
} ]
} ]
}
Refresh Token Flow
Since 1.0.4 (Release 5.13)
Issues new access and refresh tokens by previously issued refresh token. Requests to this endpoint must
be authenticated with HTTP Basic scheme using the application key and application secret as login and
password, correspondingly.
Request Body
Content Type: application/x-www-form-urlencoded
Parameter
refresh_token
Type
string
Description
Previously issued refresh token
Response Body
Token Info [57]
Example
Request example
CONFIDENTIAL
58
Rev.1.0.16.a.[79434afda268+]
Authentication
POST /restapi/oauth/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==
refresh_token=BCMDFUMDRKV1MwMXx5d5dwzLFL4ec6U1A0XMsUv935527jghj48
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token" : "U1BCMDFUMDRKV1MwMXxzLFSvXdw5PHMsVLEn_MrtcyxUsw",
"token_type" : "bearer",
"expires_in" : 7199,
"refresh_token" : "U1BCMDFUMDRKV1MwMXxzLFL4ec6A0XMsUv9wLriecyxS_w",
"refresh_token_expires_in" : 6048799,
"scope" : "AccountInfo CallLog ExtensionInfo Messages SMS"
}
Revoke Token
Since 1.0.5 (Release 5.14)
Revokes access/refresh token. Requests to this endpoint must be authenticated with HTTP Basic scheme
using the application key and application secret as login and password, correspondingly.
Request Body
Content Type: application/x-www-form-urlencoded
Parameter
token
Type
string
Description
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
CONFIDENTIAL
59
Rev.1.0.16.a.[79434afda268+]
Chapter 12. API Versioning
Get API Versions
Since 1.0.0
Returns current API version(s) and server info.
Method/URI
GET /restapi
Usage Plan Group
Light
Request Body
None
Response Body
Parameter
Type
Description
uri
string
Standard resource property canonical URI, see the
section called “Resource Identification Properties”
apiVersions
Collection of
[VersionInfo [60]]
Full API version information: uri, number, release
date
serverVersion
string
Server version
serverRevision
string
Server revision
Version Info
Parameter
Type
Description
uri
string
Standard resource property canonical URI, see the
section called “Resource Identification Properties”
versionString
string
Version of the RingCentral REST API
releaseDate
string
Release date of this version
uriString
string
URI part determining the current version
Example
Request example
GET /restapi/ HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUFWZmY4ZXoxMlhvSmlGdjlQc1
Response example
CONFIDENTIAL
60
Rev.1.0.16.a.[79434afda268+]
API Versioning
HTTP/1.1 200 OK
Date: Mon, 13 Oct 2014 13:24:10 GMT
RoutingKey: SJC01P01PAS01
Content-Type: application/json
Content-Language: en
Content-Length: 312
{
"uri" : "https.../restapi/",
"apiVersions" : [ {
"uri" : "https.../restapi/v1.0",
"versionString" : "1.0.14",
"releaseDate" : "2014-10-31T00:00:00.000Z",
"uriString" : "v1.0"
} ],
"serverVersion" : "7.0.0.551",
"serverRevision" : "598ed4edcc56"
}
Get Version Info
Since 1.0.0
Returns current API version info by apiVersion.
Method/URI
GET /restapi/apiVersion
Usage Plan Group
Light
Path Parameters
Parameter
apiVersion
Type
Description
string
API version to be requested, for example "v1.0"
Request Body
None
Response Body
VersionInfo [60]
Example
Request example
GET /restapi/v1.0 HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUFWZmY4ZXoxMlhvSmlGdjlQc1f
Response example
CONFIDENTIAL
61
Rev.1.0.16.a.[79434afda268+]
API Versioning
HTTP/1.1 200 OK
Date: Mon, 13 Oct 2014 13:57:02 GMT
RoutingKey: SJC01P01PAS01
Content-Type: application/json
Content-Language: en
Content-Length: 156
{
"uri" : "https.../restapi/v1.0",
"versionString" : "1.0.14",
"releaseDate" : "2014-10-31T00:00:00.000Z",
"uriString" : "v1.0"
}
CONFIDENTIAL
62
Rev.1.0.16.a.[79434afda268+]
Chapter 13. Account and Extension
Information
Get Account Info
Since 1.0.0
Returns basic information about a particular RingCentral customer account.
Method/URI
GET /restapi/v1.0/account/{accountId}
Usage Plan Group
Light
Path Parameters
Parameter
accountId
Type
Description
integer
See the section called “Generic Path
Parameters”
Request Body
None
Response Body
Account Info
Parameter
Type
Description
Standard resource properties ID and canonical
URI, see the section called “Resource
Identification Properties”
id, uri
serviceInfo
Service Info [64]
Account service information, including brand,
service plan and billing plan
mainNumber
string
Main phone number of the current account
operator
Extension Info [66]
Operator's extension information. This
extension will receive all calls and messages
intended for the operator
status
'Confirmed' | 'Disabled'
Account status
setupWizardState
'NotStarted' | 'Incomplete' |
'Completed'
Specifies account configuration wizard state
(web service setup). The default value is
'NotStarted'
CONFIDENTIAL
63
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
Parameter
Type
Description
statusInfo
Collection of parameters
Status information (reason, comment, lifetime).
Returned for 'Disabled' status only
reason
'SuspendedVoluntarily' |
'SuspendedInvoluntarily'
| 'CancelledVoluntarily' |
'CancelledInvoluntarily'
Type of suspension
comment
string
A free-form user comment, describing the
status change reason
till
datetime
Date until which the account will get deleted.
The default value is 30 days since current time
partnerId
string
Additional account identifier, developed and
applied by the client
Service Info
Parameter
Type
Description
brand
id
string
Internal identifier of a brand
name
string
Brand name, for example "RingCentral UK",
"ClearFax"
id
string
Internal identifier of a home country
uri
string
Home country URI
id
string
Internal identifier of a service plan
name
string
Service plan name
id
string
Internal identifier of a billing plan
name
string
Billing plan name
durationUnit
'Month' | 'Day'
Duration period
duration
string
Number of duration units
type
'Initial' | 'Regular' | 'Suspended' Billing plan type
| 'Trial' | 'TrialNoCC' | 'Free'
homeCountry
servicePlan
billingPlan
Example
Request example
GET /restapi/v1.0/account/401145624008 HTTP/1.1
Authorization: Bearer UExBMDFUMDRQV1MwMXzq47-tLtp8ltajk78BuDxCDNYh_Q
Accept: application/json
Response example
CONFIDENTIAL
64
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/account/401145624008",
"id" : 401145624008,
"serviceInfo" : {
"uri" : "https.../restapi/v1.0/account/401145624008/service-info",
"brand" : {
"id" : "1210",
"name" : "MyCompany Inc.",
"homeCountry" : {
"id" : "1",
"uri" : "https.../restapi/v1.0/dictionary/country/1"
}
},
"servicePlan" : {
"id" : "1216",
"name" : "Professional"
},
"billingPlan" : {
"id" : "159",
"name" : "Monthly - 14.99 - Pro 101503",
"durationUnit" : "Month",
"duration" : 1,
"type" : "Regular"
}
},
"operator" : {
"uri" : "https.../restapi/v1.0/account/401145624008/extension/401145624008",
"id" : 401145624008,
"extensionNumber" : "101"
},
"mainNumber" : "18555440014",
"status" : "Confirmed",
"setupWizardState" : "Completed"
}
Get Extension Info
Since 1.0.0
Returns the information on account extension.
Method/URI
GET /restapi/v1.0/account/{accountId}/extension/{extensionId}
Usage Plan Group
Light
Path Parameters
Parameter
accountId,
extensionId
Type
Description
integer
See Generic Path Parameters
Request Body
None
CONFIDENTIAL
65
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
Response Body
Extension Info
Parameter
Type
Description
Standard resource properties ID and
canonical URI, see Common Properties
id, uri
partnerId
string
For Partner Applications Internal identifier
of an extension created by partner. The
RingCentral supports the mapping of
accounts and stores the corresponding
accountId/extensionId for each partnerId
of a client application. In request URIs
partnerIds are accepted instead of regular
RingCentral native IDs as path parameters
using pid = XXX clause. Though in
response URIs contain the corresponding
accountIds and extensionIds. In all request
and response bodies these values are
reflected via "partnerId" attributes of
account and extension
extensionNumber
string
Extension short number (usually 3 or 4
digits)
name
string
Extension user name
type
'User' | 'Fax User' | 'VirtualUser' Extension type (see Extension Information
| 'DigitalUser' | 'Department' |
for details)
'Announcement' | 'Voicemail'
| 'SharedLinesGroup' |
'PagingOnly' | 'IvrMenu' |
'ApplicationExtension'
departments
Collection of parameters
Information on department extension(s),
to which the requested extension belongs.
Returned only for user extensions, members
of department, requested by single
extensionId
uri
string
Link to full information on department
extension, see Common Properties
id
string
Internal identifier of department extension
extensionNumber
string
Number of department extension
contact
Contact Info [67]
Contact detailed information
status
'Enabled' | 'Disabled' |
'NotActivated' | 'Unassigned'
Extension current state
statusInfo
Collection of parameters
Status information (reason, comment).
Returned for 'Disabled' status only
reason
'Voluntarily' | 'Involuntarily'
Type of suspension
comment
string
A free-form user comment, describing the
status change reason
CONFIDENTIAL
66
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
Parameter
Type
Description
serviceFeatures
Collection of [Extension
Service Feature Info [68]]
Extension service features returned in
response only when the logged-in user
requests his/her own extension info, see
also Extension Service Features [68]
regionalSettings
Regional Settings [70]
Extension region data (timezone, home
country, language)
setupWizardState
'NotStarted' | 'Incomplete' |
'Completed'
Specifies extension configuration wizard
state (web service setup). The default value
is "NotStarted"
permissions
Extension Permissions [71]
Extension permissions, corresponding to
the Service Web permissions "Admin" and
"InternationalCalling"
greetings
Greetings Info [71]
The greetings that are applied during
forwarding calls
Note
Short or extended version of Extension Info can be returned depending on particular API.
Extension Info (short)
Parameter
Type
Description
Standard resource properties ID and canonical URI, see
the section called “Resource Identification Properties”
id, uri
partnerId
string
For Partner Applications Internal identifier of an
extension created by partner. The RingCentral supports
the mapping of accounts and stores the corresponding
accountId/extensionId for each partnerId of a client
application. In request URIs partnerIds are accepted
instead of regular RingCentral native IDs as path
parameters using pid = XXX clause. Though in
response URIs contain the corresponding accountIds and
extensionIds. In all request and response bodies these
values are reflected via "partnerId" attributes of account
and extension
extensionNumber
string
Extension number (usually 3 or 4 digits)
Contact Info
Parameter
Type
Description
firstName
string
For User extension type only. Extension user first name
lastName
string
For User extension type only. Extension user last name
company
string
Extension user company name
email
string
Email of extension user
businessPhone
string
Extension user contact phone number
CONFIDENTIAL
67
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
Parameter
businessAddress
Type
Contact Address
Info [68]
Description
Business address of extension user company
Contact Address Info
Parameter
Type
Description
country
string
Country name of extension user company
state
string
State/province name of extension user company
city
string
City name of extension user company
street
string
Street address of extension user company
zip
string
Zip code of extension user company
Extension Service Feature Info
Parameter
Type
Description
featureName
string
Feature name, see all available values in Service Feature
List [68]
enabled
True | False
Feature status; shows feature availability for an extension
reason
string
Reason of limitation for a particular service feature.
Returned only if the enabled parameter value is 'False',
see Service Feature Limitations and Reasons [69]
Service Feature List
Feature Name
Description
BlockedMessageForwarding
Disallows to forward unencrypted fax and voicemail
messages and specifies 'Open With' on Android devices
CallForwarding
Feature that allows forwarding a call to the number
previously added to the extension forwarding list
CallPark
Feature that allows putting a call on hold at one telephone
set and continuing the conversation from any other
telephone set
Conferencing
Conference calling
DND
DnD (Do not Disturb) mode
EncryptionAtRest
Enables data protection on mobile devices and softphones
Fax
Sending and receiving Fax messages
FaxReceiving
Receiving Fax messages
FreeSoftPhoneLines
Free Digital Line availability
HDVoice
Feature enabling support of HD Voice compatible phones
HipaaCompliance
HIPAA Compliance of the account. The Health Insurance
Portability and Accountability Act is a standard for
protecting sensitive patient data, providing physical,
network and process security
Intercom
Intercom calling. A soft key on the caller's phone is
assigned for the Intercom function. By pressing it the
CONFIDENTIAL
68
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
Feature Name
Description
user makes a call which is received by the destination
number automatically via the loudspeaker. The callee is
also able to switch the microphone on. Available for User
extension types except FaxUser
InternationalCalling
Calling to international phone numbers
OnDemandCallRecording
Feature that allows recording a call on demand
Pager
Sending and receiving Pager messages
PagerReceiving
Receiving Pager messages
Paging
Intercom calling without callback possibility; used when
some information is to be delivered via the loud speaker
to one or several paging groups. Available for User
extension types except FaxUser
Reports
Viewing reports on call history
Presence
Ability of user extension to monitor other extensions'
presence
RingOut
Click-to-Call feature, allowing to make calls using the
web on any IP, analog or mobile phone. When you
initiate a call using RingOut, RingCentral will call your
current location number. Once you answer, RingCentral
dials a destination number for you. It is useful, when you
do not want to dial a number manually or want to make a
call with another phone using RingCentral number. Also
it may be used by a third party (secretary) to initiate a call
between you and another person
SalesForce
Integration with Salesforce
SingleExtensionUI
Indicates that current account can contain one and only
one extension
SMS
Sending and receiving SMS messages
SMSReceiving
Receiving SMS messages
VideoConferencing
Video conference calling
VoipCalling
IP telephony
Voicemail
Sending and receiving Voicemail messages
VoicemailToText
Transcription of voicemail audio record to text message
Service Feature Limitations and Reasons
Note
When retrieving service features for extension, the reasons for the limitations, if any, are
returned in response.
Limitation
AccountTypeLimitation
CONFIDENTIAL
Description
Principal account type
limitation. Feature is not
supported for account type
69
Example
Free Digital Line service feature is
turned off on UBP tier
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
Limitation
Description
ExtensionTypeLimitation Principal extension type
limitation. Feature is not
supported for particular
extension type (built-in
Product restriction)
Example
Announcement Only or Take Messages
Only extension types that cannot send
SMS, feature is disabled because of
immutable extension type limitation
and it is impossible to change the type
of this extension
AccountLimitation
Account limitation (service
SMS can be turned off for a particular
parameter setting at brand,
account/tier
tier or account level); can be
changed only by RC Customer
Support, or by upgrading to a
different tier
ExtensionLimitation
Extension limitation, requiring
chargeable action; can
be changed by Account
Administrator, requires
chargeable action (except tier
upgrades)
Is used for Free Digital Line service
feature, it is available only if there is
at least one paid digital line on this
extension
InsufficientPermissions Extension limitation, resolution International Calling is turned off using
is not chargeable; can
be changed by Account
Administrator without extra
charges
extension permissions
Regional Settings
Parameter
Type
Description
timezone
Timezone Info [134]
Extension timezone information
homeCountry
Country Info [126]
Extension country information
language
Collection of parameters
User interface language data
id
string
Internal identifier of a language
name
string
Official name of a language
localeCode
string
Localization code
greetingLanguage
Collection of parameters
Information on language used for
telephony greetings
id
string
Internal identifier of a greeting
language
name
string
Official name of a greeting language
localeCode
string
Localization code
formattingLocale
Collection of parameters
Formatting language preferences for
numbers, dates and currencies
CONFIDENTIAL
70
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
Parameter
Type
Description
id
string
Internal identifier of a formatting
language
name
string
Official name of a language
localeCode
string
Localization code
Extension Permissions
Parameter
Type
admin
Collection of parameters
enabled
'True' | 'False'
internationalCalling
Collection of parameters
enabled
'True' | 'False'
Description
Admin permission
International Calling permission
Greetings Info
Parameter
Type
Description
type
Introductory' | 'Voicemail'
| 'AudioWhileConnecting'
| 'CallScreening' |
'ConnectingMessage'
| 'Announcement'|
'MusicOnHold', etc.
Type of greeting
prompt
Collection of parameters
The prompt message
id
string
Internal identifier of the prompt
type
string
Type of the prompt
name
string
The specified name of the prompt
Example
Request example
GET /restapi/v1.0/account/11041661004/extension/~ HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFSi1KZFFBdkFFWldt
Response example
HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
{
"uri" : "https.../restapi/v1.0/account/11041661004/extension/11041661004",
"id" : 11041661004,
"extensionNumber" : "101",
"contact" : {
"firstName" : "John",
"lastName" : "Smith",
"company" : "MyCompany Inc.",
"email" : "[email protected]",
"businessPhone" : "+16557809302",
"businessAddress" : {
"street" : "13 Elm Street",
"city" : "Foster City",
CONFIDENTIAL
71
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
"state" : "CA",
"zip" : "94404",
"country" : "United States"
}
},
"name" : "John Smith",
"type" : "User",
"status" : "Enabled",
"serviceFeatures" : [ {
"featureName" : "SMS",
"enabled" : true
}, {
"featureName" : "SMSReceiving",
"enabled" : true
}, {
"featureName" : "Pager",
"enabled" : true
}, {
"featureName" : "PagerReceiving",
"enabled" : true
}, {
"featureName" : "Voicemail",
"enabled" : true
}, {
"featureName" : "Fax",
"enabled" : true
}, {
"featureName" : "FaxReceiving",
"enabled" : true
}, {
"featureName" : "DND",
"enabled" : true
}, {
"featureName" : "RingOut",
"enabled" : true
}, {
"featureName" : "InternationalCalling",
"enabled" : false,
"reason" : "AccountLimitation"
}, {
"featureName" : "Presence",
"enabled" : true
}, {
"featureName" : "VideoConferencing",
"enabled" : true
}, {
"featureName" : "SalesForce",
"enabled" : true
}, {
"featureName" : "Intercom",
"enabled" : true
}, {
"featureName" : "Paging",
"enabled" : true
}, {
"featureName" : "Conferencing",
"enabled" : true
}, {
"featureName" : "VoipCalling",
"enabled" : true
}, {
"featureName" : "FreeSoftPhoneLines",
"enabled" : false,
"reason" : "ExtensionLimitation"
}, {
"featureName" : "HipaaCompliance",
"enabled" : false,
"reason" : "AccountLimitation"
}, {
"featureName" : "CallPark",
"enabled" : true
}, {
"featureName" : "OnDemandCallRecording",
"enabled" : true
}, {
"featureName" : "Reports",
"enabled" : true
CONFIDENTIAL
72
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
}, {
"featureName" : "CallForwarding",
"enabled" : true
}, {
"featureName" : "DeveloperPortal",
"enabled" : false,
"reason" : "AccountLimitation"
}, {
"featureName" : "EncryptionAtRest",
"enabled" : false,
"reason" : "AccountLimitation"
}, {
"featureName" : "BlockedMessageForwarding",
"enabled" : false,
"reason" : "AccountLimitation"
}, {
"featureName" : "EmergencyCalling",
"enabled" : false,
"reason" : "AccountLimitation"
}, {
"featureName" : "HDVoice",
"enabled" : false,
"reason" : "AccountTypeLimitation"
}, {
"featureName" : "SingleExtensionUI",
"enabled" : false,
"reason" : "AccountLimitation"
}, {
"featureName" : "CallSupervision",
"enabled" : false,
"reason" : "AccountLimitation"
}, {
"featureName" : "VoicemailToText",
"enabled" : false,
"reason" : "AccountLimitation"
} ],
"regionalSettings" : {
"timezone" : {
"uri" : "https.../restapi/v1.0/dictionary/timezone/14",
"id" : "14",
"name" : "Europe/Moscow",
"description" : "Moscow, St. Petersburg, Volgograd"
},
"homeCountry" : {
"uri" : "https.../restapi/v1.0/dictionary/country/1",
"id" : "1",
"name" : "United States",
"isoCode" : "US",
"callingCode" : "1"
},
"language" : {
"id" : "1033",
"name" : "English (United States)",
"localeCode" : "en-US"
},
"greetingLanguage" : {
"id" : "1033",
"name" : "English (United States)",
"localeCode" : "en-US"
},
"formattingLocale" : {
"id" : "1033",
"name" : "English (United States)",
"localeCode" : "en-US"
}
},
"setupWizardState" : "Completed",
"permissions" : {
"admin" : {
"enabled" : true
},
"internationalCalling" : {
"enabled" : true
}
},
"greetings" : [ {
"type" : "MusicOnHold",
CONFIDENTIAL
73
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
"prompt"
"id" :
"type"
"name"
}
} ]
: {
"6",
: "music",
: "Acoustic"
}
Get Extension List
Since 1.0.0
Returns the list of extensions created for a particular account. All types of extensions are included in this
list.
Method/URI
GET /restapi/v1.0/account/{accountId}/extension
Usage Plan Group
Medium
Path Parameters
Parameter
accountId
Type
Description
integer
See the section called “Generic Path Parameters”
Query Parameters
Parameter
Type
Description
page, perPage
integer
Standard paging parameters, see the section
called “Common Query Parameters in Collection
Resources”
status
'Enabled' | 'Disabled'
| 'NotActivated'|
'Unassigned'
Extension current state. If 'Unassigned' is specified,
then extensions without extensionNumber are
returned. If not specified, then all extensions are
returned
Request Body
None
Response Body
Property
records
Type
Description
Collection [Extension
Info [66]]
Standard collection metadata, see the section called
“Common Collection Properties”
paging, navigation
CONFIDENTIAL
List of extension records
74
Rev.1.0.16.a.[79434afda268+]
Account and Extension Information
Example
Request example
GET /restapi/v1.0/account/~/extension HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFKV1MwMXz6J_ixC7_yYvon-KUZ31Lx-if4rw
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : ".../account/754224008/extension?page=1&perPage=100",
"records" : [ {
"uri" : ".../account/754224008/extension/754233008",
"id" : 754233008,
"extensionNumber" : "109",
"name": "Sara Lin"
"type": "User"
"contact" {
"firstName" : "Sara",
"lastName" : "Lin",
"company" : "MyCompany Inc.",
"email": "[email protected]" }
"status": "Enabled"
},
{
"uri" : ".../account/754224008/extension/754235008",
"id" : 754235008,
"extensionNumber" : "301",
"name" : "Announcement Extension",
"type" : "Announcement"
"contact" {
"company" : "MyCompany Inc.",
"email": "[email protected]"
"businessAddress": {
"country": "China"
"city": "Beijing" }
"status": "Enabled"
},
{
"uri" : ".../account/754224008/extension/754234008",
"id" : 754234008,
"extensionNumber" : "201",
"name" : "Department Extension",
"type" : "Department"
"contact"{
"company" : "MyCompany Inc.",
"email": "[email protected]"
"businessAddress": {
"country": "Canada"
"city": "Montreal" }
"status": "Enabled"
},
{
"uri" : ".../account/754224008/extension/754236008",
"id" : 754236008,
"extensionNumber" : "401",
"name" : "Voicemail Extension",
"type" : "Voicemail"
"contact"{
"company" : "MyCompany Inc.",
"email": "[email protected]"
"businessAddress": {
"country": "USA"
"city": "Washington" }
"status": "Enabled"
}
}
CONFIDENTIAL
75
Rev.1.0.16.a.[79434afda268+]
Chapter 14. Call Log
Get Call Log Record
Since 1.0.3 (Release 5.11)
Returns individual call log record by callRecordId(s).
Method/URI
GET /restapi/v1.0/account/{accountId}/call-log/{callRecordId(s)}
GET
/restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log/
{callRecordId(s)}
Batch request is supported, see Batch Requests for details.
Usage Plan Group
Heavy
Path Parameters
Parameter
Type
Batch
support
Description
accountId,
extensionId
integer
no
See the section called “Generic Path Parameters”
callRecordId
integer
yes
Internal identifier of a call log record
Request Body
None
Response Body
Call Log Record
Parameter
Type
Description
Standard resource properties ID and canonical URI,
see the section called “Resource Identification
Properties”
id, uri
sessionId
string
Internal identifier of a call session
from
Caller Info
Caller information
to
Caller Info
Callee information
type
'Voice' | 'Fax'
Call type
direction
'Inbound' | 'Outbound' Call direction
action
string
CONFIDENTIAL
Action description of the call operation. See the
section called “Commonly Used Call Actions and
Results”
76
Rev.1.0.16.a.[79434afda268+]
Call Log
Parameter
Type
Description
result
string
Status description of the call operation. See the section
called “Commonly Used Call Actions and Results”
startTime
datetime
Call start time
duration
integer
Call duration in seconds
recording
Recording
Info [78]
Call recording data. Returned if the call is recorded
Call Log Detailed Record
Parameter
Type
Description
Standard resource properties ID and canonical
URI, see the section called “Resource
Identification Properties”
id, uri
sessionId
string
Internal identifier of a call session
from
Caller Info
Caller information
to
Caller Info
Callee information
type
'Voice' | 'Fax'
Call type
direction
'Inbound' | 'Outbound'
Call direction
action
string
Action description of the call operation. See the
section called “Commonly Used Call Actions and
Results”
result
string
Status description of the call operation. See the
section called “Commonly Used Call Actions and
Results”
startTime
datetime
Call start time
duration
integer
Call duration in seconds
transport
'PSTN'/ 'VoIP'
Call transport
message
null
Message attachment
recording
Recording Info [78]
Call recording data. Returned if the call is
recorded
billing
'costIncluded' |
'costPurchased'
Information on costs
legs
Collection of parameters
Leg description
startTime
datetime
Call start time
duration
integer
Call duration in seconds
type
'Voice' | 'Fax'
Call type
direction
'Inbound' | 'Outbound'
Call direction
action
string
Action description of the call operation. See the
section called “Commonly Used Call Actions and
Results”
CONFIDENTIAL
77
Rev.1.0.16.a.[79434afda268+]
Call Log
Parameter
Type
Description
result
string
Status description of the call operation. See the
section called “Commonly Used Call Actions and
Results”
from
Caller Info
Caller information
to
Caller Info
Callee information
transport
'PSTN'/ 'VoIP'
Call transport
message
null
Message attachment
recording
Recording Info [78]
Call recording data. Returned if the call is
recorded
billing
'costIncluded' |
'costPurchased'
Information on costs
legType
string
Leg type
Recording Info
Parameter
Type
Description
id
integer
Internal identifier of the call recording
uri
string
Link to the call recording resource
contentType
string
Call recording file format. Supported format is audio/
x-wav
duration
integer
Recorded call duration
Example
Request example
GET https.../restapi/v1.0/account/10979280004/extension/10979280004/call-log/AYRh1VBgc6C8eks
HTTP/1.1
Authorization: Bearer
U0pDMDFQMDFQQVMwMnxBQUJFU3VOMlp2bjZFSUNPU3BWV2wyZmZ4YkVPSFNDSlVFT3FaRmZTdFdraUx
Accept: application/json
Response example
HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json
Content-Length: 723
{
"uri" : "https.../restapi/v1.0/account/10979280004/extension/10979280004/call-log/
AYRh1VBgc6C8eks",
"id" : "AYRh1VBgc6C8eks",
"sessionId" : "18340829004",
"startTime" : "2015-01-19T13:58:19.000Z",
"duration" : 60,
"type" : "Voice",
"direction" : "Inbound",
"action" : "Phone Call",
"result" : "Accepted",
"to" : {
"phoneNumber" : "18773220048",
"name" : "John Smith"
},
"from" : {
CONFIDENTIAL
78
Rev.1.0.16.a.[79434afda268+]
Call Log
"phoneNumber" : "18558570060",
"name" : "Jane Smith"
},
"recording" : {
"uri" : "https.../restapi/v1.0/account/10979280004/extension/10979280004/
recording/59497406004/content",
"id" : 59497406004,
"contentType" : "audio/x-wav",
"duration" : 30
}
}
Get Call Log Records by Filter
Since 1.0.3 (Release 5.11)
Returns call log records filtered by the specified parameters.
Method/URI
Account Call-Log
GET /restapi/v1.0/account/{accountId}/call-log
Extension Call-Log
GET /restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log
Usage Plan Group
Heavy
Path Parameters
Parameter
Type
Description
accountId, extensionId integer
See the section called “Generic Path
Parameters”
Query Parameters
Parameter
Type
extensionNumber string
Description
Extension number of a user. If specified, returns call log for a
particular extension only. Cannot be specified together with the
phoneNumber filter
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 accepted
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
accepted
CONFIDENTIAL
79
Rev.1.0.16.a.[79434afda268+]
Call Log
Parameter
Type
Description
view
'Simple' |
'Detailed'
The default value is 'Simple' for both account and extension call
log
withRecording
'True' | 'False' 'True' if only recorded calls have to be returned
dateTo
datetime
Specifies the ending timestamp for result records. Default: current
time
dateFrom
datetime
The start timestamp for result records. Default value is equal to
dateTo minus 1 week
page, perPage
integer
Standard paging parameters, see the section called “Common
Query Parameters in Collection Resources”
Request Body
None
Response Body
Property
records
Type
Description
Collection [Call Log
Record [76]]; or
collection [Call Log
Detailed Record [77]]
List of call log records depending on the view
parameter value. If the 'Simple' value is specified then
collection of Call Log Record [76] is returned. If
the 'Detailed' value is specified then collection of Call
Log Detailed Record [77] is returned
Standard collection metadata, see the section called
“Common Collection Properties”, except for properties
totalPages and totalElements, which are not
returned for this request. The total number of elements
per page is not specified, and the page enumeration is
absent
paging,
navigation
Example 1
If the view parameter value is 'Simple'
Request example
GET /restapi/v1.0/account/~/extension/~/call-log?
direction=Inbound&dateFrom=2012-09-17T12:51:00.000Z HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFKV1MwMXz6J_ixC7_yYvon-KUZ31Lx-if4rw
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : ".../account/754224008/extension/754224008/call-log?
direction=Inbound&dateFrom=2012-09-17T12:51:00.000Z&page=1&perPage=100",
"records" : [ {
"uri" : ".../account/754224008/extension/754224008/call-log/Pz4OE2Y_VJRPEg",
"id" : "Pz4OE2Y_VJRPEg",
"sessionId" : "403389461094",
CONFIDENTIAL
80
Rev.1.0.16.a.[79434afda268+]
Call Log
"startTime" : "2012-09-17T12:51:22.000Z",
"duration" : 48,
"type" : "Voice",
"direction" : "Inbound",
"action" : "Phone Call",
"result" : "Voicemail",
"to" : {
"phoneNumber" : "12056770024",
"location" : "Chelsea, AL"
},
"from" : {
"phoneNumber" : "18559100010"
}
} ],
"paging" : {
"page" : 1,
"perPage" : 100,
"pageStart" : 0,
"pageEnd" : 0
},
"navigation" : {
"firstPage" : {
"uri" : ".../account/754224008/extension/754224008/call-log?
direction=Inbound&dateFrom=2012-09-17T16:51:00.000Z&page=1&perPage=100"
}
}
}
Example 2
If the view parameter value is 'Detailed'
Request example
GET /restapi/v1.0/account/400686290004/extension/400686290004/call-log/detail?perPage=2 HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMlhvUFI5dmhYVzVs
Response example
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3178
{
"uri" : "https.../restapi/v1.0/account/400686290004/extension/400686290004/call-log?
dateFrom=2014-08-12T00:00:00.000Z&page=1&perPage=2",
"records" : [ {
"uri" : "https.../restapi/v1.0/account/400686290004/extension/400686290004/call-log/IVNVUw5GHgnXlE",
"id" : "IV-NVUw5GHgnXlE",
"sessionId" : "403457840004",
"startTime" : "2014-08-19T11:15:05.000Z",
"duration" : 4,
"type" : "Voice",
"direction" : "Inbound",
"action" : "Phone Call",
"result" : "Accepted",
"to" : {
"phoneNumber" : "18559700003",
"name" : "John Smith"
},
"from" : {
"phoneNumber" : "16504445567",
"name" : "Jane Smith",
"location" : "Palo Alto, CA"
},
"transport" : "PSTN",
"message" : "null",
"recording" : "null",
"billing" : { },
"legs" : [ {
"startTime" : "2014-08-19T11:15:05.000Z",
CONFIDENTIAL
81
Rev.1.0.16.a.[79434afda268+]
Call Log
"duration" : 4,
"type" : "Voice",
"direction" : "Inbound",
"action" : "Phone Call",
"result" : "Accepted",
"to" : {
"phoneNumber" : "18559700003",
"name" : "John Smith"
},
"from" : {
"phoneNumber" : "16504445567",
"name" : "Jane Smith",
"location" : "Palo Alto, CA"
},
"transport" : "PSTN",
"message" : "null",
"recording" : "null",
"billing" : { },
"legType" : "ACCEPT"
} ]
}, {
"uri" : "https.../restapi/v1.0/account/400686290004/extension/400686290004/call-log/IVNR2uCZNDDXk4",
"id" : "IV-NR2uCZNDDXk4",
"sessionId" : "403457830004",
"startTime" : "2014-08-19T11:15:02.000Z",
"duration" : 7,
"type" : "Voice",
"direction" : "Inbound",
"action" : "Phone Call",
"result" : "Accepted",
"to" : {
"phoneNumber" : "18559700003",
"name" : "John Smith"
},
"from" : {
"phoneNumber" : "16504445566",
"name" : "Jerry Smith",
"location" : "Palo Alto, CA"
},
"transport" : "PSTN",
"message" : "null",
"recording" : "null",
"billing" : { },
"legs" : [ {
"startTime" : "2014-08-19T11:15:02.000Z",
"duration" : 7,
"type" : "Voice",
"direction" : "Inbound",
"action" : "Phone Call",
"result" : "Accepted",
"to" : {
"phoneNumber" : "18559700003",
"name" : "John Smith"
},
"from" : {
"phoneNumber" : "16504445566",
"name" : "Jerry Smith",
"location" : "Palo Alto, CA"
},
"transport" : "PSTN",
"message" : "null",
"recording" : "null",
"billing" : { },
"legType" : "ACCEPT"
} ]
} ],
"paging" : {
"page" : 1,
"perPage" : 2,
"pageStart" : 0,
"pageEnd" : 1
},
"navigation" : {
"nextPage" : {
"uri" : "https.../restapi/v1.0/account/400686290004/extension/400686290004/call-log?
dateFrom=2014-08-12T00:00:00.000Z&page=2&perPage=2"
CONFIDENTIAL
82
Rev.1.0.16.a.[79434afda268+]
Call Log
},
"firstPage" : {
"uri" : "https.../restapi/v1.0/account/400686290004/extension/400686290004/call-log?
dateFrom=2014-08-12T00:00:00.000Z&page=1&perPage=2"
}
}
}
Get Active Calls
Since 1.0.13 (Release 6.5)
Returns records of all calls that are in progress, ordered by start time in descending order.
Method/URI
Account Call-Log
GET /restapi/v1.0/account/{accountId}/active-calls
Extension Call-Log
GET /restapi/v1.0/account/{accountId}/extension/{extensionId}/active-calls
Usage Plan Group
Heavy
Required Permissions
Permission
Description
Viewing user call logs
ReadCallLog
Path Parameters
Parameter
Type
Description
accountId, extensionId integer
See the section called “Generic Path
Parameters”
Query Parameters
Parameter
Type
Description
direction
'Inbound' |
'Outbound'
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
accepted
page, perPage
integer
CONFIDENTIAL
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 accepted
Standard paging parameters, see the section called “Common
Query Parameters in Collection Resources”
83
Rev.1.0.16.a.[79434afda268+]
Call Log
Request Body
None
Response Body
Property
records
Type
Collection
[Call Log
Record [76]]
paging,
navigation
Description
List of call log records
Standard collection metadata, see the section called
“Common Collection Properties”, except for properties
totalPages and totalElements, which are not returned
for this request. The total number of elements per page is
not specified, and the page enumeration is absent
Example
Request example
GET /restapi/v1.0/account/400618687004/extension/400618687004/active-calls HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMlhvUFI5dmhYVzV
Response example
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 941
{
"uri" : "https.../restapi/v1.0/account/400618687004/extension/400618687004/active-calls?
page=1&perPage=100",
"records" : [ {
"uri" : "https.../restapi/v1.0/account/400618687004/extension/400618687004/call-log/
IV5fj9D8vHjs8fw",
"id" : "IV5fj9D8vHjs8fw",
"sessionId" : "403402173004",
"startTime" : "2014-08-15T15:16:12.000Z",
"duration" : 0,
"type" : "Voice",
"direction" : "Outbound",
"action" : "RingOut Web",
"result" : "Call connected",
"to" : {
"phoneNumber" : "18556620006",
"name" : "John Smith"
},
"from" : {
"name" : "Jane Smith"
}
} ],
"paging" : {
"page" : 1,
"perPage" : 100,
"pageStart" : 0,
"pageEnd" : 0
},
"navigation" : {
"firstPage" : {
"uri" : "https.../restapi/v1.0/account/400618687004/extension/400618687004/active-calls?
page=1&perPage=100"
}
CONFIDENTIAL
84
Rev.1.0.16.a.[79434afda268+]
Call Log
}
}
CONFIDENTIAL
85
Rev.1.0.16.a.[79434afda268+]
Chapter 15. Messaging
RingCentral Messaging API allows to work with different types of messages processed by RingCentral
phone system.
Get Message
Since 1.0.2
Returns individual message record by the given messageId.
Method/URI
GET
/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/
{messageId(s)}
Batch request is supported, see Batch Requests for details.
Usage Plan Group
Light
Path Parameters
Parameter
Type
Batch
support
Description
accountId,
extensionId
integer
no
See the section called “Generic Path
Parameters”
messageId
integer
yes
Internal identifier of a message
Request Body
None
Response Body
Message Info
Parameter
Type
Description
Standard resource properties ID and
canonical URI, see the section called
“Resource Identification Properties”
id, uri
type
'Fax' | 'SMS' | 'VoiceMail' |
'Pager' | 'Text'
Message type
direction
'Inbound' | 'Outbound'
Message direction. Note that for some
message types not all directions are allowed.
For example voicemail messages can be only
inbound
from
Caller Info
Sender information
CONFIDENTIAL
86
Rev.1.0.16.a.[79434afda268+]
Messaging
Parameter
Type
Description
to
Caller Info
Recipient information
creationTime
datetime
Message creation timestamp
lastModifiedTime
datetime
The timestamp when the message was
modified on server
messageStatus
'Queued' | 'Sent' | 'Delivered'
| 'DeliveryFailed' |
'SendingFailed' | 'Received'
Message status. Different message types
may have different allowed status values
(see Chapter 6, Working with Messages for
details)
readStatus
'Read' | 'Unread'
Message read status
availability
'Alive' | 'Deleted' | 'Purged'
Message availability status. Message in
'Deleted' state is still preserved along 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
vmTranscriptionStatus'NotAvailable' | 'InProgress'
Voicemail only. Status of voicemail to text
| 'TimedOut' | 'Completed' |
transcription. If VoicemailToText feature is
'CompletedPartially' | 'Failed' not activated for account, the 'NotAvailable'
value is returned
attachments
Collection of [Message
Attachment Info [87]]
The list of message attachments
conversationId
integer
SMS and Pager only. Identifier of the
conversation the message belongs to
deliveryErrorCode
string
SMS only. Delivery error code returned by
gateway
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).
priority
'Normal' | 'High'
Message priority
smsDeliveryTime
datetime
SMS only. The timestamp when outbound
SMS was delivered to recipient's handset. 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
pgToDepartment
boolean
Pager only. True if at least one of the
message recipients is Department extension
Message Attachment Info
CONFIDENTIAL
87
Rev.1.0.16.a.[79434afda268+]
Messaging
Parameter
Type
Description
Standard resource properties ID and
canonical URI. In this case URI points to
media for a particular attachment
id, uri
type
'AutoRecording' |
'AutoTranscription |
'Text' | 'SourceDocument'|
'RenderedDocument'
Attachment type, see also Attachment Type
Info [88]
contentType
string
MIME type for a given attachment, for
instance 'audio/wav'
vmDuration
integer
Voicemail only Duration of the voicemail in
seconds
Attachment Type Info
Attachment Type
Message
Type
Content Type
Description
AutoRecording
Voicemail audio
Auto recorded audio file
AutoTranscription
Voicemail text
Auto transcribed text file
RenderedDocument
Fax
image/tiff;
application/
pdf
The file rendered from original format to
TIFF or PDF; delivered to the recipient
SourceDocument
Fax/Text
Any supported
file format
The original file in any format; attached by
the sender
Text
SMS/
Pager
text/plain
Text format file
Example 1
Get Voicemail message
Request example
GET /restapi/v1.0/account/14833636004/extension/14833636004/message-store/82063400004 HTTP/1.1
Accept-Encoding: gzip,deflate
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/messagestore/82063400004",
"id" : 82063400004,
"to" : [ {
"name" : "John Smith"
} ],
"from" : {
"phoneNumber" : "+18664320079",
CONFIDENTIAL
88
Rev.1.0.16.a.[79434afda268+]
Messaging
"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/messagestore/82063400004/content/82063400004",
"type" : "AudioRecording",
"contentType" : "audio/x-wav",
"vmDuration" : 30
}, {
"id" : 1897320004,
"uri" : "https.../restapi/v1.0/account/14833636004/extension/14833636004/messagestore/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
Authorization: Bearer
U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMlhvUFI5dmhYVzVsb1hBV21Ka01xV3NDREFvZ2ZoT2J
Accept: application/json
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/account/400928048004/extension/400928050004/messagestore/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/messagestore/401081345004/content/401081345004",
"type" : "Text",
"contentType" : "text/plain"
} ],
"direction" : "Outbound",
"availability" : "Alive",
"subject" : "Sample message",
CONFIDENTIAL
89
Rev.1.0.16.a.[79434afda268+]
Messaging
"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
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUJFU3VOMlp2bjZFSzBYeG9vaVc1UXpWR0k0VU13Yk4tbXFaRmZ
Accept: application/json
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/messagestore/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/messagestore/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 Fax message
Request example
GET /restapi/v1.0/account/12569864004/extension/12569864004/message-store/60335038004 HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUJFU3VOMlp2bjZFSzBYeG9vaVc1UXpDbGpvZTZrcFlj
Response example
CONFIDENTIAL
90
Rev.1.0.16.a.[79434afda268+]
Messaging
HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 766
{
"uri" : "https.../restapi/v1.0/account/12569864004/extension/12569864004/messagestore/60335038004",
"id" : 60335038004,
"to" : [ {
"phoneNumber" : "+18005630003"
} ],
"type" : "Fax",
"creationTime" : "2015-02-19T14:15:51.000Z",
"readStatus" : "Unread",
"priority" : "Normal",
"attachments" : [ {
"id" : 60335038004,
"uri" : "https.../restapi/v1.0/account/12569864004/extension/12569864004/messagestore/60335038004/content/60335038004",
"type" : "RenderedDocument",
"contentType" : "image/tiff"
} ],
"direction" : "Outbound",
"availability" : "Alive",
"messageStatus" : "Sent",
"faxResolution" : "High",
"faxPageCount" : 2,
"lastModifiedTime" : "2015-02-19T14:18:05.042Z"
}
Get Message List
Since 1.0.2
Returns the list of messages from an extension mailbox.
Method/URI
GET /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store
Usage Plan Group
Light
Path Parameters
Parameter
accountId,
extensionId
Type
Description
integer
See the section called “Generic Path Parameters”
Query Parameters
Parameter
Type
Description
phoneNumber
string
The phone number. If specified, messages are
returned for this particular phone number only
direction
'Inbound' | 'Outbound'
The direction for the resulting messages. If not
specified, both inbound and outbound messages are
returned. Multiple values are accepted
CONFIDENTIAL
91
Rev.1.0.16.a.[79434afda268+]
Messaging
Parameter
Type
Description
messageType
'Fax' | 'SMS' | 'VoiceMail' The type of the resulting messages. If not specified,
| 'Pager' | 'Text'
all messages without message type filtering are
returned. Multiple values are accepted
readStatus
'Read' | 'Unread'
The read status for the resulting messages. Multiple
values are accepted
dateTo
datetime
Specifies the ending timestamp for the resulting
messages. Default: current time
dateFrom
datetime
The start timestamp for the resulting messages.
Default value is equal to dateFrom minus 1 week
conversationId
integer
Specifies the conversation identifier for the
resulting messages
availability
'Alive' | 'Deleted' |
'Purged'
Specifies the availability status for the resulting
messages. Default value is 'Alive'. Multiple values
are accepted
page, perPage
integer
Standard paging parameters, see the section
called “Common Query Parameters in Collection
Resources”
Request Body
None
Response Body
Property
records
Type
Description
Collection [Message
Info [86]]
List of records with message details
Standard collection metadata, see the section called
“Common Collection Properties”
paging,
navigation
Example
Request example
GET /restapi/v1.0/account/~/extension/~/message-store HTTP/1.1
Accept: application/json
Authorization: Bearer U1BCMDFUMDRKV1MwMXwVVOaPwPu88hVU5oR0u-FQFVTmhA
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : ".../account/1346632010/extension/1346632010/message-store?
availability=Alive&page=1&perPage=100",
"records" : [ {
"uri" : ".../account/1346632010/extension/1346632010/message-store/315433012010",
"id" : 315433012010,
CONFIDENTIAL
92
Rev.1.0.16.a.[79434afda268+]
Messaging
"to" : [ {
"phoneNumber" : "18559100010"
} ],
"from" : {
"phoneNumber" : "16509101086"
},
"type" : "SMS",
"creationTime" : "2012-09-13T14:46:37.000Z",
"readStatus" : "Unread",
"priority" : "Normal",
"attachments" : [ {
"id" : 1,
"uri" : ".../account/1346632010/extension/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-13T14:46:37.000Z"
}, {
"uri" : ".../account/1346632010/extension/1346632010/message-store/315432888010",
"id" : 315432888010,
"to" : [ {
"phoneNumber" : "18559100010"
} ],
"from" : {
"phoneNumber" : "16509101086"
},
"type" : "VoiceMail",
"creationTime" : "2012-09-13T14:44:27.000Z",
"readStatus" : "Unread",
"priority" : "Normal",
"attachments" : [ {
"id" : 1,
"uri" : ".../account/1346632010/extension/1346632010/message-store/315432888010/
content/1",
"type": "AudioRecording",
"contentType" : "audio/x-wav",
"vmDuration" : 25
} ],
"direction" : "Inbound",
"availability" : "Alive",
"messageStatus" : "Received",
"lastModifiedTime" : "2012-09-13T14:44:27.000Z",
"vmTranscriptionStatus" : "NotAvailable"
}],
"paging":
{
"page": 1,
"totalPages": 1,
"perPage": 100,
"totalElements": 2,
"pageStart": 0,
"pageEnd": 1
},
"navigation":
{
"firstPage": {"uri": ".../account/1346632010/extension/1346632010/message-store?
availability=Alive&page=1&perPage=100"},
"lastPage": {"uri": ".../account/1346632010/extension/1346632010/message-store?
availability=Alive&page=1&perPage=100"}
}
}
Update Message
Since 1.0.2
Updates an individual message or several messages. Currently, updating only the message read status is
supported.
CONFIDENTIAL
93
Rev.1.0.16.a.[79434afda268+]
Messaging
Note
If the status of the updating message is 'Purged', then 404 Not Found error code is
returned. In case of incorrect request 400 Bad Request error code is returned.
Method/URI
PUT
/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/
{messageId(s)}
Batch request is supported, see Batch Requests for details.
Usage Plan Group
Medium
Path Parameters
Parameter
Type
Batch
support
Description
accountId,
extensionId
integer
no
See the section called “Generic Path Parameters”
messageId
integer
yes
Internal identifier of a message
Request Body
Parameter
readStatus
Type
Description
'Read' | 'Unread'
Read status of a message to be changed. Multiple
values are accepted
Response Body
Message Info [86] with the updated read status.
Example
Request example
PUT /restapi/v1.0/account/1346632010/extension/1346632010/message-store/315433012010 HTTP/1.1
Authorization: Bearer U1BCMDFUMDRKV1MwMXwVVOaPwPu88hVU5oR0u-FQFVTmhA
Content-Type: application/json
{"readStatus": "Read"}
Response example
HTTP/1.1 200 OK
Content-Type: application/json
CONFIDENTIAL
94
Rev.1.0.16.a.[79434afda268+]
Messaging
{
"uri" : ".../account/1346632010/extension/1346632010/message-store/1346632010/messagestore/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/messagestore/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"
}
Delete Message
Since 1.0.2
Deletes an individual message or several messages by the given message IDs.
Method/URI
DELETE
/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/
{messageId(s)}
Batch request is supported, see Batch Requests for details.
Usage Plan Group
Medium
Path Parameters
Parameter
Type
Batch
support
Description
accountId,
extensionId
integer
no
See the section called “Generic Path Parameters”
messageId
integer
yes
Internal identifier of a message
Request Body
None
CONFIDENTIAL
95
Rev.1.0.16.a.[79434afda268+]
Messaging
Response Body
None
Example
Request example
DELETE /restapi/v1.0/account/1346632010/extension/1346632010/message-store/315433012010 HTTP/1.1
Authorization: Bearer U1BCMDFUMDRKV1MwMXwVVOaPwPu88hVU5oR0u-FQFVTmhA
Response example
HTTP/1.1 204 No Content
Delete Messages in a Thread
Since 1.0.2
Deletes the entire message thread by the conversationId assigned to this message thread. It is possible to
delete only one thread by one request, batch request is not supported.
Method/URI
DELETE
/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/
{conversationId}
Usage Plan Group
Medium
Path Parameters
Parameter
Type
Description
accountId,
extensionId
string
See the section called “Generic Path Parameters”
conversationId
integer
Internal identifier of a message
Request Body
None
Response Body
None
CONFIDENTIAL
96
Rev.1.0.16.a.[79434afda268+]
Messaging
Example
Request example
DELETE /restapi/v1.0/account/1346632010/extension/1346632010/message-store/141549019326272744
HTTP/1.1
Authorization: Bearer U1BCMDFUMDRKV1MwMXwVVOaPwPu88hVU5oR0u-FQFVTmhA
Response example
HTTP/1.1 204 No Content
Get Message Attachment Data
Since 1.0.4 (Release 5.13)
Returns particular message attachment data as a media stream.
Method/URI
GET
/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/
{messageId}/content/{attachmentId}
Usage Plan Group
Medium
Path Parameters
Parameter
Type
Description
accountId,
extensionId
integer
See the section called “Generic Path Parameters”
messageId
integer
Internal identifier of a message
attachmentId
integer
Internal identifier of a message attachment
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
CONFIDENTIAL
97
Rev.1.0.16.a.[79434afda268+]
Messaging
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...>
Create SMS Message
Since 1.0.2
Creates and sends new SMS message.
Method/URI
POST /restapi/v1.0/account/{accountId}/extension/{extensionId}/sms
Usage Plan Group
Medium
Path Parameters
Parameter
accountId,
extensionId
Type
Description
integer
See the section called “Generic Path Parameters”
Request Body
Parameter
Type
Description
from
Caller Info
Sender of SMS message. The phoneNumber property
must be filled to correspond to one of the account
phone numbers which is allowed for given extension
to send SMS from
to
Caller Info
Receiver of SMS message. phoneNumber property
must be filled
CONFIDENTIAL
98
Rev.1.0.16.a.[79434afda268+]
Messaging
Parameter
text
Type
Description
string
Text of SMS message (max 160 characters)
Response Body
Message Info [86] of the newly created and sent message.
Example
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"
}
Create Fax Message
Since 1.0.2
Creates and sends new fax message.
CONFIDENTIAL
99
Rev.1.0.16.a.[79434afda268+]
Messaging
Method/URI
POST /restapi/v1.0/account/{accountId}/extension/{extensionId}/fax
Usage Plan Group
Heavy
Path Parameters
Parameter
accountId,
extensionId
Type
Description
integer
See the section called “Generic Path Parameters”
Request Body
Parameter
Type
Description
to
Caller Info
Recipient information. Phone number property is
mandatory
resolution
'High' | 'Low'
Fax resolution
sendTime
datetime
Optional. Timestamp to send fax at. If not specified
(current or the past), the fax is sent immediately
coverIndex
integer (0-16)
Optional. Cover page index. If not specified, the
default cover page which is configured in "Outbound
Fax Settings" is attached. See also "Available Cover
Pages" table below
coverPageText
string
Optional. Cover page text, entered by the fax sender
and printed on the cover page. Maximum length is
limited to 1024 symbols
Available Cover Pages
Cover Index Value
Description
0
"None", the cover page is not attached
1
"Ancient" cover page template is attached
2
"Birthday" cover page template is attached
3
"Blank" cover page template is attached
4
"Clasmod" cover page template is attached
5
"Classic" cover page template is attached
6
"Confidential" cover page template is attached
7
"Contempo" cover page template is attached
8
"Elegant" cover page template is attached
9
"Express" cover page template is attached
10
"Formal" cover page template is attached
CONFIDENTIAL
100
Rev.1.0.16.a.[79434afda268+]
Messaging
Cover Index Value
Description
11
"Jazzy" cover page template is attached
12
"Modern" cover page template is attached
13
"Urgent" cover page template is attached
Response Body
Message Info [86] of the created fax message with the filled fax-specific fields.
Example
Request example 1: Passing attachments in a fax by specifying Content-Type of fax attachments as MIME
type (see Fax Attachments. MIME Types for details)
POST /restapi/v1.0/account/~/extension/~/fax HTTP/1.1
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888
Content-Length: ACTUAL_CONTENT_LENGTH_HERE
--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: text/plain
Hello, World!
--Boundary_1_14413901_1361871080888--
Request example 2: Passing attachments in a fax by specifying Content-Type of fax attachments as MIME
type (see Fax Attachments. MIME Types for details) and a filename in Content-Disposition header.
POST /restapi/v1.0/account/~/extension/~/fax HTTP/1.1
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888
Content-Length: ACTUAL_CONTENT_LENGTH_HERE
--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: text/plain
Content-Disposition: attachment; filename="fax.txt"
Hello, World!
--Boundary_1_14413901_1361871080888--
Request example 3: Passing attachments in a fax by specifying Content-Type "application/octet-stream"
and a filename in Content-Disposition header.
POST /restapi/v1.0/account/~/extension/~/fax HTTP/1.1
Content-Type: multipart/mixed; boundary=Boundary_1_14413901_1361871080888
CONFIDENTIAL
101
Rev.1.0.16.a.[79434afda268+]
Messaging
Content-Length: ACTUAL_CONTENT_LENGTH_HERE
--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: application/octet-stream
Content-Disposition: attachment; filename="fax.txt"
Hello, World!
--Boundary_1_14413901_1361871080888--
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri": ".../restapi/v1.0/account/284818008/extension/284822008/message-store/3291869008",
"id": 3291869008,
"to": [{"phoneNumber": "18005630003"}],
"type": "Fax",
"creationTime": "2013-02-26T08:38:45.000Z",
"readStatus": "Unread",
"priority": "Normal",
"attachments": [
{
"id": 1,
"uri": ".../restapi/v1.0/account/284818008/extension/284822008/message-store/3291869008/
content/1",
"contentType": "image/tiff"
}],
"direction": "Outbound",
"availability": "Alive",
"messageStatus": "Queued",
"faxResolution": "High",
"faxPageCount": 0,
"lastModifiedTime": "2013-02-26T08:38:45.000Z"
}
Create Pager Message
Since 1.0.2
Creates and sends new pager message.
Method/URI
POST /restapi/v1.0/account/{accountId}/extension/{extensionId}/company-pager
Usage Plan Group
Medium
Path Parameters
Parameter
accountId,
extensionId
CONFIDENTIAL
Type
Description
integer
See the section called “Generic Path Parameters”
102
Rev.1.0.16.a.[79434afda268+]
Messaging
Request Body
Parameter
Type
Description
from
Caller Info
Sender of pager message. The extensionNumber
property must be filled
replyOn
integer
Optional. ID of a message this message replies to
text
string
Text of pager message
to
Caller Info
Receiver of pager message. The extensionNumber
property must be filled
Response Body
Message Info [86] of the created pager message.
Error Codes
Logical Error Code
HTTP Status Code
Possible Reason
FeatureNotAvailable
403 Forbidden
This extension/account does not support pager
messages
InvalidContent
400 Bad Request
The content is invalid. For example, the pager
message exceeds the length limit (160 symbols)
InvalidParameter
400 Bad Request
One or many request parameters are invalid, refer
to parameterName field in response
OldThreadReply
403 Forbidden
Reply is forbidden for old message threads
OutOfThreadReply
403 Forbidden
Reply is denied for user, who is no longer a
thread participant
RejectedByRecipient
400 Bad Request
This extension/account does not support pager
messages, or it is Disabled.
Example
Request example
POST /restapi/v1.0/account/~/extension/~/company-pager HTTP/1.1
Accept: application/json
Authorization: Bearer U1BCMDFUMDRKV1MwMXzidVlSWLyuMeJ1WV-VfMBf4nVZWg
Content-Type: application/json
{
"to": [{"extensionNumber": "102"},
{"extensionNumber": "103"}
],
"from": {"extensionNumber": "101"},
"text": "Hello!"
}
Response example
HTTP/1.1 200 OK
CONFIDENTIAL
103
Rev.1.0.16.a.[79434afda268+]
Messaging
Content-Type: application/json
{
"uri" : ".../account/1346632010/extension/1346632010/message-store/315458412010",
"id" : 315458412010,
"to" : [
{"extensionNumber" : "102"},
{"extensionNumber" : "103"} ],
"from" : {
"extensionNumber" : "101"
},
"type" : "Pager",
"creationTime" : "2012-09-13T16:03:04.000Z",
"readStatus" : "Unread",
"priority" : "Normal",
"attachments" : [ {
"id" : 1,
"uri" : ".../account/1346632010/extension/1346632010/message-store/315458412010/
content/1",
"contentType" : "text/plain"
} ],
"direction" : "Outbound",
"availability" : "Alive",
"subject" : "Hello!",
"messageStatus" : "Sent",
"conversationId" : 315458412010,
"lastModifiedTime" : "2012-09-13T16:03:04.000Z"
}
CONFIDENTIAL
104
Rev.1.0.16.a.[79434afda268+]
Chapter 16. 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.
Make RingOut Call
Since 1.0.7 (Release 5.16)
Makes a 2-leg RingOut call.
Method/URI
POST /restapi/v1.0/account/{accountId}/extension/{extensionId}/ringout
Usage Plan Group
Heavy
Path Parameters
Parameter
Type
integer
accountId,
extensionId
Description
See the section called “Generic Path Parameters”
Request Body
Parameter
Type
Description
from
Caller Info (only phoneNumber
element is supported)
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. Required
to
Caller Info (only phoneNumber
element is supported)
Phone number of the called party. This number
corresponds to the 2nd leg of the RingOut call.
Required
callerId
Caller Info (only phoneNumber
element is supported)
The number which will be displayed to the called
party. Optional
playPrompt
True | False
The audio prompt that the calling party hears when
the call is connected. Optional
Response Body
Parameter
Type
Description
id
string
Internal identifier of a RingOut call
status
RingOut Status Info [106]
RingOut status information
CONFIDENTIAL
105
Rev.1.0.16.a.[79434afda268+]
RingOut
RingOut Status Info
Parameter
Type
Description
callStatus
string
Status of a call
callerStatus
string
Status of a calling party
calleeStatus
string
Status of a called party
Call Status
Parameter
Description
Invalid
Invalid call status
Success
Call is connected
InProgress
Connection is in progress
Busy
Call failed
NoAnswer
Call failed
Rejected
Call failed
GenericError
Call failed
Finished
Call is completed
InternationalDisabled International calls are disabled
DestinationBlocked
Destination number is prohibited
NotEnoughFunds
Low balance on account
NoSuchUser
Call failed
Request example
Example
Request example
POST /restapi/v1.0/account/~/extension/~/ringout HTTP/1.1
Authorization: Bearer UExBMDFUMDRQV1MwMnzeaX-Y1k77JspRU1uvPvfyj8Faaw
Content-Type: application/json
{
"from": {"phoneNumber": "12053320032"},
"to": {"phoneNumber": "12052160005"},
"callerId": {"phoneNumber": "12053320032"},
"playPrompt": true
}
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/account/400162076008/extension/400162076008/ringout/1",
"id" : 1,
"status" : {
"callStatus" : "InProgress",
"callerStatus" : "InProgress",
CONFIDENTIAL
106
Rev.1.0.16.a.[79434afda268+]
RingOut
"calleeStatus" : "InProgress"
}
}
Get Status of RingOut Call
Since 1.0.7 (Release 5.16)
Returns the status of a 2-leg RingOut call.
Method/URI
GET /restapi/v1.0/account/{accountId}/extension/{extensionId}/ringout/{ringoutId}
Usage Plan Group
Light
Path Parameters
Parameter
Type
Description
accountId,
extensionId
integer
See the section called “Generic Path Parameters”
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 [106]
RingOut status information
Example
Request example
GET /restapi/v1.0/account/~/extension/~/ringout/2 HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQV1MwM3zcKcfZlnowKxw6lxYDv9mfS1b6eQ
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
CONFIDENTIAL
107
Rev.1.0.16.a.[79434afda268+]
RingOut
"uri" : "https:.../restapi/v1.0/account/400162076008/extension/400162076009/ringout/2",
"id" : 2,
"status" : {
"callStatus" : "Success",
"callerStatus" : "Success",
"calleeStatus" : "Success"
}
}
Cancel RingOut Call
Since 1.0.7 (Release 5.16)
Cancels the 2-leg RingOut call.
Method/URI
DELETE
{ringoutId}
/restapi/v1.0/account/{accountId}/extension/{extensionId}/ringout/
Usage Plan Group
Heavy
Path Parameters
Parameter
Type
Description
accountId,
extensionId
integer
See the section called “Generic Path Parameters”
ringoutId
string
Internal identifier of a RingOut call
Request Body
None
Response Body
None
Example
Request example
DELETE /restapi/v1.0/account/~/extension/~/ringout/44 HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQV1MwM3ynkntrtBfuwxg4QnTdVPcFSUL_Fi
Response example
HTTP/1.1 204 No Content
CONFIDENTIAL
108
Rev.1.0.16.a.[79434afda268+]
Chapter 17. Presence
Get Extension Presence Status
Since 1.0.2
Returns the extension presence status.
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.
Important
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/URI
GET /restapi/v1.0/account/{accountId}/extension/{extensionId(s)}/presence
Batch request is supported, see Batch Requests for details.
Usage Plan Group
Light
Required Permissions
Permission
ReadPresence
Description
Getting user presence information
Path Parameters
Parameter
Type
Batch
support
Description
accountId
string
no
See Generic Path Parameters
extensionId
string
yes
See Generic Path Parameters
Request Body
None
CONFIDENTIAL
109
Rev.1.0.16.a.[79434afda268+]
Presence
Response Body
Presence Info
Property
Type
Description
Standard resource property
canonical URI, see Resource
Identification Properties
uri
presenceStatus
'Offline' | 'Busy' | 'Available'
Aggregated presence status,
calculated from a number of
sources
telephonyStatus
'NoCall' | 'CallConnected' | 'Ringing' |
'OnHold'
Telephony presence status
extension
Extension Info (short) [67]
Information on extension, for
which this presence data is
returned
userStatus
'Offline' | 'Busy' | 'Available'
User-defined presence status
(as previously published by the
user)
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 (as
previously published by user)
allowSeeMyPresence
'True' | 'False'
If "True" enables other
extensions to see the extension
presence status
ringOnMonitoredCall
'True' | 'False'
If "True" enables to ring
extension phone, if any user
monitored by this extension is
ringing
CONFIDENTIAL
110
Rev.1.0.16.a.[79434afda268+]
Presence
Property
pickUpCallsOnHold
Type
Description
'True' | 'False'
If "True" enables the extension
user to pick up a monitored line
on hold
Telephony Status Values
Value
Description
NoCall
The call is disconnected
CallConnected
Telephony connection has been established and the call is
active
Ringing
Telephony connection is being established, destination
phone is ringing, and source phone receives long tones
OnHold
The call is put on hold
Example
Request example
GET /restapi/v1.0/account/400792315004/extension/400792315004/presence HTTP/1.1
Authorization: Bearer U1BCMDFUMDRKV1MwMXwpWCipXIQTrClYKKwK5DkfKVgorg
Accept: application/json
Response example
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 530
{
"uri" : "https.../restapi/v1.0/account/400792315004/extension/400792315004/presence",
"extension" : {
"uri" : "https.../restapi/v1.0/account/400792315004/extension/400792315004",
"id" : 400792315004,
"extensionNumber" : "101"
},
"presenceStatus" : "Available",
"telephonyStatus" : "NoCall",
"userStatus" : "Available",
"dndStatus" : "TakeAllCalls",
"message" : "Hello, World",
"allowSeeMyPresence" : true,
"ringOnMonitoredCall" : false,
"pickUpCallsOnHold" : false
}
CONFIDENTIAL
111
Rev.1.0.16.a.[79434afda268+]
Chapter 18. Notifications: Subscription
API
Create Subscription
Since 1.0.6 (Release 5.15)
Creates a new subscription.
Note
To call this method with APNS transport type you have to specify endpoint_id attribute
in get token request at authorization.
Method/URI
POST /restapi/v1.0/subscription
Usage Plan Group
Medium
Request Body
Parameter
Type
Description
eventFilters
string
Mandatory. Collection of URIs to API resources (see Event
Types for details). For APNS transport type only message event
filter is available
deliveryMode
Collection of
parameters
Notification delivery settings
transportType
'PubNub' |
'APNS'
Notifications transportation provider name. 'APNS' (Apple Push
Notifications Service)
encryption
'True' | 'False' Optional parameter. Specifies if the message will be encrypted
or not. If request contains any presence event filter the value by
default is 'true' (even if specified as 'false'). If request contains
only message event filters the value by default is 'false'
Response Body
Subscription Info
Parameter
Type
Description
id, uri
string
Standard resource properties, see the section
called “Resource Identification Properties”
eventFilters
string
Collection of URIs to API resources
(message-store/presence/detailed presence)
CONFIDENTIAL
112
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
Parameter
Type
Description
expirationTime
datetime
Subscription expiration time
expiresIn
integer
Subscription lifetime in seconds. The default
value is 900
status
'Active' |
'Suspended'
Subscription status
creationTime
datetime
Subscription creation time
deliveryMode
Collection of
parameters
Delivery mode data
transportType
'PubNub' | 'APNS' Notifications transportation provider name.
'APNS' (Apple Push Notifications Service)
encryption
'True' | 'False'
Optional parameter. Specifies if the message
will be encrypted or not. For APNS transport
type the value is always "false"
address
string
PubNub channel name. For APNS transport
type - internal identifier of a device
"device_token"
subscriberKey
string
PubNub subscriber credentials required to
subscribe to the channel
secretKey
string
PubNub subscriber credentials required
to subscribe to the channel. Optional (for
PubNub transport type only)
encryptionAlgorithm
string
Encryption algorithm 'AES' (for PubNub
transport type only)
encryptionKey
string
Key for notification message decryption (for
PubNub transport type only)
Error Codes
HTTP
Status Code
403 Forbidden
Error Code
Reason/Message
1. If all eventFilters specified in request are unavailable for
the current extension, the server responds with this error code
and an optional note in the message field of response payload.
The filters can be unavailable due to the following reasons:
1.1 Presence event filter: "Presence" feature is turned off for
account or is disabled for the current extension type
1.2 Presence event filter: the user disallowed to monitor his/her
presence
1.3 Detailed presence event filter: the user disallowed this
subscriber to pick up his/her calls
2. If the number of subscriptions exceeds the limit, the
server returns this code with the error message: "Current
limit {number of subscriptions} subscriptions was exceeded
for extension {ext. number} applicationId {app ID}." The
CONFIDENTIAL
113
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
HTTP
Status Code
Error Code
Reason/Message
maximum number of subscriptions is limited to 20 for each
user extension on a particular application. If you, for example,
login to the same extension from two different applications,
you can create maximum 40 subscriptions for this extension
(20 on each application)
400 Bad
Request
InvalidParameter If any attributes passed in the request are incorrect, the server
403 Forbidden
SUB-401
No Presence on account
403 Forbidden
SUB-402
No Presence on extension
403 Forbidden
SUB-403
Presence monitoring is disallowed
403 Forbidden
SUB-404
Presence pick-up is disallowed
403 Forbidden
SUB-405
Not allowed to subscribe for notifications on another extension
403 Forbidden
SUB-406
Not allowed to subscribe for notifications on another account
403 Forbidden
SUB-407
Not allowed to deal with APNS subscription if endpoint ID is
not provided in get token request at authorization
403 Forbidden
SUB-408
Not allowed subscribe for unknown user. Implement SIP
registration by calling /sip-provision method
responds with this error code, and an optional note in the
message field describing what is wrong. For example, if the
eventFilters parameter value is empty, then the following
error message is returned: "Parameter [eventFilters] is
invalid [Does not specified]"
Note
If an event filter is duplicated then only one instance of it will be kept for that subscription.
Therefore, the client will always get only a single notification per subscription per event
if the subscription conforms to the event.
Example 1
PubNub Transport Type
Request example
POST /restapi/v1.0/subscription HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMlhvUFI5dmh
Content-Type: application/json
Content-Length: 424
{
"eventFilters": [
"/restapi/v1.0/account/~/extension/~/presence?detailedTelephonyState=true"
],
"deliveryMode": {
"transportType": "PubNub",
"encryption": "false"
}
}
Response example
CONFIDENTIAL
114
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 760
{
"id" : "60ce3d67-9104-478c-bcb3-768d93c0151c",
"creationTime" : "2014-08-20T06:07:04.614Z",
"status" : "Active",
"uri" : "https.../restapi/v1.0/subscription/60ce3d67-9104-478c-bcb3-768d93c0151c",
"eventFilters" : [ "/restapi/v1.0/account/~/extension/400700290004/presence?
detailedTelephonyState=true" ],
"expirationTime" : "2014-08-20T06:22:04.614Z",
"expiresIn" : 899,
"deliveryMode" : {
"transportType" : "PubNub",
"encryption" : true,
"address" : "410843294189492_7777a1d1",
"subscriberKey" : "sub-c-b8b9cd8c-e906-11e2-b383-02ee2ddab7fe",
"secretKey" : "sec-c-ZDNlYjY0OWMtMWFmOC00OTg2LWJjMTMtYjBkMzgzOWRmM",
"encryptionAlgorithm" : "AES",
"encryptionKey" : "/boiP9IObgz6mrDalnl5lA=="
}
}
Example 2
APNS Transport Type
Request example
POST /restapi/v1.0/subscription HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQURIZjAzWFFySGpMen
Content-Type: application/json
Content-Length: 240
{
"eventFilters": [
"/restapi/v1.0/account/~/extension/~/message-store?direction=Inbound"
],
"deliveryMode": {
"transportType": "APNS",
"address": "kdttV0We6coOSKcuCxJx5lyy4Srz5TpEG8JisLu+uB4=",
"encryption": "false"
}
}
Response example
HTTP/1.1 200 OK
Content-Language: en-US
Content-Type: application/json; charset=UTF-8
Content-Length: 605
{
"id" :
"apns6B6474745630576536636F4F534B637543784A78356C79793453727A3554704547384A69734C752B7542343D",
"creationTime" : "2015-03-18T09:23:10.025Z",
"status" : "Active",
"uri" : "https.../restapi/v1.0/subscription/
apns6B6474745630576536636F4F534B637543784A78356C79793453727A3554704547384A69734C752B7542343D",
"eventFilters" : [ "/restapi/v1.0/account/2740078004/extension/2740078004/message-store?
direction=Inbound" ],
"deliveryMode" : {
"transportType" : "APNS",
"encryption" : false,
"address" : "kdttV0We6coOSKcuCxJx5lyy4Srz5TpEG8JisLu+uB4="
}
}
CONFIDENTIAL
115
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
Get Subscription
Since 1.0.6 (Release 5.15)
Returns the requested subscription.
Method/URI
GET /restapi/v1.0/subscription/{subscriptionId}
Usage Plan Group
Light
Path Parameters
Parameter
subscriptionId
Type
Description
string
Internal identifier of a subscription
Request Body
None
Response Body
Subscription Info [112]
Error Codes
HTTP Status Code
Logical Error Code
Possible Reason
If the subscriptionId value is incorrect this error
code is returned
404 Not Found
Example
Request example
GET /restapi/v1.0/subscription/60ce3d67-9104-478c-bcb3-768d93c0151c HTTP/1.1
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMlhvUFI5dmhYVzVsb1h5SnVT
Accept: application/json
Response example
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 760
{
"id" : "60ce3d67-9104-478c-bcb3-768d93c0151c",
"creationTime" : "2014-08-20T06:07:04.614Z",
"status" : "Active",
"uri" : "https.../restapi/v1.0/subscription/60ce3d67-9104-478c-bcb3-768d93c0151c",
"eventFilters" : [ "/restapi/v1.0/account/~/extension/400700290004/presence?
detailedTelephonyState=true" ],
CONFIDENTIAL
116
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
"expirationTime" : "2014-08-20T06:22:04.614Z",
"expiresIn" : 687,
"deliveryMode" : {
"transportType" : "PubNub",
"encryption" : true,
"address" : "410843294189492_7777a1d1",
"subscriberKey" : "sub-c-b8b9cd8c-e906-11e2-b383-02ee2ddab7fe",
"secretKey" : "sec-c-ZDNlYjY0OWMtMWFmOC00OTg2LWJjMTMtYjBkMzgzOWRmMzUz",
"encryptionAlgorithm" : "AES",
"encryptionKey" : "/boiP9IObgz6mrDalnl5lA=="
}
}
Renew Subscription
Since 1.0.6 (Release 5.15)
Renews the existent subscription.
Method/URI
PUT /restapi/v1.0/subscription/{subscriptionId}
Usage Plan Group
Medium
Path Parameters
Parameter
subscriptionId
Type
string
Description
Internal identifier of a subscription
Request Body
Current eventFilters (as in POST/restapi/v1.0/subscription request) or empty body
Response Body
Subscription Info [112]
Example
Request example
PUT /restapi/v1.0/subscription/60ce3d67-9104-478c-bcb3-768d93c0151c HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMlhvUFI5dmhYVzVsb
Content-Type: application/json
Content-Length: 3
{}
Response example
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 760
{
CONFIDENTIAL
117
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
"id" : "60ce3d67-9104-478c-bcb3-768d93c0151c",
"creationTime" : "2014-08-20T06:07:04.614Z",
"status" : "Active",
"uri" : "https.../restapi/v1.0/subscription/60ce3d67-9104-478c-bcb3-768d93c0151c",
"eventFilters" : [ "/restapi/v1.0/account/~/extension/400700290004/presence?
detailedTelephonyState=true" ],
"expirationTime" : "2014-08-20T06:35:30.701Z",
"expiresIn" : 899,
"deliveryMode" : {
"transportType" : "PubNub",
"encryption" : true,
"address" : "410843294189492_7777a1d1",
"subscriberKey" : "sub-c-b8b9cd8c-e906-11e2-b383-02ee2ddab7fe",
"secretKey" : "sec-c-ZDNlYjY0OWMtMWFmOC00OTg2LWJjMTMtYjBkMzgzOWRmMzUz",
"encryptionAlgorithm" : "AES",
"encryptionKey" : "/boiP9IObgz6mrDalnl5lA=="
}
}
Modify Event Filters
Since 1.0.6 (Release 5.15)
Modifies the event filters for the existing subscription. The client application can extend or narrow the
events for which it receives notifications in the frame of one subscription.
Method/URI
PUT /restapi/v1.0/subscription/{subscriptionId}
Usage Plan Group
Medium
Path Parameters
Parameter
subscriptionId
Type
string
Description
Internal identifier of a subscription
Request Body
Parameter
eventFilters
Type
string
Description
Collection of URIs to API resources (see Event Types).
Mandatory field
Response Body
Subscription Info [112]
Note
When modifying the event filters, the subscription is renewed automatically.
CONFIDENTIAL
118
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
Example
Request example
PUT /restapi/v1.0/subscription/78c53776-6aa5-4089-b080-150089c097bf HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFKV1MwMnxXEhpuK23FJtRSi_rafOgPSMOorQ
Content-Type: application/json
Content-Length: 159
{
"eventFilters": [
"/restapi/v1.0/account/~/extension/~/message-store",
"/restapi/v1.0/account/~/extension/~/presence"
]
}
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"eventFilters" : [ "/restapi/v1.0/account/~/extension/400978708008/message-store","/restapi/
v1.0/account/~/extension/400978708008/presence" ],
"expirationTime" : "2014-04-28T15:41:32.272Z",
"deliveryMode" : {
"transportType" : "PubNub",
"encryption" : true,
"address" : "3695317637993668_ac84962a",
"subscriberKey" : "sub-c-b8b9cd8c-e906-11e2-b383-02ee2ddab7fe",
"secretKey" : "sec-c-ZDNlYjY0OWMtMWFmOC00OTg2LWJjMTMtYjBkMzgzOWRmMzUz",
"encryptionAlgorithm" : "AES",
"encryptionKey" : "WchkzJuAJT9BqoDffzg2Kg=="
},
"id" : "a2206de0-1eca-48be-a951-2899e89c03bf",
"creationTime" : "2014-04-28T14:26:32.272Z",
"status" : "Active",
"uri" : "https.../restapi/v1.0/subscription/a2206de0-1eca-48be-a951-2899e89c03bf"
}
Cancel Subscription
Cancels the existent subscription.
Method/URI
DELETE /restapi/v1.0/subscription/{subscriptionId}
Usage Plan Group
Medium
Path Parameters
Parameter
subscriptionId
CONFIDENTIAL
Type
string
Description
Internal identifier of a subscription
119
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
Request Body
None
Response Body
None
Error Codes
HTTP Status Code
Logical
Error Code
Possible Reason
If the subscriptionId value is incorrect this
error code is returned
404 Not Found
Example
Request example
DELETE /restapi/v1.0/subscription/a2206de0-1eca-48be-a951-2899e89c03bf HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFKV1MwMnxXEhpuK23FJtRSi_rafOgPSMOorQ
Response example
HTTP/1.1 204 No Content
Notifications Event Types
Notifications which the client wants to receive can be specified by the event filters, that are set in the
subscription request. The event filter is exposed as a URL, pointing to the RingCentral API resource.
Currently the following event types are available for notifications: messages, presence and detailed
presence. They are described in detail below.
Messages Event
Since 1.0.6 (Release 5.15)
This event filter /restapi/v1.0/account/~/extension/~/message-store specifies that notifications
will be sent in case of:
• new message creation;
• any message change in extension message store.
Note
You should obtain the updated message info by calling the GET Message List method.
CONFIDENTIAL
120
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
Notification Payload Structure
The client receives messages notifications payload as JSON object with the following structure:
Parameter
Type
Description
uuid
string
Universally unique identifier of a notification
event
string
Event filter URI
body
Collection of parameters
Notification payload body
extensionId
integer
Internal identifier of an extension. Optional
parameter
lastUpdated
datetime
The time the message has been last modified
changes
Collection of parameters
Message changes
type
'Voicemail' | 'SMS' | 'Fax' |
'Pager'
Message type
newCount
integer
The number of new messages. Can be omitted if
the value is zero
updatedCount
integer
The number of updated messages. Can be
omitted if the value is zero
Example
{
"timestamp": "2014-04-29T14:29:27.408+0000",
"uuid": "b11c9430-9687-4498-b12b-3fcb470bfe04",
"event": "/restapi/v1.0/account/~/extension/406149828004/message-store",
"body": {
"extensionId": 406149828004,
"lastUpdated": "2014-04-29T14:29:20.531+0000",
"changes": [
{
"type": "Pager",
"updatedCount": 1,
"newCount": 0
}
{
"type": "SMS",
"updatedCount": 0,
"newCount": 1
},
{...} ],
},
}
Presence Event
Since 1.0.6 (Release 5.15)
1. This event filter/restapi/v1.0/account/~/extension/~/presence specifies that notifications
will be sent in case of any change of the following presence information:
• userStatus
• dndStatus
CONFIDENTIAL
121
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
• message
• telephonyStatus
2. This event filter /restapi/v1.0/account/~/extension/~/presence/line/presence specifies
that notifications will be sent to the client in case of changes in the presence information of extensions
which are monitored by the current extension.
Note
The modified data itself is not returned in notification payload body if DnD status, user
status or message are changed. You should obtain presence info by calling the GET
Extension Presence Status method.
Notification Payload Structure
The client receives non-detailed presence notification payload as a JSON object with the following
structure:
Parameter
Type
Description
uuid
string
Universally unique identifier of a notification
event
string
Event filter URI
body
Collection of parameters
Notification payload body
extensionId
integer
Internal identifier of an extension. Optional
parameter
telephonyStatus
'NoCall' | 'CallConnected' | Telephony presence status. Returned if telephony
'Ringing' | 'OnHold'
status is changed. See Telephony Status
Values [111]
Example
{
"timestamp": "2014-04-29T14:28:35.996+0000",
"uuid": "08174cd9-3fe1-45e1-aa23-77043164f8f9",
"event": "/restapi/v1.0/account/~/extension/406149828004/presence",
"body": {
"extensionId": 406149828004,
"telephonyStatus": "Ringing"
}
}
Detailed Presence Event
Since 1.0.6 (Release 5.15)
The additional attribute for this event filter is the list of active calls for the given extension.
1. This
event
filter
/restapi/v1.0/account/~/extension/~/presence?
detailedTelephonyState=true specifies that detailed presence notifications for the requested
extension will be sent to the client in case of any change of the following presence information:
• userStatus
CONFIDENTIAL
122
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
• dndStatus
• message
• telephonyStatus
2. This
event
filter
/restapi/v1.0/account/~/extension/~/presence/line/presence?
detailedTelephonyState=true specifies that detailed presence notifications will be sent to the client
in case of changes in the presence information of extensions which are monitored by the current
extension.
Note
If both presence and detailed presence event types are specified, then the detailed presence
notifications will be received.
Notification Payload Structure
The client receives detailed presence notifications payload as a JSON object with the following structure:
Parameter
Type
Description
uuid
string
Universally unique identifier of a notification
event
string
Event filter URI
body
Collection of
parameters
Notification payload body
sequence
integer
Order number of notification to state the chronology
sessionId
string
Internal identifier of a call session
extensionId
integer
Internal identifier of an extension. Optional parameter
telephonyStatus
'NoCall' |
'CallConnected' |
'Ringing' | 'OnHold'
Aggregated telephony call status, based on the priority
of active calls. See Telephony Status Values [111]
activeCalls
Collection of
parameters
Active calls for the given extension
id
string
Internal identifier of the call
from
string
Phone number or extension number of a caller
to
string
Phone number or extension number of a callee
direction
'Inbound' | 'Outbound'
Call direction
telephonyStatus
'NoCall' |
'CallConnected' |
'Ringing' | 'OnHold'
Telephony call status. See Telephony Status
Values [111] for detailed status description
Example
{
"timestamp": "2014-04-29T13:23:12.468+0000",
"uuid": "a295fa1f-af6a-4518-b333-acf091bdd7ea",
CONFIDENTIAL
123
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
"event": "/restapi/v1.0/account/~/extension/406149828004/presence?
detailedTelephonyState=true",
"body": {
"sequence": 3
"extensionId": 406149828004,
"sessionId" : "403389471094",
"telephonyStatus": "NoCall",
"activeCalls": [
{
"id": null,
"from": "+18558689714",
"to": "6316761623",
"direction": "Outbound",
"telephonyStatus": "NoCall"
},
{...}
],
},
}
Presence Line Event
Since 1.0.16 (Release 7.1)
This event filter /restapi/v1.0/account/~/extension/~/presence/line specifies that notifications
will be sent in case the list of extensions, which presence is monitored by the current extension, has
changed.
Notification Payload Structure
The client receives detailed presence notifications payload as a JSON object with the following structure:
Parameter
Type
Description
uuid
string
Universally unique identifier of a notification
event
string
Event filter URI
body
Collection of
parameters
Notification payload body
extension
Collection of
parameters
Extension information
id
string
Internal identifier of the extension
id
string
Internal identifier of the returned line
Example
{
"timestamp": "2014-04-29T13:23:12.468+0000",
"uuid": "a295fa1f-af6a-4518-b333-acf091bdd7ea",
"event": "/restapi/v1.0/account/~/extension/406149828004/presence/line",
"body": {
"extension": {
"id": "677628004765"
},
"id": "3"
},
{...}
},
CONFIDENTIAL
124
Rev.1.0.16.a.[79434afda268+]
Notifications: Subscription API
}
CONFIDENTIAL
125
Rev.1.0.16.a.[79434afda268+]
Chapter 19. Dictionary
This API allows to get information on all the countries and the corresponding states, provinces and
counties, available for calling.
Get Single Country
Since 1.0.10 (Release 6.2)
Returns the information on the required country.
Method/URI
GET /restapi/v1.0/dictionary/country/{countryId}
Usage Plan Group
Light
Path Parameters
Parameter
Type
Description
string
countryId
Internal identifier of a country
Request Body
None
Response Body
Country Info
Parameter
Type
Description
Standard resource properties ID and canonical URI; see the section
called “Resource Identification Properties”
id, uri
name
string
Official name of the country
isoCode
string
Country code according to the ISO standard, see ISO 3166 [http://
en.wikipedia.org/wiki/ISO_3166]
callingCode
string
Country calling code defined by ITU-T [http://en.wikipedia.org/
wiki/ITU-T] recommendations E.123 [http://en.wikipedia.org/wiki/
E.123] and E.164 [http://en.wikipedia.org/wiki/E.164], see Calling
Codes [http://en.wikipedia.org/wiki/List_of_country_calling_codes]
Example
Request example
GET https.../restapi/v1.0/dictionary/country/1 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXxO-FoZwFZyHYPYGNhxFhxmEzRTwg
CONFIDENTIAL
126
Rev.1.0.16.a.[79434afda268+]
Dictionary
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/country/1",
"id" : "1",
"name" : "United States",
"isoCode" : "US",
"callingCode" : "1"
}
Get Countries
Since 1.0.10 (Release 6.2)
Returns all the countries available for calling.
Method/URI
GET /restapi/v1.0/dictionary/country
Usage Plan Group
Light
Query Parameters
Parameter
page, perPage
Type
Description
integer
Standard paging parameters, see the section
called “Common Query Parameters in Collection
Resources”
Standard collection metadata, see the section called
“Common Collection Properties”
paging, navigation
Request Body
None
Response Body
Collection [Country Info [126]]
Example
Request example
GET /restapi/v1.0/dictionary/country?page=17&perPage=3 HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMXy62rmA1DFyfjMse_RdEC4Zs0mYkA
Response example
HTTP/1.1 200 OK
CONFIDENTIAL
127
Rev.1.0.16.a.[79434afda268+]
Dictionary
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/country?page=17&perPage=3",
"records" : [ {
"uri" : "https.../restapi/v1.0/dictionary/country/14",
"id" : "14",
"name" : "Congo, Democratic Republic",
"isoCode" : "CD",
"callingCode" : "243"
}, {
"uri" : "https.../restapi/v1.0/dictionary/country/52",
"id" : "52",
"name" : "Cook Islands",
"isoCode" : "CK",
"callingCode" : "682"
}, {
"uri" : "https.../restapi/v1.0/dictionary/country/53",
"id" : "53",
"name" : "Costa Rica",
"isoCode" : "CR",
"callingCode" : "506"
} ],
"paging" : {
"page" : 17,
"totalPages" : 83,
"perPage" : 3,
"totalElements" : 247,
"pageStart" : 48,
"pageEnd" : 50
},
"navigation" : {
"nextPage" : {
"uri" : "https.../restapi/v1.0/dictionary/country?page=18&perPage=3"
},
"previousPage" : {
"uri" : "https.../restapi/v1.0/dictionary/country?page=16&perPage=3"
},
"firstPage" : {
"uri" : "https.../restapi/v1.0/dictionary/country?page=1&perPage=3"
},
"lastPage" : {
"uri" : "https.../restapi/v1.0/dictionary/country?page=83&perPage=3"
}
}
}
Get Single State
Since 1.0.10 (Release 6.2)
Returns the information on the required state.
Method/URI
GET /restapi/v1.0/dictionary/state/{stateId}
Usage Plan Group
Light
Path Parameters
Parameter
stateId
CONFIDENTIAL
Type
Description
string
Internal identifier of a state
128
Rev.1.0.16.a.[79434afda268+]
Dictionary
Request Body
None
Response Body
State Info
Parameter
Type
Description
Standard resource properties ID and canonical URI; see the section
called “Resource Identification Properties”
id, uri
name
string
Official name of the state
isoCode
string
Short code for the state (2-letter usually)
country
string
ID and URI of the country the state is in, as a part of the Country
Info [126]
Example
Request example
GET /restapi/v1.0/dictionary/state/13 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXz4fLQaUGXzS41vGnEw43d0JVPIUw
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/state/13",
"id" : "13",
"name" : "ALASKA",
"isoCode" : "AK",
"country" : {
"uri" : "https.../restapi/v1.0/dictionary/country/1",
"id" : "1"
}
}
Get States of a Country
Since 1.0.10 (Release 6.2)
Returns all the states for the certain country.
Method/URI
GET /restapi/v1.0/dictionary/state
Usage Plan Group
Light
CONFIDENTIAL
129
Rev.1.0.16.a.[79434afda268+]
Dictionary
Query Parameters
Parameter
Type
Description
countryId
string
Internal identifier of a country
withPhoneNumbers
'True' | 'False'
If 'True', the list of states with phone numbers
available for buying is returned. The default value is
'False'
page, perPage
integer
Standard paging parameters, see the section
called “Common Query Parameters in Collection
Resources”
Request Body
None
Response Body
Collection [State Info [129]]
Example
Request example
GET /restapi/v1.0/dictionary/state?countryId=39 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXz4fLQaUGXzS41vGnEw43d0JVPIUw
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/state?countryId=39&page=1&perPage=100",
"records" : [ {
"uri" : "https.../restapi/v1.0/dictionary/state/501",
"id" : "501",
"name" : "Alberta",
"isoCode" : "AB",
"country" : {
"uri" : "https.../restapi/v1.0/dictionary/country/39",
"id" : "39"
}
}, {
"uri" : "https.../restapi/v1.0/dictionary/state/505",
"id" : "505",
"name" : "British Columbia",
"isoCode" : "BC",
"country" : {
"uri" : "https.../restapi/v1.0/dictionary/country/39",
"id" : "39"
}
}, {
"uri" : "https.../restapi/v1.0/dictionary/state/516",
"id" : "516",
"name" : "Manitoba",
"isoCode" : "MB",
"country" : {
"uri" : "https.../restapi/v1.0/dictionary/country/39",
"id" : "39"
}
CONFIDENTIAL
130
Rev.1.0.16.a.[79434afda268+]
Dictionary
}, {
"uri" : "https.../restapi/v1.0/dictionary/state/517",
"id" : "517",
"name" : "New Brunswick",
"isoCode" : "NB",
"country" : {
"uri" : "https.../restapi/v1.0/dictionary/country/39",
"id" : "39"
}
}, {...}
],
"paging" : {
"page" : 1,
"totalPages" : 1,
"perPage" : 100,
"totalElements" : 13,
"pageStart" : 0,
"pageEnd" : 12
},
"navigation" : {
"firstPage" : {
"uri" : "https.../restapi/v1.0/dictionary/state?countryId=39&page=1&perPage=100"
},
"lastPage" : {
"uri" : "https.../restapi/v1.0/dictionary/state?countryId=39&page=1&perPage=100"
}
}
}
Get All Locations
Since 1.0.10 (Release 6.2)
Returns all the available locations for the certain state.
Method/URI
GET /restapi/v1.0/dictionary/location
Usage Plan Group
Light
Query Parameters
Parameter
Type
Description
stateId
string
Internal identifier of a state
orderBy
'Npa' | 'City'
Sorts results by the specified property. The default
value is 'City'
page, perPage
integer
Standard paging parameters, see the section called
“Common Query Parameters in Collection Resources”
Request Body
None
Response Body
Collection [Location Info [132]]
CONFIDENTIAL
131
Rev.1.0.16.a.[79434afda268+]
Dictionary
Location Info
Parameter
Type
Description
Standard resource properties ID and canonical URI; see the section
called “Resource Identification Properties”
uri
city
string
Official name of the city, belonging to the certain state
npa
string
Area code of the location (3-digit usually), according to the
NANP number format, that can be summarized as NPANXX-xxxx and covers Canada, the United States, parts of the
Caribbean Sea, and some Atlantic and Pacific islands. See
North American Numbering Plan [http://en.wikipedia.org/wiki/
North_American_Numbering_Plan] for details
nxx
string
Central office code of the location, according to the NANP number
format, that can be summarized as NPA-NXX-xxxx and covers
Canada, the United States, parts of the Caribbean Sea, and some
Atlantic and Pacific islands. See North American Numbering Plan
[http://en.wikipedia.org/wiki/North_American_Numbering_Plan]
for details
state
string
ID and URI of the state this location belongs to, as a part of the State
Info [129]
Example
Request example
GET /restapi/v1.0/dictionary/location?stateId=516&orderBy=City HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXzqYEmFlzzQ19sSTpvsRKY6RXkQPw
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/location?
stateId=516&orderBy=City&page=1&perPage=100",
"records" : [ {
"city" : "Winnipeg",
"npa" : "204",
"nxx" : "null",
"state" : {
"uri" : "https.../restapi/v1.0/dictionary/state/516",
"id" : "516"
}
}, {
"city" : "Winnipeg",
"npa" : "204",
"nxx" : "272",
"state" : {
"uri" : "https.../restapi/v1.0/dictionary/state/516",
"id" : "516"
}
}, {
"city" : "Winnipeg",
"npa" : "204",
"nxx" : "800",
"state" : {
"uri" : "https.../restapi/v1.0/dictionary/state/516",
"id" : "516"
}
CONFIDENTIAL
132
Rev.1.0.16.a.[79434afda268+]
Dictionary
}, {
"city" : "Winnipeg",
"npa" : "204",
"nxx" : "480",
"state" : {
"uri" : "https.../restapi/v1.0/dictionary/state/516",
"id" : "516"
}
}, {
"city" : "Winnipeg",
"npa" : "204",
"nxx" : "318",
"state" : {
"uri" : "https.../restapi/v1.0/dictionary/state/516",
"id" : "516"
}
} ],
"paging" : {
"page" : 1,
"totalPages" : 1,
"perPage" : 100,
"totalElements" : 5,
"pageStart" : 0,
"pageEnd" : 4
},
"navigation" : {
"firstPage" : {
"uri" : "https.../restapi/v1.0/dictionary/location?
stateId=516&orderBy=City&page=1&perPage=100"
},
"lastPage" : {
"uri" : "https.../restapi/v1.0/dictionary/location?
stateId=516&orderBy=City&page=1&perPage=100"
}
}
}
Get Single Timezone
Since 1.0.10 (Release 6.2)
Returns the information on the certain timezone.
Method/URI
GET /restapi/v1.0/dictionary/timezone/{timezoneId}
Usage Plan Group
Light
Path Parameters
Parameter
timezoneId
Type
Description
string
Internal identifier of a timezone
Query Parameters
Parameter
page, perPage
CONFIDENTIAL
Type
Description
integer
Standard paging parameters, see the section
called “Common Query Parameters in Collection
Resources”
133
Rev.1.0.16.a.[79434afda268+]
Dictionary
Request Body
None
Response Body
Timezone Info
Parameter
Type
Description
Standard resource properties ID and canonical URI; see the section
called “Resource Identification Properties”
id, uri
name
string
Short name of the timezone
description
string
Meaningful description of the timezone
Example
Request example
GET /restapi/v1.0/dictionary/timezone/57 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXw3nyAG7E-TvrhWGS8VjCNy3VIiNQ
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/timezone/57",
"id" : "57",
"name" : "US/Mountain",
"description" : "Mountain Time (US & Canada)"
}
Get All Timezones
Since 1.0.10 (Release 6.2)
Returns all available timezones.
This API provides access to all the available time zones and their respective IDs. They may be used to
configure the default time zone and time zones for specific extensions. The API supports only one operation
- retrieving available time zones.
Method/URI
GET /restapi/v1.0/dictionary/timezone
Usage Plan Group
Light
CONFIDENTIAL
134
Rev.1.0.16.a.[79434afda268+]
Dictionary
Query Parameters
Parameter
page, perPage
Type
Description
string
Official name of the state, which locations are to be
returned
Request Body
None
Response Body
Collection [Timezone Info [134]]
Example
Request example
GET /restapi/v1.0/dictionary/timezone?perPage=7 HTTP/1.1
Accept: application/json
Authorization: Bearer UExBMDFUMDRQV1MwMXwpRl4bV49QPA2GrecHHauJzSKX5w
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"uri" : "https.../restapi/v1.0/dictionary/timezone?page=1&perPage=7",
"records" : [ {
"uri" : "https.../restapi/v1.0/dictionary/timezone/1",
"id" : "1",
"name" : "GMT",
"description" : "Casablanca, Monrovia, Reykjavik"
}, {
"uri" : "https.../restapi/v1.0/dictionary/timezone/2",
"id" : "2",
"name" : "WET",
"description" : "Dublin, Edinburgh, Lisbon, London"
}, {
"uri" : "https.../restapi/v1.0/dictionary/timezone/3",
"id" : "3",
"name" : "CET",
"description" : "Brussels, Copenhagen, Madrid, Paris"
}, {
"uri" : "https.../restapi/v1.0/dictionary/timezone/4",
"id" : "4",
"name" : "CET",
"description" : "Sarajevo, Skopje, Warsaw, Zagreb"
}, {
"uri" : "https.../restapi/v1.0/dictionary/timezone/5",
"id" : "5",
"name" : "CET",
"description" : "Belgrade, Bratislava, Budapest, Ljubljana, Prague"
}, {
"uri" : "https.../restapi/v1.0/dictionary/timezone/6",
"id" : "6",
"name" : "CET",
"description" : "Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna"
}, {
"uri" : "https.../restapi/v1.0/dictionary/timezone/7",
"id" : "7",
"name" : "EET",
"description" : "Athens, Bucharest, Istanbul"
} ],
CONFIDENTIAL
135
Rev.1.0.16.a.[79434afda268+]
Dictionary
"paging" : {
"page" : 1,
"totalPages" : 13,
"perPage" : 7,
"totalElements" : 90,
"pageStart" : 0,
"pageEnd" : 6
},
"navigation" : {
"nextPage" : {
"uri" : "https.../restapi/v1.0/dictionary/timezone?page=2&perPage=7"
},
"firstPage" : {
"uri" : "https.../restapi/v1.0/dictionary/timezone?page=1&perPage=7"
},
"lastPage" : {
"uri" : "https.../restapi/v1.0/dictionary/timezone?page=13&perPage=7"
}
}
}
Get Language List
Since 1.0.14 (Release 6.6)
Returns the information about supported languages.
Method/URI
GET /restapi/v1.0/dictionary/language
Usage Plan Group
Light
Request Body
None
Response Body
Parameter
Type
Description
records
Collection of
parameters
User interface language data
id, uri
string
Standard resource properties ID and canonical URI; see the
section called “Resource Identification Properties”
name
string
Name of the language
isoCode
string
Language code according to the ISO standard, see ISO 639
[http://ru.wikipedia.org/wiki/ISO_639]
localeCode
string
Localization code
paging, navigation
Standard collection metadata, see the section called
“Common Collection Properties”
Example
Request example
CONFIDENTIAL
136
Rev.1.0.16.a.[79434afda268+]
Dictionary
GET /restapi/v1.0/dictionary/language HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMnxBQUFWZmY4ZXoxMlhv
Response example
HTTP/1.1 200 OK
Content-Language: en
Content-Type: application/json; charset=UTF-8
Content-Length: 897
{
"uri" : "https.../restapi/v1.0/dictionary/language?page=1&perPage=100",
"records" : [ {
"uri" : "https.../restapi/v1.0/dictionary/language/1033",
"id" : "1033",
"name" : "English (United States)",
"isoCode" : "en",
"localeCode" : "en-US"
}, {
"uri" : "https.../restapi/v1.0/dictionary/language/1049",
"id" : "1049",
"name" : "Russian",
"isoCode" : "ru",
"localeCode" : "ru-RU"
} ],
"paging" : {
"page" : 1,
"totalPages" : 1,
"perPage" : 100,
"totalElements" : 2,
"pageStart" : 0,
"pageEnd" : 1
},
"navigation" : {
"firstPage" : {
"uri" : "https.../restapi/v1.0/dictionary/language?page=1&perPage=100"
},
"lastPage" : {
"uri" : "https.../restapi/v1.0/dictionary/language?page=1&perPage=100"
}
}
}
Get Single Language
Since 1.0.14 (Release 6.6)
Returns language by its respective ID.
Method/URI
GET /restapi/v1.0/dictionary/language/{languageId}
Usage Plan Group
Light
Path Parameters
Parameter
languageId
CONFIDENTIAL
Type
string
Description
Internal identifier of a language; see the section called “Resource
Identification Properties”
137
Rev.1.0.16.a.[79434afda268+]
Dictionary
Response Body
None
Response Body
Parameter
Type
Description
id, uri
string
Standard resource properties ID and canonical URI; see the section
called “Resource Identification Properties”
name
string
Name of the language
isoCode
string
Language code according to the ISO standard, see ISO 639 [http://
ru.wikipedia.org/wiki/ISO_639]
localeCode
string
Localization code
Example
Request example
GET /restapi/v1.0/dictionary/language/1033 HTTP/1.1
Accept: application/json
Authorization: Bearer U0pDMDFQMDFQQVMwMXxBQUFWZmY4ZXoxMlhvSDBfczRRd2ZMclB1dG
Response example
HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en
Content-Length: 182
{
"uri" : "https.../restapi/v1.0/dictionary/language/1033",
"id" : "1033",
"name" : "English (United States)",
"isoCode" : "en",
"localeCode" : "en-US"
}
CONFIDENTIAL
138
Rev.1.0.16.a.[79434afda268+]