# AddCal API Documentation

The official AddCal API documentation. This comprehensive guide provides developers with everything needed to integrate calendar and event management functionality into their applications. Our RESTful API enables seamless creation, management, and sharing of events across multiple platforms and calendar services.

- Base URL: `https://addcal.co`
- Authentication: HTTP Bearer token. You can retrieve your token from the [API Tokens page](https://addcal.co/user/api-tokens) in your dashboard.
- OpenAPI document: https://addcal.co/docs.openapi
- Interactive reference: https://addcal.co/docs

Send the token on every request:

```
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

## Sections

- [Create Event](https://addcal.co/docs/create-event.md)
- [Calendars](https://addcal.co/docs/calendars.md)
- [Calendars > Subscribers](https://addcal.co/docs/subscribers.md)
- [Events](https://addcal.co/docs/events.md)
- [Events > RSVPs](https://addcal.co/docs/rsvps.md)
- [Events > Invites](https://addcal.co/docs/invites.md)
- [Account](https://addcal.co/docs/account.md)
- [Dynamic Links](https://addcal.co/docs/dynamic-links.md)
- [Endpoints](https://addcal.co/docs/endpoints.md)

## Events > RSVPs

APIs for managing event RSVP responses.

## Working with Custom Form Fields

Events can have custom forms with additional fields beyond the standard `name` and `email`. To create an RSVP with custom field data:

1. First, fetch the event details using the **Get Event** endpoint (`GET /api/calendars/{calendar}/events/{event}`)
2. Check the `custom_form` object in the response - it contains a `fields` array with all form fields
3. Use each field's `slug` property as the key when submitting custom field data

### Example Workflow

```
GET /api/calendars/cal_abc123/events/evt_xyz789

Response:
{
  "data": {
    "custom_form": {
      "fields": [
        { "slug": "company", "label": "Company Name", "field_type": "text", "is_required": false },
        { "slug": "dietary_requirements", "label": "Dietary Requirements", "field_type": "dropdown", "is_required": true,
          "options": [{ "label": "Vegetarian", "value": "vegetarian" }, { "label": "None", "value": "none" }] }
      ]
    }
  }
}
```

Then create the RSVP, passing the custom field values in `custom_fields`, keyed by slug:

```
POST /api/calendars/cal_abc123/events/evt_xyz789/rsvps

{
  "name": "John Doe",
  "email": "john@example.com",
  "response_type": "yes",
  "custom_fields": {
    "company": "Acme Inc",
    "dietary_requirements": "vegetarian"
  }
}
```

For fields of type `name_field` and `email_field`, send the value as the top-level `name` / `email`
instead of inside `custom_fields`.

### Strict validation (opt-in)

By default the API is lenient: `custom_fields` are stored as sent, without enforcing the form's
required fields, option lists, or field types. This keeps existing integrations working.

Pass `"strict": true` to validate the submission exactly like the public RSVP form: fields marked
`is_required` must be present, `dropdown`/`radio` values must be one of the field's `options[].value`,
and typed fields (e.g. `marketing_consent`) must match their type. Note `marketing_consent` values
must be a JSON boolean (`true`/`false`), not a string like `"True"`.

Earlier versions of this API accepted these values as a flat `data` object. That shape is still
accepted, but it is deprecated: prefer `custom_fields`.

### List RSVPs

`GET /api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps`

**Path parameters**

- `calendar_public_id` (string, required): The ID of the calendar public.
- `event_public_id` (string, required): The ID of the event public.

**Query parameters**

- `response_type` (string, optional): Filter by response type. Options: 'yes', 'maybe', 'no', 'waitlist'
- `search` (string, optional): Search RSVPs by name or email
- `per_page` (integer, optional): Number of results per page (1-100)

**Body parameters** (`application/json`)

- `response_type` (string, optional): No description. Options: `yes`, `maybe`, `no`, `waitlist`.
- `search` (string, optional): Must not be greater than 255 characters.
- `per_page` (integer, optional): Must be at least 1. Must not be greater than 100.

**Example request**

```bash
curl --request GET \
  --url 'https://addcal.co/api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'
```

**Response 200**

```json
{
    "data": [
        {
            "uid": "f57031ac-ace3-41d7-b631-6a82a32ca805",
            "public_id": "rsvp_f57031ac-ace3-41d7-b631-6a82a32ca805",
            "event_uid": "xdakful6xd0s",
            "response_type": "yes",
            "waitlist_position": null,
            "name": "Christa Dare",
            "email": "juwan53@yahoo.com",
            "data": {
                "guests": 0,
                "comment": null
            },
            "formatted_created_at": "2026-10-28 23:12:04",
            "created_at": "2026-10-28T23:12:04.000000Z",
            "updated_at": "2026-10-28T23:12:04.000000Z",
            "event": {
                "uid": "xdakful6xd0s",
                "public_id": "evt_xdakful6xd0s",
                "calendar_uid": "cal_6xm11o5utssx",
                "short_link": null,
                "title": "Unde qui cupiditate voluptates architecto necessitatibus amet consequuntur non.",
                "internal_name": null,
                "is_draft": false,
                "description": "<p>Ut quis inventore alias dolor quia ut sapiente. Impedit blanditiis in est officiis odio. In modi rerum et error ut nisi sint modi.</p>\n\n<p>Repellendus omnis voluptatem vero facilis fuga blanditiis consequatur. Possimus quia alias accusamus nihil quia. Veritatis illum corporis quo dolor. Earum aut enim eum.</p>",
                "location": null,
                "is_all_day": false,
                "has_rsvp": false,
                "has_calendar_invites": false,
                "rsvp_limit": null,
                "is_recurring": false,
                "recurrence_rule": null,
                "recurrence_text": null,
                "date_start": "2026-10-29T09:34:05+04:00",
                "date_end": "2026-10-29T12:34:05+04:00",
                "timezone": "Indian/Mahe",
                "busy_type": null,
                "reminder_before": null,
                "date_range_formatted": "Thu, Oct 29, 2026 9:34 AM - 12:34 PM",
                "public_url": "http://addcal.co/e/xdakful6xd0s",
                "embed_url": "http://addcal.co/e/xdakful6xd0s",
                "location_url": null,
                "image_url": null,
                "timezone_readable": "+04 / GMT+04:00",
                "calendar": {
                    "uid": "6xm11o5utssx",
                    "public_id": "cal_6xm11o5utssx",
                    "short_link": null,
                    "name": "illo atque nam",
                    "internal_name": "et cumque vel",
                    "description": "<p>Et molestias soluta et. Quo veniam et natus facilis ut hic sunt. Id quia sed atque quam. Est harum nisi animi iste illum mollitia neque.</p>",
                    "timezone": "Asia/Dubai",
                    "week_begins": 2,
                    "start_on": "today",
                    "public_url": "http://addcal.co/c/6xm11o5utssx",
                    "created_at": "2026-10-28T23:12:04.000000Z",
                    "updated_at": "2026-10-28T23:12:04.000000Z"
                },
                "created_at": "2026-10-28T23:12:04.000000Z",
                "updated_at": "2026-10-28T23:12:04.000000Z"
            }
        },
        {
            "uid": "60b6450a-44d1-4aa1-aa9d-8022e3bc1e77",
            "public_id": "rsvp_60b6450a-44d1-4aa1-aa9d-8022e3bc1e77",
            "event_uid": "qc312dq2ni9g",
            "response_type": "maybe",
            "waitlist_position": null,
            "name": "Camron Klocko",
            "email": "marietta15@casper.com",
            "data": {
                "guests": 1,
                "comment": "Sed omnis perspiciatis necessitatibus quo odit."
            },
            "formatted_created_at": "2026-10-28 23:12:04",
            "created_at": "2026-10-28T23:12:04.000000Z",
            "updated_at": "2026-10-28T23:12:04.000000Z",
            "event": {
                "uid": "qc312dq2ni9g",
                "public_id": "evt_qc312dq2ni9g",
                "calendar_uid": "cal_q9icqpcwjfps",
                "short_link": null,
                "title": "Tempore inventore sint at.",
                "internal_name": null,
                "is_draft": false,
                "description": "<p>Qui magni voluptatem at aut quasi. Itaque ut rerum qui ullam soluta nihil. Quia in asperiores laboriosam reiciendis quaerat repellendus. Fuga a quisquam vitae eius error excepturi in.</p>\n\n<p>Tempore officia eum consectetur rerum omnis pariatur cum. Suscipit ut enim atque ipsa. Qui itaque molestiae dolorem provident necessitatibus temporibus. Similique quia enim qui ut.</p>",
                "location": null,
                "is_all_day": false,
                "has_rsvp": false,
                "has_calendar_invites": false,
                "rsvp_limit": null,
                "is_recurring": false,
                "recurrence_rule": null,
                "recurrence_text": null,
                "date_start": "2026-11-19T16:47:21+03:30",
                "date_end": "2026-11-19T17:47:21+03:30",
                "timezone": "Asia/Tehran",
                "busy_type": null,
                "reminder_before": null,
                "date_range_formatted": "Thu, Nov 19, 2026 4:47 PM - 5:47 PM",
                "public_url": "http://addcal.co/e/qc312dq2ni9g",
                "embed_url": "http://addcal.co/e/qc312dq2ni9g",
                "location_url": null,
                "image_url": null,
                "timezone_readable": "+0330 / GMT+03:30",
                "calendar": {
                    "uid": "q9icqpcwjfps",
                    "public_id": "cal_q9icqpcwjfps",
                    "short_link": null,
                    "name": "ipsa et quas",
                    "internal_name": null,
                    "description": "<p>Natus error qui numquam adipisci et ut qui. Et doloribus autem ea ea qui quis. Sed perspiciatis sed est ratione quae.</p>",
                    "timezone": "UTC",
                    "week_begins": 3,
                    "start_on": "today",
                    "public_url": "http://addcal.co/c/q9icqpcwjfps",
                    "created_at": "2026-10-28T23:12:04.000000Z",
                    "updated_at": "2026-10-28T23:12:04.000000Z"
                },
                "created_at": "2026-10-28T23:12:04.000000Z",
                "updated_at": "2026-10-28T23:12:04.000000Z"
            }
        }
    ]
}
```

### Create RSVP

`POST /api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps`

**Path parameters**

- `calendar_public_id` (string, required): The ID of the calendar public.
- `event_public_id` (string, required): The ID of the event public.

**Body parameters** (`application/json`)

- `response_type` (string, required): No description. Options: `yes`, `maybe`, `no`, `waitlist`.
- `name` (string, required): Must not be greater than 255 characters.
- `email` (string, required): Must not be greater than 255 characters.
- `strict` (boolean, optional): No description.
- `custom_fields` (object, optional): No description.
- `language` (string, optional): Language for the confirmation and reminder emails, as a two-letter code (e.g. de). A region-tagged code such as de-DE is accepted and narrowed to the language. Defaults to English when omitted; an unsupported language is rejected with a 422.

**Example request**

```bash
curl --request POST \
  --url 'https://addcal.co/api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "response_type": "deserunt",
    "name": "rxvmmxev",
    "email": "dax81@example.net",
    "strict": false,
    "language": "de"
}'
```

**Response 200**

```json
{
    "uid": "27c93004-6e62-4692-b434-fd88bc2449e9",
    "public_id": "rsvp_27c93004-6e62-4692-b434-fd88bc2449e9",
    "event_uid": "3pq0fiok5wuf",
    "response_type": "no",
    "waitlist_position": null,
    "name": "Ida Larson",
    "email": "wilbert88@yahoo.com",
    "data": {
        "guests": 2,
        "comment": null
    },
    "formatted_created_at": "2026-10-28 23:12:04",
    "created_at": "2026-10-28T23:12:04.000000Z",
    "updated_at": "2026-10-28T23:12:04.000000Z",
    "event": {
        "uid": "3pq0fiok5wuf",
        "public_id": "evt_3pq0fiok5wuf",
        "calendar_uid": "cal_4e92hq3kg5od",
        "short_link": null,
        "title": "Ea ipsum dolorum facere perferendis tenetur consequatur eaque.",
        "internal_name": null,
        "is_draft": false,
        "description": "<p>Molestias aliquid nisi laboriosam est. Ea minima quasi doloribus minima id accusamus dolorum. Quis odit libero harum quia sed vel laborum. Id incidunt necessitatibus et.</p>\n\n<p>Sunt sint qui saepe aut nostrum aperiam. Ut consequatur consectetur nihil et libero. Quaerat aut distinctio iure dolorum rerum dolore iste.</p>",
        "location": "3867 Maxime Crescent\nJerodport, ME 79315",
        "is_all_day": false,
        "has_rsvp": false,
        "has_calendar_invites": false,
        "rsvp_limit": null,
        "is_recurring": false,
        "recurrence_rule": null,
        "recurrence_text": null,
        "date_start": "2026-11-18T15:35:56+03:00",
        "date_end": "2026-11-18T18:35:56+03:00",
        "timezone": "Africa/Addis_Ababa",
        "busy_type": null,
        "reminder_before": null,
        "date_range_formatted": "Wed, Nov 18, 2026 3:35 PM - 6:35 PM",
        "public_url": "http://addcal.co/e/3pq0fiok5wuf",
        "embed_url": "http://addcal.co/e/3pq0fiok5wuf",
        "location_url": null,
        "image_url": null,
        "timezone_readable": "EAT / GMT+03:00",
        "calendar": {
            "uid": "4e92hq3kg5od",
            "public_id": "cal_4e92hq3kg5od",
            "short_link": null,
            "name": "ut cumque quam",
            "internal_name": null,
            "description": "<p>Tempore est libero quae ad eligendi. Excepturi eaque fugiat modi similique sit.</p>",
            "timezone": "Africa/Johannesburg",
            "week_begins": 6,
            "start_on": "today",
            "public_url": "http://addcal.co/c/4e92hq3kg5od",
            "created_at": "2026-10-28T23:12:04.000000Z",
            "updated_at": "2026-10-28T23:12:04.000000Z"
        },
        "created_at": "2026-10-28T23:12:04.000000Z",
        "updated_at": "2026-10-28T23:12:04.000000Z"
    }
}
```

### Get RSVP

`GET /api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps/{public_id}`

**Path parameters**

- `calendar_public_id` (string, required): The ID of the calendar public.
- `event_public_id` (string, required): The ID of the event public.
- `public_id` (string, required): The ID of the public.

**Example request**

```bash
curl --request GET \
  --url 'https://addcal.co/api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps/{public_id}' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'
```

**Response 200**

```json
{
    "uid": "b90d3a83-0bb9-441c-b73d-15ce2c942cf0",
    "public_id": "rsvp_b90d3a83-0bb9-441c-b73d-15ce2c942cf0",
    "event_uid": "x82tpdzegdu5",
    "response_type": "maybe",
    "waitlist_position": null,
    "name": "Anabel Pacocha",
    "email": "roberto.kihn@wiza.org",
    "data": {
        "guests": 0,
        "comment": "Fugiat molestiae totam assumenda dolores."
    },
    "formatted_created_at": "2026-10-28 23:12:04",
    "created_at": "2026-10-28T23:12:04.000000Z",
    "updated_at": "2026-10-28T23:12:04.000000Z",
    "event": {
        "uid": "x82tpdzegdu5",
        "public_id": "evt_x82tpdzegdu5",
        "calendar_uid": "cal_yg3pghr7b20r",
        "short_link": null,
        "title": "Explicabo voluptatum ut consequatur sunt fugiat possimus.",
        "internal_name": null,
        "is_draft": false,
        "description": "<p>Nisi quaerat quos ut debitis. Explicabo culpa accusantium voluptatem nobis eum.</p>\n\n<p>Quia itaque aliquam perferendis. Quam fugit et dicta eum tempore aliquam vel. Autem dolor molestiae mollitia est nam.</p>",
        "location": "7482 Tyrel Highway Apt. 890\nEast Bryceland, NY 89873",
        "is_all_day": true,
        "has_rsvp": false,
        "has_calendar_invites": false,
        "rsvp_limit": null,
        "is_recurring": false,
        "recurrence_rule": null,
        "recurrence_text": null,
        "date_start": "2026-10-26T16:42:09+00:00",
        "date_end": "2026-10-26T18:42:09+00:00",
        "timezone": null,
        "busy_type": null,
        "reminder_before": null,
        "date_range_formatted": "Mon, Oct 26, 2026 (all day)",
        "public_url": "http://addcal.co/e/x82tpdzegdu5",
        "embed_url": "http://addcal.co/e/x82tpdzegdu5",
        "location_url": null,
        "image_url": null,
        "timezone_readable": null,
        "calendar": {
            "uid": "yg3pghr7b20r",
            "public_id": "cal_yg3pghr7b20r",
            "short_link": null,
            "name": "nemo accusamus eius",
            "internal_name": "id sit rerum",
            "description": "<p>Ipsa cum quasi quia modi vel ad corrupti. Et est nam incidunt maxime. Reiciendis deserunt esse facilis aut et et qui.</p>",
            "timezone": "America/Indiana/Winamac",
            "week_begins": 1,
            "start_on": "today",
            "public_url": "http://addcal.co/c/yg3pghr7b20r",
            "created_at": "2026-10-28T23:12:04.000000Z",
            "updated_at": "2026-10-28T23:12:04.000000Z"
        },
        "created_at": "2026-10-28T23:12:04.000000Z",
        "updated_at": "2026-10-28T23:12:04.000000Z"
    }
}
```

### Update RSVP

`PUT /api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps/{public_id}`

**Path parameters**

- `calendar_public_id` (string, required): The ID of the calendar public.
- `event_public_id` (string, required): The ID of the event public.
- `public_id` (string, required): The ID of the public.

**Body parameters** (`application/json`)

- `response_type` (string, optional): No description. Options: `yes`, `maybe`, `no`, `waitlist`.
- `name` (string, optional): Must not be greater than 255 characters.
- `email` (string, optional): Must not be greater than 255 characters.
- `strict` (boolean, optional): No description.
- `override_limit` (boolean, optional): Skip the RSVP limit and waitlist, as an organiser override. When omitted, a yes on a full event joins the waitlist, or is rejected with a 422 if the event has no waitlist.
- `custom_fields` (object, optional): No description.

**Example request**

```bash
curl --request PUT \
  --url 'https://addcal.co/api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps/{public_id}' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "response_type": "rerum",
    "name": "kmduzbfqrckfc",
    "email": "igislason@example.com",
    "strict": true,
    "override_limit": false
}'
```

**Response 200**

```json
{
    "uid": "997f6097-965f-4a60-bffb-982cfeda7a14",
    "public_id": "rsvp_997f6097-965f-4a60-bffb-982cfeda7a14",
    "event_uid": "xa6vodh8rpsa",
    "response_type": "no",
    "waitlist_position": null,
    "name": "Dr. Ernie Schimmel Sr.",
    "email": "julia33@gmail.com",
    "data": {
        "guests": 1,
        "comment": "Voluptatem aliquid officiis delectus natus."
    },
    "formatted_created_at": "2026-10-28 23:12:04",
    "created_at": "2026-10-28T23:12:04.000000Z",
    "updated_at": "2026-10-28T23:12:04.000000Z",
    "event": {
        "uid": "xa6vodh8rpsa",
        "public_id": "evt_xa6vodh8rpsa",
        "calendar_uid": "cal_01fckj35pzem",
        "short_link": null,
        "title": "Dolorum ut assumenda ea iusto totam autem.",
        "internal_name": null,
        "is_draft": false,
        "description": "<p>Ut ut omnis fuga. Nobis eius repellat laudantium in iusto. Sit non odit autem repudiandae incidunt iste est molestias. Qui saepe omnis praesentium totam consequatur voluptate nobis non.</p>\n\n<p>Vitae numquam natus et aspernatur. Neque qui qui qui quod dolores omnis animi.</p>",
        "location": null,
        "is_all_day": false,
        "has_rsvp": false,
        "has_calendar_invites": false,
        "rsvp_limit": null,
        "is_recurring": false,
        "recurrence_rule": null,
        "recurrence_text": null,
        "date_start": "2026-11-21T08:30:24-04:00",
        "date_end": "2026-11-21T09:30:24-04:00",
        "timezone": "America/Santo_Domingo",
        "busy_type": null,
        "reminder_before": null,
        "date_range_formatted": "Sat, Nov 21, 2026 8:30 AM - 9:30 AM",
        "public_url": "http://addcal.co/e/xa6vodh8rpsa",
        "embed_url": "http://addcal.co/e/xa6vodh8rpsa",
        "location_url": null,
        "image_url": null,
        "timezone_readable": "AST / GMT-04:00",
        "calendar": {
            "uid": "01fckj35pzem",
            "public_id": "cal_01fckj35pzem",
            "short_link": null,
            "name": "voluptatem nisi vero",
            "internal_name": "tenetur recusandae aut",
            "description": "",
            "timezone": "Pacific/Norfolk",
            "week_begins": 4,
            "start_on": "today",
            "public_url": "http://addcal.co/c/01fckj35pzem",
            "created_at": "2026-10-28T23:12:04.000000Z",
            "updated_at": "2026-10-28T23:12:04.000000Z"
        },
        "created_at": "2026-10-28T23:12:04.000000Z",
        "updated_at": "2026-10-28T23:12:04.000000Z"
    }
}
```

### Delete RSVP

`DELETE /api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps/{public_id}`

**Path parameters**

- `calendar_public_id` (string, required): The ID of the calendar public.
- `event_public_id` (string, required): The ID of the event public.
- `public_id` (string, required): The ID of the public.

**Example request**

```bash
curl --request DELETE \
  --url 'https://addcal.co/api/calendars/{calendar_public_id}/events/{event_public_id}/rsvps/{public_id}' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'
```