---
title: "Create Subscription"
method: POST
path: "/restapi/v1.0/subscription"
tags: ["Subscriptions"]
---

# Create Subscription

`POST /restapi/v1.0/subscription`

This API allows client applications to register a new subscription so that it
can be notified of events when they occur on the platform.

A subscription relates to a set of events that a client application would like
to be informed of and the delivery channel by which they will be notified of
those events. How subscriptions are established depends upon the notification
channel the client application would like to use to receive the event
notification. For example, to create a webhook a developer would create a
subscription via a REST API call, while specifying a list of events or "event
filters" to be notified of, a transport type of `WebHook`, and the address or
URL to which they would like the webhook delivered.

However, developers wishing to subscribe to a set of events via a WebSocket
channel, would first connect to the WebSocket gateway, and then issue their
subscription request over the WebSocket itself, as opposed to making a REST
API call to this endpoint.

While the protocol for establishing a subscription may vary depending upon
the delivery channel for that subscription, the schemas used for representing
a subscription are the same across all delivery modes.

Subscriptions are currently limited to 20 subscriptions per user/extension (for particular application).

RingCentral currently supports the following delivery modes for event subscriptions:

* [WebHook](https://developers.ringcentral.com/guide/notifications/webhooks/quick-start) - to receive event notifications as an HTTP POST to a given URL
* [WebSocket](https://developers.ringcentral.com/guide/notifications/websockets/quick-start) - to receive real-time events over a persistent WebSocket connection
* [PubNub](https://developers.ringcentral.com/guide/notifications/push-notifications/quick-start) (deprecated) - to receive a push notification sent directly to a client application

Developers should be aware that the PubNub delivery mode is currently
deprecated and will be removed in 2024. Developers are encouraged to
[migrate their client applications to use WebSockets](https://developers.ringcentral.com/guide/notifications/websockets/migration/)
instead.

## Request body

- CreateSubscriptionRequest
  - `eventFilters` string[], required — The list of event filters corresponding to events the user is subscribed to
  - `expiresIn` integer — Subscription lifetime in seconds. The maximum subscription lifetime depends upon the specified `transportType`: | Transport type | Maximum permitted lifetime | | ------------------- | ------------------------------ | | `WebHook` | 315360000 seconds (10 years) | | `RC/APNS`, `RC/GSM` | 7776000 seconds (90 days) | | `PubNub` | 900 seconds (15 minutes) | | `WebSocket` | n/a (the parameter is ignored) |
  - `deliveryMode` union, required — Notification delivery transport information
    - WebhookDeliveryModeRequest
      - `transportType` 'WebHook', required — The transport type for this subscription, or the channel by which an app should be notified of an event
      - `address` string, uri, required — The URL to which notifications should be delivered. This is only applicable for the `WebHook` transport type, for which it is a required field.
      - `verificationToken` string — An optional validation token used to verify the authenticity of the incoming webhook. Applicable only for the `WebHook` transport type.
    - MobileDeliveryModeRequest
      - `transportType` 'RC/APNS' | 'RC/GCM', required — The transport type for this subscription, or the channel by which an app should be notified of an event
      - `certificateName` string, required — Certificate name for mobile notification transports
      - `registrationId` string, required — Device instance ID for mobile notification transports
    - PubNubDeliveryModeRequest
      - `transportType` 'PubNub', required — The transport type for this subscription, or the channel by which an app should be notified of an event
      - `encryption` boolean — Optional. Specifies if notification messages will be encrypted or not. Please note that for some event filters (e.g. presence) encryption is mandatory and `false` value provided by caller will be ignored.

## Response `200`

Successful response

- SubscriptionInfo
  - `uri` string, uri, required — Canonical URI of a subscription resource
  - `id` string, required — Internal identifier of a subscription
  - `eventFilters` string[], required — The list of event filter names corresponding to events the user is subscribed to
  - `disabledFilters` DisabledFilterInfo[] — The list of event filter names corresponding to events the user is not subscribed to due to certain limitations
    - `filter` string, required — Event filter that is disabled for the user
    - `reason` string, required — Reason why the filter is disabled for the user
    - `message` string — Error message
  - `expirationTime` string, date-time, required — Subscription expiration time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format including timezone, for example *2016-03-10T18:07:52.534Z*
  - `expiresIn` integer — Subscription lifetime in seconds
  - `status` 'Active' | 'Blacklisted', required — Subscription status
  - `creationTime` string, date-time, required — Subscription creation time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format including timezone, for example *2016-03-10T18:07:52.534*
  - `deliveryMode` union, required — Notification delivery transport information
    - WebhookDeliveryMode
      - `transportType` 'WebHook', required — The transport type for this subscription, or the channel by which an app should be notified of an event
      - `address` string, uri, required — The URL to which notifications should be delivered. This is only applicable for the `WebHook` transport type, for which it is a required field.
      - `encryption` false, required — Specifies if notification messages will be encrypted or not.
    - MobileDeliveryMode
      - `transportType` 'RC/APNS' | 'RC/GCM', required — The transport type for this subscription, or the channel by which an app should be notified of an event
      - `certificateName` string, required — Certificate name for mobile notification transports
      - `registrationId` string, required — Device instance ID for mobile notification transports
      - `encryption` false, required — Specifies if notification messages will be encrypted or not.
    - PubNubDeliveryMode
      - `transportType` 'PubNub', required — The transport type for this subscription, or the channel by which an app should be notified of an event
      - `encryption` boolean, required — Optional. Specifies if notification messages will be encrypted or not. Please note that for some event filters (e.g. presence) encryption is mandatory and `false` value provided by caller will be ignored.
      - `address` string, required — PubNub channel name
      - `subscriberKey` string, required — PubNub credential required to subscribe to the channel
      - `secretKey` string, required — PubNub credential required to subscribe to the channel
      - `encryptionAlgorithm` 'AES' — (Only for a "PubNub" transport, returned only if `encryption` is `true`) Encryption algorithm used
      - `encryptionKey` string — (Only for a "PubNub" transport, returned only if `encryption` is `true`) Cryptographic key to decrypt PubNub notification messages
    - WebSocketDeliveryMode
      - `transportType` 'WebSocket', required — The transport type for this subscription, or the channel by which an app should be notified of an event
  - `blacklistedData` object — Returned if a WebHook subscription is blacklisted
    - `blacklistedAt` string, date-time — Time of adding subscription to a black list in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format including timezone, for example *2016-03-10T18:07:52.534Z*
    - `reason` string — Reason of adding subscription to a black list

## Other responses

- `400` — General response with **HTTP 400 "Bad request"** status.<br> Reasons: unparsable request, path, query or body parameters are invalid. The error description may contain reference to particular parameter(s) which haven't passed the validation.
- `403` — General response with **HTTP 403 "Forbidden"** status.<br> Reasons: the requested operation is forbidden because of certain resource state, lack of permissions, feature unavailability, etc.
- `500` — General response with **HTTP 500 "Internal Server Error"** status.<br> Reasons: general server-side error.
- `503` — General response with **HTTP 503 "Service not available"** status.<br> Reasons: server cannot process the request because of being overloaded, misconfiguration or other issues.

---

[API](https://skmtc.net/ringcentral/apis/ringcentral-api.md) · [All operations](https://skmtc.net/ringcentral/apis/ringcentral-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ringcentral/ringcentral-api/revisions/8d602198ec97/schema)