Create New Webcal Subscription

Use the API to programatically create a calendar subscription using the Webcal protocol

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

calendarParams

Name	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.
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 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
utmCampaign Optional	String	Value used to identify the referring subscriber Campaign. in Dashboard Analytics. e.g. Summer Campaign
utmContent Optional	String	Value used to identify the referring subscriber Content. Used for Dashboard Analytics. in Dashboard Analytics. e.g. 400x300 banner
userAgent Optional	String	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.
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
events Optional	EventDetails[]	You can add manual events to this subscription that belong solely to this subscription.

Protected Calendars

Rokt Calendar supports the ability to mark calendars as protected. Calendars can be marked as protected by emailing [email protected] with a special request.

Protected calendars have the following properties:

• Protected calendars are hidden and are not accessible via a public calendar URL
• Subscribing to a protected calendar must occur via the Rokt Calendar API
• Protected calendars require basic http authentication. Forcing basic authentication ensures that webcal URLs on iOS devices cannot be shared since the webcal password is masked after a user subscribes from an in-app experience.

Protected calendars require that the calendarParams object contains the username field. For iOS users, the username will appear under the Subscribe Calendar Information section, and the password will be randomly generated and masked.

Here is an example:

Returns

A webcal URL containing a subscriptionId as a GUID. The subscription ID is a unique subscription identifier.

Protected calendars return a webcal URL containing a subscriptionId as a GUID, prefixed with the username and password required for basic http authentication. The URL for a protected calendar will contain a randomly generated username and password as part of the url in the format of {username}:{password}.

🚧

The webcal subscription API function should be used to add new calendar subscription on iOS devices and for Microsoft Outlook users. This function is not compatible with Google Calendar.

📘

Recommendation

It is recommended that you extract this GUID from the URL returned and store it against the users profile information in your own database.

📘

Tip

To deactivate subscribers please see the information in this section Deactivate an Existing Subscription