Cartoply
Get started

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: https://www.cartoply.com/oauth/authorize — send the user's browser here. It's the Cartoply consent screen; the user signs in, approves, and is redirected back to your redirect_uri with an authorization code.
  • 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.

Available scopes: bookings:read (the Zapier integration's scope, and the default when none is requested) plus mcp:read, mcp:write, and the explicitly-consented high-risk mcp:danger, which gate the MCP server's tool surface. Clients can self-register via dynamic client registration (POST https://api.cartoply.com/api/oauth/register, RFC 7591); clients registered with token_endpoint_auth_method: "none" are public clients and must use PKCE (S256). Discovery metadata lives at /.well-known/oauth-authorization-server on the API origin. Note that https://api.cartoply.com/api/oauth/authorize is an internal endpoint used by the consent screen itself — it requires a Cartoply session, not a client credential, and integrations should not call it directly.

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.requested, booking.cancelled,booking.rescheduled.

booking.requested fires when an event type with manual approval holds a booking for review (the payload status is pending_approval). If the host later approves it, a normal booking.created fires; if they decline, booking.cancelled fires.

  • 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?scope=self|org — recent bookings for setup/testing, mirroring the subscription scope. Samples are drawn from real bookings, so a booking.requested sample carries status: "confirmed" rather than pending_approval.

Each event delivers a flat JSON payload:

{
  "id": "3f2b41c8-9d5e-4a17-b0c6-8e2d7a5419fb",
  "event": "booking.created",
  "inviteeName": "Jane Doe",
  "inviteeEmail": "jane@example.com",
  "inviteePhone": "+1 555 123 4567",
  "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 },
  "attribution": {
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "summer-ac",
    "gclid": "Cj0KCQ...",
    "referrer": "https://www.google.com/",
    "page": "https://example.com/book"
  }
}

All timestamps are ISO 8601 in UTC (trailing Z). attribution carries the UTM and ad-click data captured at booking time and is null when none was present — see Conversion tracking.

Delivery

  • Payloads are signed with an HMAC-SHA256 digest in the X-Cartoply-Signature header. Verify it against your shared secret before trusting a payload.
  • If your endpoint responds 410 Gone, Cartoply deletes the subscription — that's the intended way to retire a hook.

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, emails the guest, and archives the linked Jobber Request. Returns 404 unless the connected user owns or is the assigned rep on the booking, and 400 if it's already cancelled.

If the booking was paid, cancelling refunds the guest in full, automatically. There is no dry-run — treat this endpoint as a financial action.

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). The guest is not notified, but the booking's status changes, so it moves between tabs on the Bookings dashboard as well as feeding reporting. Returns 400 on a cancelled booking. Unlike cancel, this is also permitted to admins of the booking's organization.

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 with a JSON body carrying an error key. Validation failures return 400 — some include per-field detail, others a single message; an invalid or expired token returns 401; a missing or not-permitted record returns 404.

The /oauth endpoints are rate-limited to 30 requests per minute per IP and return 429 when you exceed it. The trigger and action endpoints under /zapier aren't hard-limited today, but keep polling to a reasonable cadence — that may change.

Building on Cartoply

The fastest way to automate Cartoply is the official Zapier integration, which is built on the endpoints above. AI assistants should connect over MCP instead — it exposes the full admin tool surface rather than this narrower REST set. For partnership or direct-API access, contact hello@cartoply.com.