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/v1All 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
- Authorize — Redirect the user to
/oauth/authorizewith yourclient_id,redirect_uri,response_type=code, andscope. - Exchange — POST the authorization code to
/api/oauth/tokenwithgrant_type=authorization_code. - Refresh — When the access token expires, POST to
/api/oauth/tokenwithgrant_type=refresh_token. - Revoke — POST to
/api/oauth/revoketo revoke a token pair.
Scopes
| Scope | Grants |
|---|---|
| bookings:read | List and get bookings |
| bookings:write | Create, reschedule and cancel bookings |
| bookings:refund | Refund the card payment when cancelling a booking (with bookings:write) |
| event_types:read | List and get booking types |
| contacts:read | List and search contacts |
| webhooks:manage | Subscribe and unsubscribe webhooks |
| availability:read | Read when you are busy across your calendars (times only) |
Endpoints
Account
/v1/meCurrent user info
Bookings
/v1/bookingsList bookings
/v1/bookings/:idGet a booking
/v1/bookingsCreate a booking
/v1/bookings/:id/rescheduleMove your booking to a new start; it keeps its length
/v1/bookings/:id/cancelCancel 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
/v1/event-typesList booking types
/v1/event-types/:idGet a booking type
/v1/event-types/:id/slotsOpen slots for a booking type
/v1/free-busyYour busy times across your calendars
Contacts
/v1/contactsList or search contacts
/v1/contacts/:idGet a contact
Webhooks
/v1/hooksList subscriptions
/v1/hooksCreate subscription
/v1/hooks/:idDelete subscription
Common Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Number of results to return (default 25, max 100) |
| cursor | string | Cursor for pagination (returned in response) |
| status | string | Filter bookings by status: CONFIRMED, CANCELLED, PENDING |
| string | Search contacts or bookings by invitee email |
Create Booking
POST /v1/bookings
| Field | Type | Required | Description |
|---|---|---|---|
| event_type_id | string | Yes | Booking type ID |
| start_time | string | Yes | ISO 8601 datetime (e.g., 2026-03-15T10:00:00Z) |
| invitee_name | string | Yes | Full name of the invitee |
| invitee_email | string | Yes | Email address of the invitee |
| invitee_timezone | string | No | IANA timezone (defaults to host timezone) |
| notes | string | No | Optional notes from the invitee |
| question_responses | object | No | Answers to the booking type's custom questions, keyed by question (at most 100, each up to 20,000 characters) |
| locale | string | No | The 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_minutes | integer | No | For 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.
| Event | Description |
|---|---|
| BOOKING_CREATED | A new booking is confirmed |
| BOOKING_CANCELLED | A booking is cancelled |
| BOOKING_RESCHEDULED | A booking is rescheduled |
| BOOKING_APPROVED | A pending booking is approved |
| BOOKING_DENIED | A pending booking is denied |
| CONTACT_CREATED | A new contact is created |
| CONTACT_UPDATED | A contact is updated |
| SCHEDULING_REQUEST_UPDATED | A 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.
| Header | Description |
|---|---|
| X-CalendarPA-Signature | sha256=<hex digest> — present only when the subscription has a signing secret |
| X-CalendarPA-Event | Event name (e.g., BOOKING_CREATED) |
| X-CalendarPA-Delivery-ID | Unique delivery ID |
| X-CalendarPA-Timestamp | ISO-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
| Endpoint | Limit |
|---|---|
All /v1/* endpoints | 1,000 requests / minute |
| OAuth token exchange | 20 requests / minute |
| Webhook subscriptions | 10 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"
}| Status | Meaning |
|---|---|
| 400 | Invalid request (validation error) |
| 401 | Missing, invalid or revoked access token, or a plan that no longer includes the API (INVALID_TOKEN) |
| 403 | Insufficient scope (INSUFFICIENT_SCOPE), or a feature your plan does not include (UPGRADE_REQUIRED) |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Internal 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]