Calendar API

Overview

The Rokt Calendar API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

Authentication

Rokt Calendar uses the OAuth 2.0 protocol to allow websites or applications to request authorization to access protected calendars without requiring the account user name and password.

API registration

To authenticate using OAuth you have to be a registered OAuth Application. Your application will be issued with a unique client_id and client_secret. These details will be required for your application to authenticate when requesting an access token.

The API is available upon request. Please contact your account manager to request access. You will then be provided with a unique client_id and a client_secret.

Go to:

OAuth details

Rokt Calendar OAuth supports the client_credentials grant type.
OAuth requests are only served over HTTPS.
Access tokens expire after five minutes (subject to changes in production environment). For best results, don’t rely on this amount. Instead, use the dynamic value returned in expires_in.
Refresh tokens expire after 60 minutes (subject to changes in production environment).

Sample request

With authorization header

curl -vX POST https://api.roktcalendar.com/oauth2/token \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header 'Accept: application/json' \
    --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
    -d grant_type=client_credentials'

Without authorization header

curl -vX POST https://api.roktcalendar.com/oauth2/token \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --header 'Accept: application/json' \
    -d 'grant_type=client_credentials&client_id=johnsmithmedia&client_secretpassword'

Request fields

Key	In	Description	Required?	Example
`Authorization`	header	`client_id` and `client_secret` must be included in the authorization header through Basic HTTP authorization and will be provided by your account manager; the header content is `Basic base64encode(client_id:client_secret)`	Yes	Basic base64encocde(12345:abcde)
`Content-Type`	header	Media type of request must always be `application/X-www-form-urlencoded`	Yes	application/X-www-form-urlencoded
`grant_type`	body	Must be `client_credentials`	Yes	client_credentials
`client_id`	body	Your client ID (mandatory if no authorization header)	No	username
`client_secret`	body	Your client secret (mandatory if no authorization header)	No	password

Sample response

{
  "access_token": "eyJraWQiOiJPVUpHT1RjM09FWXROakkzUlMwME5UUkJMVGxCTkRrdFJqWXdOVVV3UkRNNE1FTTJDZz09IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiJkZW1vIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJyZXBvcnQtYXBpL3JlYWQtcmVwb3J0LWFwaSIsImF1dGhfdGltZSI6MTU4NTExMDA0MSwiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS91cy13ZXN0LTJfZG93Tlp1elRYIiwiZXhwIjoxNTg1MTEzNjQxLCJpYXQiOjE1ODUxMTAwNDEsInZlcnNpb24iOjIsImp0aSI6IkYwNzY5RDVDLTRDNTAtNDVDOC04OTcyLTI4MkUwODlDMkFFOSIsImNsaWVudF9pZCI6ImRlbW8ifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA",
  "refresh_token": "eyJraWQiOiJPVUpHT1RjM09FWXROakkzUlMwME5UUkJMVGxCTkRrdFJqWXdOVVV3UkRNNE1FTTJDZz09IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiJkZW1vIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJyZXBvcnQtYXBpL3JlYWQtcmVwb3J0LWFwaSIsImF1dGhfdGltZSI6MTU4NTExMDA0MSwiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS91cy13ZXN0LTJfZG93Tlp1elRYIiwiZXhwIjoxNTg1MTEzNjQxLCJpYXQiOjE1ODUxMTAwNDEsInZlcnNpb24iOjIsImp0aSI6IkYwNzY5RDVDLTRDNTAtNDVDOC04OTcyLTI4MkUwODlDMkFFOSIsImNsaWVudF9pZCI6ImRlbW8ifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA",
  "expires_in": 3600,
  "token_type": "Bearer"
}

API Endpoints

DELETE Deactivate Subscriptions

Deactivate all subscriptions and remove all events from calendars associated with a user name.

Description

The Deactivate Subscription API function disables a subscription from receiving any events in the future. Once a subscription has been deactivated, any new events published will not appear in their calendar.

You can either specify an individual subscription or all subscriptions that belong to a user name for a calendar.

This API function is protected by OAuth and must include an access token in the same way it is required to create a subscription.

Request

Path

DELETE /v1/subscription/{accountCode}/{calendarCode}

Parameters

Name	Type	In	Description	Required	Example
`accountCode`	String	path	The Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.	true
`calendarCode`	String	path	This is a unique identifier of a specific calendar in your Rokt Calendar account. It is the URL slug that appears directly after the domain.	true	if your calendar URL is http://youraccount.roktcalendar.com/my-calendar then the `calendarCode` will be `my-calendar`.

Request body

{
  "userName": "string",
  "id": "string",
  "unsubscribeReasonId": null,
  "unsubscribeReasonText": "string",
  "actionType": "string"
}

Response

202 Accepted

Error

400 BadRequest

401 Unauthorized

DELETE Calendar Subscription Event

Use this endpoint to programmatically delete a calendar subscription event.

Description

This API endpoint will delete an event and update all calendar subscriptions that subscribe to this event. Associated Google subscriptions will be synced. The response of 202 Accepted indicates that the response was successfully validated and has been accepted for processing. Events are deleted in a background process, and it can take a few minutes for changes to propagate to subscribers' calendars.

Request

Path

DELETE /v1/subscriptionevent/{accountCode}/{eventId}

Parameters

Name	Type	In	Description	Required
`accountCode`	String	path	The Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.	true
`eventId`	String	path	A unique identifier for the event.	true

Response

202 Accepted

Error

400 BadRequest

500 InternalServerError

DELETE Subscription Event

Use the API to programmatically remove a subscription event from a subscription.

Description

This API function is used to remove a subscription event from a subscription.

Request

Path

DELETE /v2/subscription/{accountCode}/{subscriptionId}/subscriptionevent/{eventId}

Parameters

Name	Type	In	Description	Required
`accountCode`	String	path	The Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.	true
`subscriptionId`	String	path	The unique ID of the subscription.	true
`eventId`	String	path	The unique ID for the event.	true

Response

202 Accepted

Error

400 BadRequest

GET Calendar Events

Use the API to programatically retrieve available calendar events

Request

Path

GET /v1/{accountCode}/calendars/{calendarId}/events

Parameters

Name	Type	In	Description	Required
`accountCode`	String	path	The Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.	true
`calendarId`	String	path	This is a unique identifier of a specific calendar in your Rokt Calendar account.	true
`pageNumber`	integer	query	The number of the data page you watch to receive, starting with 1.
`pageSize`	integer	query	Number of results in a page of data you wish to receive. Must be greater than 0.

Response

200 OK

{
  "result": {
    "data": [
      {
        "id": "string",
        "title": "string",
        "description": "string",
        "location": "string",
        "reminderMinutes": null,
        "timezoneBclId": "string",
        "timezoneIanaId": "string",
        "startDateTimeUtc": "2025-10-04T10:00:00.000Z",
        "startDateTimeLocal": "2025-10-04T10:00:00.000Z",
        "endDateTimeLocal": "2025-10-04T10:00:00.000Z",
        "lastUpdateDateTimeUtc": "2025-10-04T10:00:00.000Z",
        "calendarTags": [
          {
            "id": "string",
            "text": "string"
          }
        ],
        "calendarTimezones": [
          {
            "bclId": "string",
            "ianaId": "string",
            "offsetMinutes": null
          }
        ],
        "calendarCustomFields": [
          {
            "name": "string",
            "label": "string",
            "url": "string",
            "imageUrl": "string"
          }
        ]
      }
    ],
    "totalResults": null,
    "pageNumber": null,
    "pageSize": null,
    "totalPages": null
  },
  "errors": [
    {
      "type": "string",
      "message": "string",
      "code": "string"
    }
  ],
  "success": true
}

Error

401 Unauthorized

404 NotFound

GET Subscription Schedule

Use the API to programmatically get events for a specific date range that live in the subscriber's primary calendar.

Request

Path

GET /v1/schedule/{subscriptionId}

Parameters

Name	Type	In	Description	Required
`subscriptionId`	String	path	This is a GUID and represents the unique identifier for a specific subscription.	true
`from`	String	query	The UTC start date of the date range query
`to`	String	query	The UTC end date of the date range query

Response

200 OK

{
  "title": "string",
  "startUtc": "2025-10-04T10:00:00.000Z",
  "endUtc": "2025-10-04T10:00:00.000Z",
  "isAllDayEvent": true
}

Error

401 Unauthorized

404 NotFound

GET Subscription Details

Use the API to programmatically Get Subscription Details.

Request

Path

GET /v1/subscription/{subscriptionId}

Parameters

Name	Type	In	Description	Required	Example
`subscriptionId`	String	path	This is the subscriptionId returned from the Create New subscription API function.	true

Response

200 OK

{
  "subscriptionId": "string",
  "calendar": {
    "id": "string",
    "code": "string",
    "name": "string",
    "image": "string"
  },
  "tags": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "timezoneId": "string",
  "subscriptionType": "string",
  "subscriberId": "string",
  "emailAddress": "string",
  "marketingAllowed": true,
  "providerName": "string",
  "channelFinderLineUpId": "string",
  "channelFinderZipCode": "string",
  "createdAt": "2025-10-04T10:00:00.000Z",
  "isActive": true,
  "deactivatedDate": "2025-10-04T10:00:00.000Z",
  "events": [
    {
      "id": "string",
      "name": "string",
      "externalId": "string",
      "isExcluded": true
    }
  ],
  "eventsVisibleToSubscription": [
    {
      "title": "string",
      "location": "string",
      "description": "string",
      "subscriptionEventId": "string",
      "calendarEventId": "string",
      "timezone": "string",
      "timezoneIanaId": "string",
      "startDateTime": "2025-10-04T10:00:00.000Z",
      "startDateTimeUtc": "2025-10-04T10:00:00.000Z",
      "endDateTime": "2025-10-04T10:00:00.000Z",
      "allDayEvent": true,
      "reminderMinutes": null,
      "merchantId": "string",
      "accountId": "string",
      "eventOccurrenceType": 0,
      "isSubscriptionEvent": true,
      "recurrenceFrequency": null,
      "recurrenceUntilDateTime": "2025-10-04T10:00:00.000Z",
      "recurrenceUntilCount": null,
      "recurrenceInterval": null,
      "recurrenceWeeklyDays": null,
      "recurrenceMonthlyDayOfWeek": true
    }
  ],
  "eventReminderMinutes": null,
  "allowPromotionalContent": true,
  "additionalOptIn": true,
  "isEventReminderDisabled": true
}

Error

400 BadRequest

POST Update Subscription Event

Use the endpoint to programmatically create a calendar subscription event and add it to one or more calendar subscriptions.

Description

This API endpoint will update event details and update all calendar subscriptions that subscribe to this event. Associated subscriptions will be synced. The response of 202 Accepted indicates that the response was successfully validated and has been accepted for processing. Events are being updated in a background process, it can take up to few minutes for changes to propagate to subscribers' calendars.

Request

Path

POST /v1/subscriptionevent/{accountCode}/update

Parameters

Name	Type	In	Description	Required
`accountCode`	String	path	The Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.	true

Request body

{
  "eventId": "string",
  "title": "string",
  "description": "string",
  "location": "string",
  "timezone": "string",
  "timezoneIanaId": "string",
  "start": "2025-10-04T10:00:00.000Z",
  "end": "2025-10-04T10:00:00.000Z",
  "allDayEvent": true,
  "notifyBefore": null,
  "actionType": "string",
  "visibleFromDateTimeUtc": "2025-10-03T10:00:00.000Z" // optional
}

Response

202 Accepted

Error

400 BadRequest

500 InternalServerError

POST Create New Subscription Event

Use the endpoint to programmatically create a calendar subscription event and add it to one or more calendar subscriptions.

Description

This API endpoint will create an event and attach it to one or more calendar subscriptions. The response of 202 Accepted indicates that the response was successfully validated and has been accepted for processing. Events are being created in a background process, it can take up to few minutes for changes to propagate to subscribers' calendars.

Request

Path

POST /v1/subscriptionevent/{accountCode}

Parameters

Name	Type	In	Description	Required	Example
`accountCode`	String	path	The Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL	true

Request body

{
  "event": {
    "eventId": "string",
    "title": "string",
    "description": "string",
    "location": "string",
    "timezone": "string",
    "timezoneIanaId": "string",
    "start": "2025-10-04T10:00:00.000Z",
    "end": "2025-10-04T10:00:00.000Z",
    "allDayEvent": true,
    "notifyBefore": null,
    "actionType": "string",
    "visibleFromDateTimeUtc": "2025-10-03T10:00:00.000Z" // optional
  },
  "subscriptionIds": [
    "string"
  ],
  "actionType": "string"
}

Response

202 Accepted

Error

400 BadRequest

500 InternalServerError

POST Create New Subscription

Use the API to programatically create a calendar subscription for Webcal and Google.

Request

Path

POST /v2/subscribe/{accountCode}/{calendarCode}

Parameters

Name	Type	In	Description	Required
`accountCode`	String	path	The Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.	true
`calendarCode`	String	path	This is a unique identifier of a specific calendar in your Rokt Calendar account.	true

Request body

{
  "redirectUrl": "string",
  "authCode": "string",
  "tagId": "string",
  "calendarTags": [
    {
      "internalId": "string",
      "externalId": "string"
    }
  ],
  "timeZoneId": "string",
  "marketingAllowed": true,
  "additionalOptIn": true,
  "allowPromotionalContent": true,
  "eventReminderMinutes": null,
  "isEventReminderDisabled": true,
  "channelFinderZipCode": "string",
  "channelFinderLineUpId": "string",
  "sourceId": null,
  "networkDevice": "string",
  "providerName": "string",
  "providerLocation": "string",
  "stationNum": null,
  "stationName": "string",
  "utmSource": "string",
  "utmMedium": "string",
  "utmCampaign": "string",
  "utmContent": "string",
  "requestEventIds": [
    "string"
  ],
  "externalEventIds": [
    "string"
  ],
  "clickId": "string",
  "urlReferrer": "string",
  "userAgent": "string",
  "ipAddress": "string",
  "redirectTo": "string",
  "userName": "string",
  "subscriberId": "string",
  "emailAddress": "string",
  "trackingId": "string",
  "sessionId": "string",
  "roktSessionId": "string",
  "subscriptionMethod": 0,
  "events": [
    {
      "eventId": "string",
      "title": "string",
      "description": "string",
      "location": "string",
      "timezone": "string",
      "timezoneIanaId": "string",
      "start": "2025-10-04T10:00:00.000Z",
      "end": "2025-10-04T10:00:00.000Z",
      "allDayEvent": true,
      "notifyBefore": null,
      "actionType": "string"
    }
  ],
  "actionType": "string"
}

Response

200 OK

{
  "subscriptionId": "string",
  "subscriptionUrl": "string",
  "username": "string",
  "password": "string",
  "isNewSubscription": true,
  "subscriberId": "string",
  "redirectTo": "string",
  "subscriptionType": 0,
  "success": true,
  "statusCode": 100,
  "message": "string",
  "errors": [
    {
      "code": "string",
      "reason": "string"
    }
  ]
}

Error

401 Unauthorized

404 NotFound

Overview​

Authentication​

API registration​

OAuth details​

Sample request​

With authorization header​

Without authorization header​

Request fields​

Sample response​

API Endpoints​

DELETE Deactivate Subscriptions​

Description​

Request​

Response​

Error​

DELETE Calendar Subscription Event​

Description​

Request​

Response​

Error​

DELETE Subscription Event​

Description​

Request​

Response​

Error​

GET Calendar Events​

Request​

Response​

Error​

GET Subscription Schedule​

Request​

Response​

Error​

GET Subscription Details​

Request​

Response​

Error​

POST Update Subscription Event​

Description​

Request​

Response​

Error​

POST Create New Subscription Event​

Description​

Request​

Response​

Error​

POST Create New Subscription​

Request​

Response​

Error​

Overview

Authentication

API registration

OAuth details

Sample request

With authorization header

Without authorization header

Request fields

Sample response

API Endpoints

DELETE Deactivate Subscriptions

Description

Request

Response

Error

DELETE Calendar Subscription Event

Description

Request

Response

Error

DELETE Subscription Event

Description

Request

Response

Error

GET Calendar Events

Request

Response

Error

GET Subscription Schedule

Request

Response

Error

GET Subscription Details

Request

Response

Error

POST Update Subscription Event

Description

Request

Response

Error

POST Create New Subscription Event

Description

Request

Response

Error

POST Create New Subscription

Request

Response

Error