Skip to main content

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

KeyInDescriptionRequired?Example
Authorizationheaderclient_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)YesBasic base64encocde(12345:abcde)
Content-TypeheaderMedia type of request must always be application/X-www-form-urlencodedYesapplication/X-www-form-urlencoded
grant_typebodyMust be client_credentialsYesclient_credentials
client_idbodyYour client ID (mandatory if no authorization header)Nousername
client_secretbodyYour client secret (mandatory if no authorization header)Nopassword

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

NameTypeInDescriptionRequiredExample
accountCodeStringpathThe Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.true 
calendarCodeStringpathThis is a unique identifier of a specific calendar in your Rokt Calendar account. It is the URL slug that appears directly after the domain.trueif your calendar URL is https://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

NameTypeInDescriptionRequired
accountCodeStringpathThe Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.true
eventIdStringpathA 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

NameTypeInDescriptionRequired
accountCodeStringpathThe Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.true
subscriptionIdStringpathThe unique ID of the subscription.true
eventIdStringpathThe 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

NameTypeInDescriptionRequired
accountCodeStringpathThe Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.true
calendarIdStringpathThis is a unique identifier of a specific calendar in your Rokt Calendar account.true
pageNumberintegerqueryThe number of the data page you watch to receive, starting with 1. 
pageSizeintegerqueryNumber 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

NameTypeInDescriptionRequired
subscriptionIdStringpathThis is a GUID and represents the unique identifier for a specific subscription.true
fromStringqueryThe UTC start date of the date range query 
toStringqueryThe 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

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

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

NameTypeInDescriptionRequiredExample
accountCodeStringpathThe Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URLtrue 

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

NameTypeInDescriptionRequired
accountCodeStringpathThe Rokt Calendar merchant account code, or the subdomain of your Rokt Calendar dashboard URL.true
calendarCodeStringpathThis 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

Was this article helpful?