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

This API function requires that your application be authenticated via OAuth. You can learn how to authenticate your application here.

Subscription Parameters

ParameterTypeDescription
subscriberId

Optional
StringIdentifier that represents a unique user to you. E.g. email address, device id, anonymous id
emailAddress

Optional
StringEmail address linked to the subscription. Rokt Calendar allows you to capture the the email address of a subscriber so that you can market to the subscriber at a later date.
additionalOptIn

Optional
BooleanAdditional opt-in allows the subscriber to specify if they are opting-in to the question/statement as defined by the copy associated with the checkbox.
redirectTo

Required
StringA url to redirect user to with subscription result after a Google subscription e.g. confirmation page, app deep link
calendarTags

Optional
CalendarTags[]Array of calendar tags to filter events by. Tags are used to group similar events. For example all events that belong to the same sporting team/topic can be tagged with a team name.

When a tagId is used, the subscription will only include events tagged with the selected tag.

See Calendar Tag Model below for complete schema.
timeZoneId

Optional
StringWindows timezone identifier to filter events by. If used, the subscription will include events that are tagged with this time zone and any events that are not tagged with a time zone.

See Timezones for available list.
requestEventIds

Optional
String[]
(UUID/GUID)
An array of event identifiers. Identifiers that do not match will be ignored.
externalEventIds

Optional
String[]One or more identifiers that represents unique events to you. Identifiers that do not match will be ignored.
utmSource

Optional
StringValue used to identify the referring subscriber Source. This is used as the UTM Source in Dashboard Analytics. e.g. Newsletter-December.
utmMedium

Optional
StringValue used to identify the referring subscriber Medium. This is used as the UTM Source in Dashboard Analytics. e.g. Email
utmContent

Optional
StringValue used to identify the referring subscriber Content. Used for Dashboard Analytics. in Dashboard Analytics. e.g. 400x300 banner
utmCampaign

Optional
StringValue used to identify the referring subscriber Campaign. in Dashboard Analytics. e.g. Summer Campaign
userAgent

Optional
StringUser agent of the user. This is required to determine the if it should be a WebCal or Google subscription. The user agent string extracted from the http header of the API request. This is used to identify the users operating system, device and other important parameters.

Required if no subscriptionMethod value is passed through
urlReferrer

Optional
StringUrl referrer of the user. Used for Dashboard Analytics. The place from which the subscriber navigated to the calendar page. e.g. Facebook
ipAddress

Optional
StringIP Address of the user. Used for monitoring and logging purposes
subscriptionMethod

Required
StringUsed when you want to bypass our subscription flow choice and tell us which one to use. Value can only be WebCal, Google or Microsoft
Events

Optional
EventDetails[]You can add manual events to this subscription that belong solely to this subscription.

Response

The response will vary depending on the subscription type determined by the server or specified by you.

WebCal

The following is response body that will be returned from a WebCal subscription flow.

ParameterTypeDescription
success

Always present
BooleanRepresents if the create subscription was successful
statusCode

Always present
NumberHTTP error codes if request was not successful
errors

Always present
ErrorModel[]List of errors if request was not successful

See Error Model below for complete schema.
subscriptionType

Sometimes Present
StringValue that represents the type of subscription created if the request was successful. Currently only Webcal, Google or Microsoft
subscriptionId

Sometimes Present
UUID/GUIDUnique identifier of the subscription if request was successful
subscriptionUrl

Sometimes Present
StringUrl to the WebCal Subscription if request was successful
isNewSubscription

Sometimes Present
BooleanRepresents if this was a new or existing subscription if request was successful
subscriberId

Sometimes Present
StringIdentifier that represents a unique user to you. E.g. email address, device id, anonymous id

If successful, the caller will need to prompt the user to add the subscription to their calendar by opening the subscriptionUrl in a window. The recommended way to do this in a website is by using javascript.

<script type="text/javascript">
  	window.location = response.subscriptionUrl;
</script>

📘

Note

A user can cancel the native prompt to add a calendar. It is recommended that you have a way i.e. link, for the user to retry adding the the calendar should they cancel the native prompt.

Google/Microsoft

A Google/Microsoft subscription initially requires the user to authorize us to have access to their Google/Microsoft Calendar, once this is done the flow will be essentially the same as a WebCal.

New Subscription
Before we can create the subscription, the user must be redirected to Google/Microsoft OAuth Consent Form, to authorize us. In this case the response of a Create Subscription will return the following. If successful, you must redirect the user to the url in the redirectTo property.

ParameterTypeDescription
success

Always Present
BooleanRepresents if the create subscription was successful
statusCode

Always Present
NumberHTTP error codes if request was not successful
errors

Always Present
String[]List of json serialized errors if request was not successful

See Error Model below for complete schema.
subscriptionType

Always Present
StringValue that represents the type of subscription created if the request was successful. Currently only WebCal, Google or Microsoft
subscriberId

Sometimes Present
StringIdentifier that represents a unique user to you. E.g. email address, device id, anonymous id
redirectTo

Always Present
StringRedirect url to the Google OAuth Consent Form

After the user has selected an option on the consent form we will redirect the user back to the caller using the redirectTo url provided in the request. The response will be exactly the same as the response for Existing Subscription, below.

Existing Subscription
If an existing subscription is found, the OAuth consent does not need to be repeated. In this case we simply update the subscription and the response of a Create Subscription will return the following.

ParameterTypeDescription
success

Always Present
BooleanRepresents if the create subscription was successful
statusCode

Always Present
NumberHTTP error codes if request was not successful
errors

Always Present
String[]List of error messages if request was not successful
subscriptionType

Always Present
StringValue that represents the type of subscription created if the request was successful. Currently only WebCal, Google or Microsoft
subscriptionId

Sometimes Present
UUID/GUIDUnique identifier of the subscription if request was successful
isNewSubscription

Sometimes Present
BooleanRepresents if this was a new or existing subscription if request was successful
subscriberId

Sometimes Present
StringIdentifier that represents a unique user to you. E.g. email address, device id, anonymous id
Language
Authorization
Basic
base64
: