Calendeur
API key

API reference

Bookings

Bookings made through the API behave exactly like bookings from a Calendeur page: the host's calendar is updated, the guest gets a confirmation with a calendar invite and join link, reminders are scheduled and webhooks fire.

Create a booking

POST/api/v1/bookings

Books a meeting at a time returned by Get bookable times. Returns 409 slot_unavailable if the time isn't offered, or slot_taken if someone booked it a moment earlier.

Scope: execute:bookings

Body

event_type_idstringrequired

The event type to book.

startdatetimerequired

A start value from availability, in ISO 8601.

guest.namestringrequired

The guest's full name.

guest.emailstringrequired

Where the confirmation and invite are sent.

guest.timezonestring

IANA timezone for the guest's emails, e.g. America/Chicago.

guest.phonestring

Phone number, for SMS reminders where enabled.

guest.companystring

Company name, stored on the contact.

notesstring

Agenda or context, shown to the host.

additional_guestsstring[]

Up to 10 more emails to invite.

curl -X POST "https://calendeur.com/api/v1/bookings" \
  -H "Authorization: Bearer $CALENDEUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_type_id": "evt_30min",
  "start": "2026-10-12T15:00:00.000Z",
  "guest": {
    "name": "Alex Morgan",
    "email": "alex@example.com",
    "timezone": "America/Chicago"
  },
  "notes": "Wants to discuss the onboarding flow"
}'
Response · 201
{
  "id": "bkg_8f2k1q",
  "object": "booking",
  "event_type_id": "evt_30min",
  "host_user_id": "user_2hX",
  "contact_id": "con_91a",
  "status": "upcoming",
  "start": "2026-10-12T15:00:00.000Z",
  "end": "2026-10-12T15:30:00.000Z",
  "duration_minutes": 30,
  "guest": {
    "name": "Alex Morgan",
    "email": "alex@example.com",
    "phone": null,
    "company": "Northwind",
    "timezone": "America/Chicago"
  },
  "additional_guests": [],
  "notes": "Wants to discuss the onboarding flow",
  "location": "google_meet",
  "join_url": "https://meet.google.com/abc-defg-hij",
  "cancellation": null,
  "has_meeting_notes": false,
  "created_at": "2026-10-05T18:22:04.000Z",
  "updated_at": "2026-10-05T18:22:05.000Z"
}

List bookings

GET/api/v1/bookings

Bookings hosted by the account, newest start time first.

Scope: read:bookings

Query parameters

statusstring

upcoming, completed, cancelled or no_show.

fromdatetime

Only bookings starting at or after this time.

todatetime

Only bookings starting at or before this time.

guest_emailstring

Only bookings with this guest.

limitinteger

Results per page, 1 to 100. Default 25.

cursorstring

The next_cursor from the previous page.

curl "https://calendeur.com/api/v1/bookings" \
  -H "Authorization: Bearer $CALENDEUR_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "id": "bkg_8f2k1q",
      "object": "booking",
      "event_type_id": "evt_30min",
      "host_user_id": "user_2hX",
      "contact_id": "con_91a",
      "status": "upcoming",
      "start": "2026-10-12T15:00:00.000Z",
      "end": "2026-10-12T15:30:00.000Z",
      "duration_minutes": 30,
      "guest": {
        "name": "Alex Morgan",
        "email": "alex@example.com",
        "phone": null,
        "company": "Northwind",
        "timezone": "America/Chicago"
      },
      "additional_guests": [],
      "notes": "Wants to discuss the onboarding flow",
      "location": "google_meet",
      "join_url": "https://meet.google.com/abc-defg-hij",
      "cancellation": null,
      "has_meeting_notes": false,
      "created_at": "2026-10-05T18:22:04.000Z",
      "updated_at": "2026-10-05T18:22:05.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get a booking

GET/api/v1/bookings/{id}

One booking, including the AI meeting summary and notes when they exist.

Scope: read:bookings

Path parameters

idstringrequired

The booking ID.

curl "https://calendeur.com/api/v1/bookings/ID" \
  -H "Authorization: Bearer $CALENDEUR_API_KEY"
Response · 200
{
  "id": "bkg_8f2k1q",
  "object": "booking",
  "event_type_id": "evt_30min",
  "host_user_id": "user_2hX",
  "contact_id": "con_91a",
  "status": "upcoming",
  "start": "2026-10-12T15:00:00.000Z",
  "end": "2026-10-12T15:30:00.000Z",
  "duration_minutes": 30,
  "guest": {
    "name": "Alex Morgan",
    "email": "alex@example.com",
    "phone": null,
    "company": "Northwind",
    "timezone": "America/Chicago"
  },
  "additional_guests": [],
  "notes": "Wants to discuss the onboarding flow",
  "location": "google_meet",
  "join_url": "https://meet.google.com/abc-defg-hij",
  "cancellation": null,
  "created_at": "2026-10-05T18:22:04.000Z",
  "updated_at": "2026-10-05T18:22:05.000Z",
  "meeting_summary": null,
  "meeting_notes": null
}

Reschedule a booking

POST/api/v1/bookings/{id}/reschedule

Moves an upcoming booking. Calendars are updated, the guest is emailed and reminders are rescheduled. Fires booking.rescheduled.

Scope: execute:bookings

Path parameters

idstringrequired

The booking ID.

Body

startdatetimerequired

The new start time, ISO 8601.

curl -X POST "https://calendeur.com/api/v1/bookings/ID/reschedule" \
  -H "Authorization: Bearer $CALENDEUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "start": "2026-10-13T14:00:00.000Z"
}'
Response · 200
{
  "id": "bkg_8f2k1q",
  "object": "booking",
  "event_type_id": "evt_30min",
  "host_user_id": "user_2hX",
  "contact_id": "con_91a",
  "status": "upcoming",
  "start": "2026-10-13T14:00:00.000Z",
  "end": "2026-10-13T14:30:00.000Z",
  "duration_minutes": 30,
  "guest": {
    "name": "Alex Morgan",
    "email": "alex@example.com",
    "phone": null,
    "company": "Northwind",
    "timezone": "America/Chicago"
  },
  "additional_guests": [],
  "notes": "Wants to discuss the onboarding flow",
  "location": "google_meet",
  "join_url": "https://meet.google.com/abc-defg-hij",
  "cancellation": null,
  "has_meeting_notes": false,
  "created_at": "2026-10-05T18:22:04.000Z",
  "updated_at": "2026-10-05T18:22:05.000Z"
}

Cancel a booking

POST/api/v1/bookings/{id}/cancel

Cancels a meeting that hasn't happened yet. Calendar events are removed and the guest is notified. Fires booking.cancelled.

Scope: execute:bookings

Path parameters

idstringrequired

The booking ID.

Body

reasonstring

Optional, up to 500 characters. Included in the guest's email.

curl -X POST "https://calendeur.com/api/v1/bookings/ID/cancel" \
  -H "Authorization: Bearer $CALENDEUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Moving to a group session instead"
}'
Response · 200
{
  "id": "bkg_8f2k1q",
  "object": "booking",
  "event_type_id": "evt_30min",
  "host_user_id": "user_2hX",
  "contact_id": "con_91a",
  "status": "cancelled",
  "start": "2026-10-12T15:00:00.000Z",
  "end": "2026-10-12T15:30:00.000Z",
  "duration_minutes": 30,
  "guest": {
    "name": "Alex Morgan",
    "email": "alex@example.com",
    "phone": null,
    "company": "Northwind",
    "timezone": "America/Chicago"
  },
  "additional_guests": [],
  "notes": "Wants to discuss the onboarding flow",
  "location": "google_meet",
  "join_url": "https://meet.google.com/abc-defg-hij",
  "cancellation": {
    "by": "host",
    "reason": "Moving to a group session instead"
  },
  "has_meeting_notes": false,
  "created_at": "2026-10-05T18:22:04.000Z",
  "updated_at": "2026-10-05T18:22:05.000Z"
}
PreviousAvailabilityNext Meeting notes