Skip to the main deck

Public API

REST API for integrating CalendarPA with Zapier, Make.com, n8n, and custom applications. Requires a Pro plan or higher.

Connecting ChatGPT, Claude, or any other agent? Use the CalendarPA MCP server instead. It signs in with OAuth, needs no API key and works on every plan.

Base URL

https://calendarpa.com/api/v1

All endpoints are served over HTTPS. HTTP requests are automatically upgraded.

Authentication

CalendarPA uses the OAuth 2.0 Authorization Code flow. After authorization, include the access token as a Bearer token in every request:

Authorization: Bearer cpa_at_...

OAuth 2.0 Flow

  1. Authorize — Redirect the user to /oauth/authorize with your client_id, redirect_uri, response_type=code, and scope.
  2. Exchange — POST the authorization code to /api/oauth/token with grant_type=authorization_code.
  3. Refresh — When the access token expires, POST to /api/oauth/token with grant_type=refresh_token.
  4. Revoke — POST to /api/oauth/revoke to revoke a token pair.

Scopes

ScopeGrants
bookings:readList and get bookings
bookings:writeCreate, reschedule and cancel bookings
bookings:refundRefund the card payment when cancelling a booking (with bookings:write)
event_types:readList and get booking types
contacts:readList and search contacts
webhooks:manageSubscribe and unsubscribe webhooks
availability:readRead when you are busy across your calendars (times only)

Endpoints

Account

GET/v1/me
any

Current user info

Bookings

GET/v1/bookings
bookings:read

List bookings

GET/v1/bookings/:id
bookings:read

Get a booking

POST/v1/bookings
bookings:write

Create a booking

POST/v1/bookings/:id/reschedule
bookings:write

Move your booking to a new start; it keeps its length

POST/v1/bookings/:id/cancel
bookings:write

Cancel a booking

To cancel a booking paid for by card, say what happens to the payment: {"refund": false} keeps it, and {"refund": true} refunds it. Without refund the request is refused with 409 REFUND_DECISION_REQUIRED and nothing is cancelled; the response carries the payment and refundAllowed, which says whether your token may refund. Refunding needs the bookings:refund scope as well as bookings:write; without it {"refund": true} is refused with 403 INSUFFICIENT_SCOPE. A free booking, or one paid only with credits, needs no refund field. Credits are returned on every cancel.

A booking that is a spot in a group session cannot be cancelled here: the cancel endpoint answers 422 withcode GROUP_SEAT_ON_SESSION_PAGE and the session's sessionId (null when unknown). Cancel the registration from the session page instead.

A booking, in these responses and in webhook payloads, carries meeting_url and meeting_password: the Zoom passcode for that link, or null when there is none or the link is not a Zoom link. A Zoom link includes the passcode only when the host's Zoom account embeds it, so send both to anyone joining.

When a booking type offers several ways to meet, the type lists them in location_options (the first is the one meeting_type describes), and a booking records the one the invitee chose in location_kind and location_option_id, with invitee_address and invitee_address_line2 when they chose to meet at their own address. These are null when the type has no list (one ordinary location). To create such a booking, send location_option_id (and invitee_address for an at-their-address option); without one it gets the first. An option whose bookable is false is one the host keeps but no longer offers, and naming it is refused.

Booking Types

GET/v1/event-types
event_types:read

List booking types

GET/v1/event-types/:id
event_types:read

Get a booking type

GET/v1/event-types/:id/slots
event_types:read

Open slots for a booking type

GET/v1/free-busy
availability:read

Your busy times across your calendars

Contacts

GET/v1/contacts
contacts:read

List or search contacts

GET/v1/contacts/:id
contacts:read

Get a contact

Webhooks

GET/v1/hooks
webhooks:manage

List subscriptions

POST/v1/hooks
webhooks:manage

Create subscription

DELETE/v1/hooks/:id
webhooks:manage

Delete subscription

Common Parameters

ParameterTypeDescription
limitintegerNumber of results to return (default 25, max 100)
cursorstringCursor for pagination (returned in response)
statusstringFilter bookings by status: CONFIRMED, CANCELLED, PENDING
emailstringSearch contacts or bookings by invitee email

Create Booking

POST /v1/bookings

FieldTypeRequiredDescription
event_type_idstringYesBooking type ID
start_timestringYesISO 8601 datetime (e.g., 2026-03-15T10:00:00Z)
invitee_namestringYesFull name of the invitee
invitee_emailstringYesEmail address of the invitee
invitee_timezonestringNoIANA timezone (defaults to host timezone)
notesstringNoOptional notes from the invitee
question_responsesobjectNoAnswers to the booking type's custom questions, keyed by question (at most 100, each up to 20,000 characters)
localestringNoThe invitee's language for their confirmation and reminders: en, es or fr. Defaults to en. There is no browser to infer this from, so an API booking is English unless you set it.
duration_minutesintegerNoFor a booking type with a flexible length: minutes within its range and increment (defaults to its standard length). A fixed-length type takes its own length; any other value is a 422 INVALID_DURATION.

Example Request

curl -X POST https://calendarpa.com/api/v1/bookings \
  -H "Authorization: Bearer cpa_at_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type_id": "et_xyz789",
    "start_time": "2026-03-15T10:00:00Z",
    "invitee_name": "Jane Smith",
    "invitee_email": "jane@example.com",
    "invitee_timezone": "America/New_York",
    "locale": "es"
  }'

The booking follows the same rules as your booking page. A time your booking page would not offer is 409 SLOT_NOT_IN_AVAILABILITY, whether it is outside your available hours, notice or buffers or is already booked; a time taken in the moment between that check and the booking is 409 SLOT_UNAVAILABLE. Either way, try another time. A day that has reached your booking limit is 422 BOOKING_LIMIT_REACHED, with its period and limit; on a round-robin or co-hosted type, where each host has their own limit, a full day is 409 SLOT_NOT_IN_AVAILABILITY. A start in the past is 422 START_IN_PAST. A paid booking type is 422 PAYMENT_REQUIRED (it is booked through checkout, which takes the payment first). On a variable-length type, duration_minutes defaults to the type's own length, and a length outside its range or steps is 422 INVALID_DURATION. Your own private booking types can be booked through the API. A booking your round-robin type assigned to a current member of its rotation is yours to list and fetch; only its host can cancel or reschedule it.

Webhook Events

Subscribe to real-time notifications when events occur in your CalendarPA account. Create subscriptions via POST /v1/hooks.

EventDescription
BOOKING_CREATEDA new booking is confirmed
BOOKING_CANCELLEDA booking is cancelled
BOOKING_RESCHEDULEDA booking is rescheduled
BOOKING_APPROVEDA pending booking is approved
BOOKING_DENIEDA pending booking is denied
CONTACT_CREATEDA new contact is created
CONTACT_UPDATEDA contact is updated
SCHEDULING_REQUEST_UPDATEDA scheduling request changed state. Available to the CalendarPA first-party app only.

Subscribing is idempotent: posting the same event and URL again from the same app returns the existing subscription with 200, reactivates it if it was disabled, and issues a NEW signing secret, so store the secret from every response. Every subscription carries client_only, which is false for every event a third-party app can subscribe to.

Webhook Signing

A webhook delivery is signed when its subscription has a signing secret. Subscriptions created before signing was available have none, and their deliveries carry no signature header.

HeaderDescription
X-CalendarPA-Signaturesha256=<hex digest> — present only when the subscription has a signing secret
X-CalendarPA-EventEvent name (e.g., BOOKING_CREATED)
X-CalendarPA-Delivery-IDUnique delivery ID
X-CalendarPA-TimestampISO-8601 timestamp of delivery

POST /v1/hooks returns a signing_secret alongside the subscription. It is shown once and cannot be retrieved again — store it when you create the subscription. If you lose it, delete the subscription and create a new one.

Verify a delivery by computing HMAC-SHA256 over the raw request body, before any JSON parsing or re-serialisation, and comparing in constant time:

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader || '');
  const b = Buffer.from(expected);
  // Lengths must match before timingSafeEqual, which throws otherwise.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Use a constant-time comparison rather than ===: an ordinary string compare returns as soon as two bytes differ, and the time it took leaks how much of the signature was correct.

Rate Limits

EndpointLimit
All /v1/* endpoints1,000 requests / minute
OAuth token exchange20 requests / minute
Webhook subscriptions10 requests / minute

Rate-limited requests return 429 Too Many Requests. Maximum 25 active webhook subscriptions per account.

Error Responses

All errors return a JSON body with an error field:

{
  "error": "Unauthorized",
  "code": "INVALID_TOKEN"
}
StatusMeaning
400Invalid request (validation error)
401Missing, invalid or revoked access token, or a plan that no longer includes the API (INVALID_TOKEN)
403Insufficient scope (INSUFFICIENT_SCOPE), or a feature your plan does not include (UPGRADE_REQUIRED)
404Resource not found
429Rate limit exceeded
500Internal server error

Third-Party Integrations

CalendarPA integrates with popular automation platforms out of the box:

  • Zapier — 7 triggers, 2 actions, and 2 searches. Connect CalendarPA to thousands of apps.
  • Make.com — Use CalendarPA as an HTTP module with OAuth2 authentication.
  • n8n — Use the generic OAuth2 API node with CalendarPA endpoints.

Need Help?

If you have questions about the API or need help with your integration, contact our support team at [email protected]