Cartoply API & integration reference

This page documents the public API surface that powers Cartoply's integrations (including the official Cartoply Zapier app): OAuth 2.0 authentication, booking-event webhooks (triggers), and write actions. All endpoints are served from the API base below and return JSON.

API base URL: https://api.cartoply.com/api

Authentication (OAuth 2.0)

Integrations authenticate on behalf of a Cartoply user with the OAuth 2.0 authorization code flow. Access tokens are sent as a Bearer token on every request:Authorization: Bearer <access_token>. Tokens are scoped to the connecting user; an endpoint only returns or affects data that user owns or is assigned to.

• Authorize: POST https://api.cartoply.com/api/oauth/authorize — issues an authorization code (user must be signed in).
• Token: POST https://api.cartoply.com/api/oauth/token — exchanges the code for an access token + refresh token (accepts application/x-www-form-urlencoded).
• Connection test / user info: GET https://api.cartoply.com/api/oauth/userinfo — returns the authenticated user; used to verify a connection.

Triggers (booking event webhooks)

Cartoply delivers booking events via REST hooks. A subscriber registers a target URL for an event; Cartoply POSTs the payload to that URL when the event fires. Supported events:booking.created, booking.cancelled, booking.rescheduled.

• Subscribe: POST https://api.cartoply.com/api/zapier/subscriptions — body { "event", "targetUrl", "scope" } (scope: self or org).
• Unsubscribe: DELETE https://api.cartoply.com/api/zapier/subscriptions/:id
• Sample data: GET https://api.cartoply.com/api/zapier/triggers/:event/sample — recent matching bookings for setup/testing.

Each event delivers a flat JSON payload:

{
  "id": "b_8f3a...",
  "event": "booking.created",
  "inviteeName": "Jane Doe",
  "inviteeEmail": "jane@example.com",
  "startTime": "2026-08-01T15:00:00.000Z",
  "endTime": "2026-08-01T16:00:00.000Z",
  "status": "confirmed",
  "guestAddress": "123 Main St, Dallas, TX",
  "eventType": { "name": "AC Tune-Up", "duration": 60 }
}

All timestamps are ISO 8601 in UTC (trailing Z).

Actions (write endpoints)

These OAuth-authenticated endpoints let an integration act on the connected user's account.

Block a date

POST https://api.cartoply.com/api/zapier/actions/block-date — blocks (or unblocks) a date on the user's availability.

// Request body
{
  "date": "2026-07-04",        // required, YYYY-MM-DD
  "isBlocked": true,            // optional, default true
  "startTime": "09:00",         // optional, HH:MM — omit for a full-day block
  "endTime": "17:00"            // optional, HH:MM
}

Cancel a booking

POST https://api.cartoply.com/api/zapier/actions/bookings/:id/cancel — cancels a booking, removes the synced calendar event, and emails the guest. Returns 404 unless the connected user owns or is the assigned rep on the booking.

Mark a booking as a no-show

POST https://api.cartoply.com/api/zapier/actions/bookings/:id/no-show — flags a booking as a no-show (body { "noShow": false } to undo). Updates reporting only; the guest is not notified.

List bookings (for ID lookups)

GET https://api.cartoply.com/api/zapier/bookings — returns the connected user's recent bookings as { id, label, ... } objects, used to populate the Booking ID picker on the cancel and no-show actions.

Errors & rate limits

Endpoints return standard HTTP status codes. Validation errors return 400 with a JSON body describing the invalid fields; an invalid or expired token returns 401; a missing or not-permitted record returns 404. Please keep automated polling to a reasonable cadence.

Building on Cartoply

The fastest way to automate Cartoply is the official Zapier integration, which is built on the endpoints above. For partnership or direct-API access, contact hello@cartoply.com.