If you subscribe people to an AddCal calendar from your own platform, you can attach your own identifier (a CRM contact id, a member id) to each subscription. AddCal stores that external ID with the subscription and gives it back to you on webhooks and through the subscribers API, so you can match a calendar subscriber to the record they came from.

This only applies to calendar subscriptions. Adding a single event to someone's calendar does not create a subscription, so there is nothing to attach an ID to.

There are two ways to send one, and both land on the same value.

On a calendar embed or subscribe button. Add a data-external-id attribute to the element:

This needs calendar.min.js 3.4.3 or later for the embed, or button.min.js 1.6.2 or later for the subscribe button. It also works on the headless popup trigger (data-addcal-headless), and on calendars that have subscriber information collection turned on. See Embed a calendar on your website and Collecting subscriber information.

On the hosted calendar page. No embed required. Add external_id to the query string of the calendar link you send people:

AddCal trims the value, then accepts it only if it is 1 to 191 characters long and every character is a letter, a number, or one of . _ : -. The pattern is ^[A-Za-z0-9._:-]+$.

This is the part worth your attention. If the value does not match the shape above, AddCal discards it and the subscribe still succeeds. You get no error, no 4xx response, and nothing in the response telling you the ID was rejected.

That is deliberate. The person subscribing is a real visitor, and an ID that only matters to the integration behind them should not break their subscribe.

The consequence is that a bad ID shows up much later, as a missing field on a webhook, possibly days after the subscribe. An email address, a base64 token, or anything over 191 characters will never arrive, and the first sign is a subscriber you cannot match to a record. Validate the shape in your own code before you send it.

Sending the same external ID twice on one calendar creates two subscriptions, not one. AddCal does not collapse them. Repeat subscribes are normal for integrations that retry, so handle duplicate IDs on your side when you reconcile.

There are two ways to get the value out again.

Webhooks. The external ID is included in the subscription payload the calendar.subscribed webhook already sends, so it arrives in your existing webhooks with no extra setup. See Webhooks.

The subscribers API. List the subscribers on a calendar with:

Authenticate with your API token, sent as a bearer token in the Authorization header, the same as the rest of the REST API. See Developer API and Dynamic Links for how to create a token, and the API documentation for the full request and response reference.

Unlike the subscribe path, the subscribers endpoint rejects a malformed external_id with a 422 response:

That is deliberate too. It is the one place you can find out your IDs are the wrong shape. If you are not sure a value will be accepted, query it against this endpoint first and check whether you get a 422.

To see and export subscribers in the app rather than through the API, see Manage calendar subscribers.