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
| Parameter | Type | Description |
|---|---|---|
| subscriberId Optional | String | Identifier that represents a unique user to you. E.g. email address, device id, anonymous id |
| emailAddress Optional | String | Email 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 | Boolean | Additional 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 | String | A 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 | String | Windows 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 | String | Value used to identify the referring subscriber Source. This is used as the UTM Source in Dashboard Analytics. e.g. Newsletter-December. |
| utmMedium Optional | String | Value used to identify the referring subscriber Medium. This is used as the UTM Source in Dashboard Analytics. e.g. Email |
| utmContent Optional | String | Value used to identify the referring subscriber Content. Used for Dashboard Analytics. in Dashboard Analytics. e.g. 400x300 banner |
| utmCampaign Optional | String | Value used to identify the referring subscriber Campaign. in Dashboard Analytics. e.g. Summer Campaign |
| userAgent Optional | String | User 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 | String | Url referrer of the user. Used for Dashboard Analytics. The place from which the subscriber navigated to the calendar page. e.g. Facebook |
| ipAddress Optional | String | IP Address of the user. Used for monitoring and logging purposes |
| subscriptionMethod Required | String | Used 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.
| Parameter | Type | Description |
|---|---|---|
| success Always present | Boolean | Represents if the create subscription was successful |
| statusCode Always present | Number | HTTP 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 | String | Value that represents the type of subscription created if the request was successful. Currently only Webcal, Google or Microsoft |
| subscriptionId Sometimes Present | UUID/GUID | Unique identifier of the subscription if request was successful |
| subscriptionUrl Sometimes Present | String | Url to the WebCal Subscription if request was successful |
| isNewSubscription Sometimes Present | Boolean | Represents if this was a new or existing subscription if request was successful |
| subscriberId Sometimes Present | String | Identifier 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.
| Parameter | Type | Description |
|---|---|---|
| success Always Present | Boolean | Represents if the create subscription was successful |
| statusCode Always Present | Number | HTTP 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 | String | Value that represents the type of subscription created if the request was successful. Currently only WebCal, Google or Microsoft |
| subscriberId Sometimes Present | String | Identifier that represents a unique user to you. E.g. email address, device id, anonymous id |
| redirectTo Always Present | String | Redirect 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.
| Parameter | Type | Description |
|---|---|---|
| success Always Present | Boolean | Represents if the create subscription was successful |
| statusCode Always Present | Number | HTTP error codes if request was not successful |
| errors Always Present | String[] | List of error messages if request was not successful |
| subscriptionType Always Present | String | Value that represents the type of subscription created if the request was successful. Currently only WebCal, Google or Microsoft |
| subscriptionId Sometimes Present | UUID/GUID | Unique identifier of the subscription if request was successful |
| isNewSubscription Sometimes Present | Boolean | Represents if this was a new or existing subscription if request was successful |
| subscriberId Sometimes Present | String | Identifier that represents a unique user to you. E.g. email address, device id, anonymous id |