TidyCal's REST API provides a handful of endpoints which can be used to get information about your account and bookings. It uses conventional OAuth 2.0 protocol for authentication.

Personal Access Token

Create a personal access token from Integrations -> Advanced -> "Manage API keys" -> "Personal tokens" tab at https://tidycal.com/integrations/advanced (the API is included on every TidyCal plan, including Free). Once created, it can be used to authenticate requests by passing it in the Authorization header.

Authorization: Bearer {TOKEN}

OAuth 2.0 Client

If you're building a custom integration to TidyCal which requires users to authenticate in order to get access tokens to make API requests on their behalf, you'll need to create an OAuth 2.0 client. This is easy to do from Integrations -> Advanced -> "Manage API keys" -> "OAuth clients" tab found here https://tidycal.com/integrations/advanced

Using the authorization_code grant type to authenticate users using OAuth 2.0 to retrieve an access token is fairly conventional, more information on that process can be found here: https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/

• Authorization URL: https://tidycal.com/oauth/authorize
• Access Token URL: https://tidycal.com/oauth/token

TidyCal ships an MCP server that lets AI assistants such as Claude and ChatGPT work with your TidyCal scheduling data through natural language — ask things like "what bookings do I have next week?" and the assistant answers using your live account data. It can read your account and, only if you approve the write permission when you connect, create and change things: book a meeting, cancel a booking, create a booking type, or add a contact.

Full setup guide, OAuth details, and the current tool list: https://tidycal.com/mcp-docs

Requirements

• A TidyCal account. The MCP server is included on every TidyCal plan, including Free.
• A supported AI client: Claude.ai (custom connector) or ChatGPT (custom connector, on a plan that supports them).

Connecting Claude

1. In Claude.ai, open Settings -> Connectors and choose Add custom connector.
2. Paste the TidyCal MCP server URL: https://tidycal.com/mcp
3. Claude redirects you to TidyCal to sign in (OAuth 2.1). Log in and approve access — TidyCal requests two scopes: mcp:scheduling:read (see your bookings, booking types, availability, and teams) and mcp:scheduling:write (create and change bookings and booking types). Approve only the first for a read-only connection.
4. Once connected, ask Claude about your schedule in plain language.

The connection uses OAuth 2.1 with Dynamic Client Registration; you never paste an API key or token into Claude.

Connecting ChatGPT

1. In ChatGPT, open Settings -> Connectors -> Add and choose a custom connector.
2. Paste the same server URL: https://tidycal.com/mcp
3. ChatGPT redirects you to TidyCal to sign in and approve the same two scopes.
4. Ask ChatGPT about your schedule. Disconnect any time from ChatGPT's connector settings or from TidyCal under Integrations -> Advanced -> Manage API keys -> Authorized clients.

Available tools

The server exposes tools to read your profile, teams, booking types, bookings, availability, busy times, locations, and Store orders. With the write scope it also exposes tools to book a meeting, cancel a booking, create a booking type, and add a contact. The current list, with what each tool returns, is on the setup page: https://tidycal.com/mcp-docs — it is generated from the server itself, so it is always up to date.

Scope and limitations

• Changes need the write scope. Without mcp:scheduling:write, tools that create or cancel refuse and say so. Even with it, no tool edits or deletes existing booking types, issues refunds, or changes account settings.
• Cancelling a booking cannot be undone, and always emails the booker and host. Booking types that charge a price cannot be booked from MCP.
• An MCP connection's token works only with the MCP server, not this REST API. It lasts one hour and is refreshed by the assistant; the refresh token lasts 30 days. Use a personal access token or your own OAuth client for the REST API.
• Exposed data: your profile, booking types, bookings, availability, busy times, teams, locations, and Store orders.
• list-busy-times covers every connected provider — Google, Microsoft and Apple — for calendars you have enabled for conflict checking.
• Dates/times use ISO 8601 (e.g. 2026-06-01T14:30:00Z); returned times are UTC unless a resource notes otherwise.

Example prompts

• "What bookings do I have next week?"
• "When am I free for a 30-minute consult over the next few days?"
• "Show my cancelled bookings from last month."
• "Which booking types do I offer, and how long is each?"

List endpoints return 100 items per page (booking types: 30, a team's booking types: 50). Use the page query parameter to move through pages. Responses include the data array plus pagination fields: either at the top level (current_page, last_page, per_page, total, next_page_url, prev_page_url, from, to, first_page_url, last_page_url, path, links) or, for endpoints that return resource collections, in links and meta objects. Keep requesting the next page until next_page_url (or links.next) is null.

Date filters (starts_at, ends_at) accept ISO 8601 timestamps, with or without milliseconds, for example 2026-10-20T14:30:00Z, 2026-10-20T14:30:00.000Z or 2026-10-20T09:30:00-05:00.

The API allows 60 requests per minute per user. Requests over the limit return 429 Too Many Requests with a Retry-After header (seconds to wait). Each response includes X-RateLimit-Limit and X-RateLimit-Remaining.

Errors are always JSON. Validation failures return 422 with a message and an errors object keyed by field name.

Webhooks send a signed HTTPS POST to your URL when something happens in your account. Manage them with the /webhooks endpoints below, or subscribe from Zapier or Make, which use the same endpoints. Up to 10 webhooks per account.

Payload

Every event has the same envelope. data is a webhook object with exactly the fields shown in the examples below: it never includes the booker's IP address, payment processor ids, or internal host and booking type settings.

{
  "id": "6f1b7c52-0f4e-4d0e-9d5e-0a4a8b1f2c33",
  "type": "booking.created",
  "created_at": "2026-10-21T15:04:05+00:00",
  "data": { ... }
}

id is unique per event and is the same on every retry and resend, so use it to dedupe. created_at is when the event happened. data is built by a background worker a few seconds later, so it reflects the record as it was then, and can be newer than created_at suggests if the record changed in between. Headers on every request: Content-Type: application/json, User-Agent: TidyCal-Webhooks/1.0, TidyCal-Event (the event type), TidyCal-Event-Id (the event id, your dedupe key), TidyCal-Delivery-Id (the id of this webhook's delivery record, the id in the delivery log) and TidyCal-Signature.

Receiving webhooks

• Delivery is at least once. The same event can reach you more than once (a retry after a timeout, or a resend from the dashboard). Dedupe on the event id, which is also sent in the TidyCal-Event-Id header and never changes across retries and resends. (TidyCal-Delivery-Id is different: it identifies this webhook's copy of the event, so it is the same across retries but not a dedupe key across webhooks.) Store the ids you have handled and skip repeats.
• Verify every request before you trust it (see below), then answer fast. Respond with a 2xx and do the real work afterwards, for example in a queue.
• Order is not guaranteed. A retried booking.created can arrive after a later booking.cancelled. Use the timestamps inside data, not arrival order.
• Test it with POST /webhooks/{id}/test, which sends a signed webhook.test event through the same path as real events.

Verifying the signature

Every request carries TidyCal-Signature: t=<unix timestamp>,v1=<hex digest>.

1. Read the raw request body bytes. Do not parse and re-serialize the JSON, because that changes the bytes.
2. Split the header on , to get t and v1.
3. Compute HMAC-SHA256 of the string t + "." + raw_body, keyed with the full webhook secret including the whsec_ prefix, as lowercase hex.
4. Compare it with v1 in constant time: hash_equals in PHP, crypto.timingSafeEqual in Node. Never use == or === on signatures.
5. Reject the request if t is more than 5 minutes (300 seconds) away from your clock. This stops someone replaying a captured request. Each retry is signed again with a fresh t, so a legitimate retry always passes.

   expected = hex(hmac_sha256(secret, t + "." + raw_body))
   

   The secret is shown once, when you create the webhook or rotate its secret (POST /webhooks/{id}/rotate-secret). Rotating stops the old secret from verifying immediately.

PHP:

$secret = getenv('TIDYCAL_WEBHOOK_SECRET'); // the full whsec_... string
$body   = file_get_contents('php://input'); // raw bytes, before any json_decode

parse_str(str_replace(',', '&', $_SERVER['HTTP_TIDYCAL_SIGNATURE'] ?? ''), $parts);
$t  = $parts['t'] ?? '';
$v1 = $parts['v1'] ?? '';

if (!ctype_digit($t) || abs(time() - (int) $t) > 300) {
    http_response_code(400); // missing, malformed or stale timestamp
    exit;
}

$expected = hash_hmac('sha256', $t . '.' . $body, $secret);

if (!hash_equals($expected, $v1)) {
    http_response_code(401); // bad signature
    exit;
}

$eventId = $_SERVER['HTTP_TIDYCAL_EVENT_ID']; // dedupe on this
$event   = json_decode($body, true);
http_response_code(204);

Node.js (Express):

const crypto = require('crypto');
const express = require('express');
const app = express();

const secret = process.env.TIDYCAL_WEBHOOK_SECRET; // the full whsec_... string

// express.raw keeps the body as a Buffer of the exact bytes TidyCal sent.
app.post('/tidycal', express.raw({ type: 'application/json' }), (req, res) => {
  const parts = Object.fromEntries(
    (req.get('TidyCal-Signature') || '').split(',').map((part) => part.split('=', 2))
  );
  const t = parts.t || '';
  const v1 = parts.v1 || '';

  if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > 300) {
    return res.sendStatus(400); // missing, malformed or stale timestamp
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.`)
    .update(req.body)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(v1);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401); // bad signature
  }

  const eventId = req.get('TidyCal-Event-Id'); // dedupe on this
  const event = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(204);
});

Delivery and retries

Respond with any 2xx within 10 seconds for the whole request (5 seconds to connect). Anything else, or a timeout, is retried up to 8 attempts in all, after 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours and 12 hours (about 22 hours from the first attempt to the last). After the 8th failed attempt the delivery is marked failed; you can resend it from the dashboard or with POST /webhooks/deliveries/{id}/resend, which keeps the same event id.

Your URL must be https and must resolve only to public addresses (private, loopback, link-local and cloud metadata addresses are refused). Redirects are not followed, so a 301 or 302 counts as a failure. Only ports 443 (the default) and 8443 are allowed; any other port is rejected when you save the webhook and before every send. Only the status code of your response is used: the body is never read, and the delivery log shows an outcome such as http_5xx, timeout, connection_failed, tls_error or blocked_destination instead. Deliveries to one host are rate limited across all accounts; over the limit they are delayed, not dropped.

When a webhook is turned off

• A 410 Gone response turns the webhook off straight away and that delivery is not retried. Use it to tell TidyCal you no longer want events.
• A webhook is turned off only when it has been failing continuously for more than 72 hours and at least 8 delivery attempts in a row have failed. Any 2xx resets the count, and so does a gap of more than 24 hours between failures. A short outage, or a webhook that gets very few events, is not turned off.
• In both cases the owner is emailed, enabled becomes false and disabled_reason is gone or failing (manual when you turn it off yourself). Events that happen while a webhook is off are not queued for it. Turn it back on with PATCH /webhooks/{id} {"enabled": true} or from Integrations, Automations in the dashboard.
• A team webhook is also turned off (team_access_removed) when the team owner or admin who created it stops managing the team, and a webhook created by a third-party app when you revoke that app (app_revoked). The first can be turned back on once its creator manages the team again; the second cannot: delete it and create a new one.
• Delivery history is kept for 30 days.

Events

Booking events carry the booking, contact.created the contact and store_order.completed the Store order, in the webhook shapes shown below (hosts are {id, name}, booking_type is a short summary). Payment and subscription events carry their own objects, shown below. Payment amounts are in major units (for example dollars), like bookings. Payment, charge and Stripe or PayPal ids, card details and the subscription manage link are never included.

Example: booking.created

{
  "id": "6f1b7c52-0f4e-4d0e-9d5e-0a4a8b1f2c33",
  "type": "booking.created",
  "created_at": "2026-10-21T15:04:05+00:00",
  "data": {
    "id": 101,
    "booking_type_id": 7,
    "starts_at": "2026-10-28T16:00:00.000000Z",
    "ends_at": "2026-10-28T16:30:00.000000Z",
    "timezone": "America/Chicago",
    "location": null,
    "booking_type": { "id": 7, "title": "Intro call", "url_slug": "intro-call", "url": "https://tidycal.com/ada/intro-call",
                      "duration_minutes": 30, "price": null, "currency_code": "USD", "team": null },
    "contact_id": 55,
    "contact": { "id": 55, "name": "Ada Lovelace", "email": "[email protected]", "phone_number": null, "timezone": "Europe/London",
                 "source": null, "created_at": "2026-10-21T15:04:04.000000Z", "updated_at": "2026-10-21T15:04:04.000000Z" },
    "payment": null,
    "add_ons": [],
    "hosts": [{ "id": 3, "name": "Grace Hopper" }],
    "questions": [],
    "meeting_url": "https://zoom.us/j/949494949494",
    "approved_at": null,
    "cancelled_at": null,
    "created_at": "2026-10-21T15:04:04.000000Z"
  }
}

booking.cancelled is the same with cancelled_at set. booking.approved has approved_at set. booking.rescheduled has the new starts_at and ends_at and an extra previous_starts_at.

Example: payment.completed

status is completed, pending or failed. On payment.refunded it is refunded or partially_refunded, and refunded_amount (cumulative, major units) is added; refunded_amount is absent on every other payment event.

{
  "id": "2c7e...", "type": "payment.completed", "created_at": "2026-10-21T15:04:05+00:00",
  "data": { "id": 9, "booking_id": 101, "type": "booking", "amount": 25.0, "currency": "USD", "status": "completed",
            "platform_fee": null, "completed_at": "2026-10-21T15:04:00.000000Z", "created_at": "2026-10-21T15:03:30.000000Z" }
}

Example: contact.created

{
  "id": "0b9c...", "type": "contact.created", "created_at": "2026-10-21T15:04:05+00:00",
  "data": { "id": 55, "name": "Ada Lovelace", "email": "[email protected]", "phone_number": null,
            "timezone": "Europe/London", "source": null,
            "created_at": "2026-10-21T15:04:04.000000Z", "updated_at": "2026-10-21T15:04:04.000000Z" }
}

Example: store_order.completed

{
  "id": "4d2a...", "type": "store_order.completed", "created_at": "2026-10-21T15:04:05+00:00",
  "data": { "id": 31, "booking_id": null, "product_id": 4, "product": { "id": 4, "title": "Planner", "slug": "planner" },
            "buyer_name": "Ada Lovelace", "buyer_email": "[email protected]", "amount": 19.0, "currency": "USD",
            "formatted_amount": "$19.00", "status": "completed",
            "completed_at": "2026-10-21T15:04:00.000000Z", "refunded_at": null, "created_at": "2026-10-21T15:03:30.000000Z" }
}

Example: subscription.started

subscription.renewed and subscription.cancelled have the same shape. renews_at is the end of the current period while the subscription is active and not cancelled, otherwise null.

{
  "id": "8e1f...", "type": "subscription.started", "created_at": "2026-10-21T15:04:05+00:00",
  "data": { "id": 3, "status": "active",
            "plan": { "id": 2, "booking_type_id": 7, "booking_type": "Coaching", "credits_per_period": 4, "period_unit": "month" },
            "price": 99.0, "currency": "USD", "credits_used": 0,
            "current_period_start": "2026-10-21T15:00:00.000000Z", "current_period_end": "2026-11-21T15:00:00.000000Z",
            "renews_at": "2026-11-21T15:00:00.000000Z", "cancelled_at": null, "ends_at": null,
            "contact": { "id": 55, "name": "Ada Lovelace", "email": "[email protected]" },
            "created_at": "2026-10-21T15:00:00.000000Z" }
}

Test events

POST /webhooks/{id}/test sends {"id": "...", "type": "webhook.test", "created_at": "...", "data": {"message": "This is a test event from TidyCal.", "webhook_id": 12}}. You cannot subscribe to webhook.test.