Skip to main content

Developer API and Dynamic Links

When to use the AddCal REST API or Dynamic Links instead of Smart Links, and where to find the technical docs.

T
Written by Tom

AddCal gives you two programmatic ways to create add-to-calendar links at scale: the REST API and Dynamic Links. Most people never need either. If you only want a shareable link that always points at your latest event, use a Smart Link instead. Reach for the API or Dynamic Links when you are building automation or generating links from your own system.

Which one do I need?

You want to...

Use

Share one link that follows your latest event, no code

Smart Links

Create or update calendars, events, and RSVPs from your own code

REST API

Turn event details from your own system into an add-to-calendar link or picker page

Dynamic Links

For the no-code options, see Smart Links and Add-to-calendar links.

The REST API

The API lets you manage your calendars, events, RSVPs, and calendar invites programmatically. You authenticate each request with a personal API token (see below). The full endpoint reference, request formats, and examples live in the developer docs.

You can also send, list, resend, and cancel calendar invites for an event through the API, which suits automation or calling from a tool like Zapier via a custom API step. Calendar invites must be enabled on the event and are a paid feature (see Send calendar invites for an event).

When you create an RSVP or send a calendar invite through the API, you can pass an optional language so the emails AddCal sends that person are in their language. Without it, they are sent in English. See Send calendar invites for an event for the supported languages.

To see who subscribed to a calendar, use the subscribers endpoint. If you attach your own record ID to each subscription, you can filter the list by it to find the subscriber that belongs to a record in your system. See Match subscribers to your own records with external IDs.

Read the API documentation for the complete reference.

The API is free to use on every plan. The events you create through it count toward your plan's event limits, the same as events you add in the app.

To work with AddCal from an AI assistant instead of code, see Connect AddCal to AI assistants with the MCP server.

Create an event

POST to /api/events with title, date_start and date_end (on or after the start). Send dates in ISO 8601 format, for example 2026-08-12T14:00:00. Other useful fields are timezone, is_all_day, location, description, calendar_uid or calendar_name, and recurrence_rule. See the API documentation for every field.

Leave recurrence_rule out for a one-off event. A rule with no end creates up to 500 occurrences. On the Free plan each occurrence counts toward your 10 events a month, so add an end, for example FREQ=WEEKLY;COUNT=4. Premium and Business have no monthly event limit.

If a request would go over your monthly event limit, the API returns 409 with a message such as "This would create 12 events, but you only have 5 events left on your monthly event limit of 10.", plus limit, remaining, attempted and would_exceed_by. Check for it in automations so the workflow does not fail silently.

Formatting the description and location

description accepts basic HTML such as <p>, <br>, <b> and links. Unsafe tags are removed. Google Calendar shows the HTML. Other calendar apps show plain text, with paragraph breaks kept and links listed as numbered footnotes. For paragraph breaks that show everywhere, use <br><br> or a blank line between paragraphs.

Add-to-calendar buttons shorten long descriptions to about 1,000 characters and add a link to the full event page.

location is plain text, up to 2,048 characters. A meeting link such as a Zoom URL works as the location. For more on how descriptions look in each calendar app, see Format your event description.

Create an RSVP

POST a JSON body to /api/calendars/{calendar}/events/{event}/rsvps. Send both Accept: application/json and Content-Type: application/json. Without the Accept header, a validation error comes back as a redirect (302) instead of a readable error message.

Required fields are response_type (yes, maybe or no, or waitlist when the event has a waitlist), name and email. Put answers to the event's custom questions in custom_fields, keyed by each field's slug. The slug is created from the field's name when you first save the form: lowercase, with spaces turned into underscores and other symbols removed, so Company name becomes company_name. It does not change if you rename the field later, and if two fields would get the same slug, one is made unique. The form builder does not show the slug. An older flat data object is still accepted and treated the same way.

{  "response_type": "yes",  "name": "Sam Lee",  "email": "[email protected]",  "language": "de",  "custom_fields": {    "company": "Example Ltd",    "marketing_consent": true  }}

By default AddCal stores custom answers as sent. Add "strict": true to have them checked against the event's form, so required questions and formats are enforced and errors come back as a 422. The optional language sets the language of the emails that person receives (see above).

Getting an API token

To call the API you need an API token:

  1. Open API Tokens in your account settings (/user/api-tokens).

  2. Click Create API Token, give it a name, and create it.

  3. Copy the token immediately and store it somewhere safe. You will not be able to see it again.

Send the token as a bearer token in the Authorization header of each request. You can create more than one token (for example, one per integration) and delete any token from the same screen to revoke access.

Dynamic Links

Dynamic Links turn event details supplied as query parameters into an add-to-calendar link. Instead of creating an event in AddCal first, you build a link that carries the event title, dates, and other details, and AddCal generates the calendar action on the fly. This suits systems that produce one-off events per visitor (for example, a confirmation page after a purchase).

Dynamic Links are a Business plan feature. You authenticate them with a Dynamic Link Key, which you create and manage on the Dynamic Links page in your integrations settings. Each key is tied to your team.

Choosing the calendar upfront, or letting the recipient pick

A Dynamic Link comes in two shapes, depending on whether you set the optional service parameter (google, apple, outlook, outlook_web, office365, yahoo, ics, or manual):

  • Set service and the visitor goes straight into that calendar app, with the event prefilled. Use this when you already know which calendar someone uses, or when you want to offer one link per calendar app.

  • Leave service off and the visitor lands on an AddCal picker page (/dynamic-links/choose) that carries your event details through in the query string, then chooses their own calendar.

The picker page shows the event title, the date and time (with a timezone selector when the event is not all-day), the location if you supplied one, and an Add to Calendar section with buttons for Google Calendar, Apple Calendar, Outlook (desktop), Outlook.com, Office 365, Yahoo Calendar, and Download .ics.

Use the picker page when you are sending links through WhatsApp or another in-app browser, which cannot reliably open a direct calendar link (see Adding events from WhatsApp, Instagram or Facebook). It is also the safer choice for one link that works everywhere. The picker page is Business plan only, the same as the rest of Dynamic Links.

Each key has its own analytics page (also Business plan only). Open it from the Dynamic Links page to see, for the date range you choose:

  • Total and unique clicks, average daily clicks, and clicks over time.

  • Calendar service split: which services people added events to (for example Google, Apple, or Office 365).

  • Event breakdown: the events each link described, ranked by clicks.

  • Visitor details: referrers, countries, devices, browsers, and UTM parameters.

You do not have to assemble the URL by hand. The Link Builder in the app walks you through the event details, encodes the link correctly, and hands you both a landing page link that works everywhere and one link per calendar app. Copy the landing page link if you want a single link for everyone, or copy the per-app links to send people straight into their calendar. For the parameter list and link format, read the Dynamic Links documentation.

If you generate these links inside an email or automation tool, use merge fields so each recipient gets their own event details. Pick your platform in the Link Builder and it leaves the merge fields intact while encoding the rest of the link.

See Using merge fields with Smart Links and Dynamic Links for the full walkthrough, including why the link needs encoding.

Related

If you would rather react to events in AddCal than push data in, see the webhooks article in this collection. To place a calendar directly in a page, see Embed a calendar on your website.

Did this answer your question?