YouCanBookMe API Guide: Access, Authentication, Endpoints, Webhooks and Limits

The short answer: broad, honest and Team-only

YouCanBookMe has a REST API at api.youcanbook.me, documented on Stoplight. It manages account details, booking pages, team members, appointment types and bookings, and the docs say every setting on a booking page can be read and changed. You can create pages, cancel bookings and drive the whole booking flow from your own code. For a scheduler this size, that is broad. The public OpenAPI export lists 14 operations, while the written guides describe more, and the documentation is unusually candid about what does not work yet. Rate limits are not published.

The catch is access. The API is a Team plan feature, and only the Account Owner can create a key ^[1]. The pricing table marks API access only for the top tier ^[2], and Administrators and Contributors cannot generate keys of their own. That plan gate shapes most decisions. A solo professional who only wants bookings pushed to another system can do that with webhooks on Professional, while anything that creates pages, changes settings or reads history requires a Team subscription. So first ask whether you need it.

Do you need the API? Webhooks and Zapier come first

Webhooks on Professional

You do not need the API to receive data. Webhooks are notifications that call your URL, on Professional and Team ^[3]. They fire on new, rescheduled, canceled, reminder, follow-up and no-show events, with optional delays. Payloads are JSON built from shorthand codes, with special encoding tags for URLs and JSON, and the methods include GET, PUT, POST, PATCH and DELETE, so you design the payload your receiving system expects. Webhooks can also carry custom request headers for authorization, a feature that arrived in a product update. Use a secret header, check it on your server and reject calls without it.

For many small businesses the price settles it. Professional with webhooks costs $140.40 a year on yearly billing, against $194.40 for a single Team member with API access, a difference of $54 a year by our arithmetic. The cheapest API access is that one Team member at $16.20 a month on yearly billing, and every person on the team is a paid member. Webhooks come cheaper, at $11.70 a month billed yearly on Professional. For teams that already need several members on Team for scheduling reasons, the API comes at no extra cost. For a solo developer, it is effectively a $194.40 a year add-on. The full plan math sits in our YouCanBookMe pricing guide.

Zapier for teams without developers

Zapier connects through a Zapier API key on the Integrations page, on Professional and Team, and offers 12 triggers. Only the Account Owner can connect it for the organization. For non-developers, Zapier covers most automation needs, though zaps run in batches, which adds delay, while the API answers at once. For CRM sync, HubSpot has a native integration on Professional, other CRMs can take each booking from a webhook, and the API is only needed to backfill history. Our YouCanBookMe integrations guide covers the native connections.

Getting in: the key, authentication and the base URL

Find the API key and your account ID under My Account, then Security. Keys start with ak_, and on a Team plan you need the Organization Owner's key. The API uses simple HTTP Basic authentication over HTTPS: the username is your account ID and the password is the API key, although the help center also mentions the account email as the username. Every call goes to the v1 path on api.youcanbook.me and is scoped to one account, so your key decides which account you reach. Version 1 is current, and the docs mention a future version 2.

Keep the key out of front-end code. Basic authentication sends the same key with every request, and the key gives full access to the account's pages and bookings. It should only ever be used from a server you control, never from a browser or a mobile app, where anyone inspecting the traffic could copy it. Store it in a secrets manager and rotate it when staff change. The Zapier key is separate and can be reset from the Integrations page.

By default, endpoints return a simple subset of fields. A fields parameter with a comma-separated list chooses exactly what comes back, using dots for child objects, though the docs discourage nested wildcards because version 2 will move away from this model. Field control matters for speed and for privacy. Requesting only the start time, end time and reference for a report keeps booker names, emails and answers out of systems that do not need them, which also simplifies your own GDPR obligations.

Booking pages, which the API calls profiles

Reading, creating and updating pages

The docs organize the API around four concepts: profiles, bookings, team members and appointment types. Profiles are booking pages. A profile is a collection of rules that lets someone book your calendar or your team's, with a URL, a unique ID and settings for availability, cancellation rules, logo and booking form. A GET to v1/profiles returns each page's ID, subdomain, title, description, time zone and online status, and fields pull more, such as booking form questions. A POST to v1/profiles creates a page. Each needs a unique subdomain; send nothing and you get a default page with a generated one. Account limits on pages still apply.

A PATCH to v1/profiles/{profileId} changes any setting on a page, and the docs say there is no limit to what can be modified. What you send overwrites what is there. That overwrite is the main risk in bulk updates. A script that sends a partial availability object to fifty pages can wipe settings it never meant to touch, so the safe pattern is to read each page, change one field and send the full object back. Done right, bulk work is the API's strongest use case: universities and large teams can create and update many pages, with locations, team members and appointment types set per page. For smaller teams, the templates in the app may be enough.

Notifications through the actions array

Each profile holds an actions array for notifications. Actions can be EMAIL, SMS or WEBHOOK, and each has an anchor, an offset in minutes and a template. Anchors include booking created, canceled or rescheduled by owner or booker, booking starts, booking ends and no-show. An offset of minus 60 on booking starts sends a reminder an hour before, and booking ends drives follow-ups. Managing actions through the API is the fastest way to roll out a policy change across many pages, such as a second reminder a day before every booking. Otherwise you open each page's notifications screen one at a time.

Team members, invitations and roles

A POST to a profile's team members endpoint adds a member, with a payload holding the member's account, description, email, name, picture and target calendar. Each member needs a unique name on the page, and updates go through PATCH. Invitations run through a separate permissions endpoint: a POST creates the invitation, a PATCH pushes the email to the new member, and a batch endpoint invites several people at once. The same endpoint moves members to Editor for specific pages. For a university or agency onboarding dozens of advisors, that batch call turns an afternoon of manual invitations into a single request.

Each person still has to accept by email and connect their own calendar before bookings can reach them. After that, a GET to the available accounts endpoint lists their calendars, each with a permission level. A level of 30 is required to create events, and you use the calendar URL to assign the member. Roles come in three kinds. Contributors share calendar and Zoom integrations and see their own bookings. Editors change specific pages. Administrators do everything except change the subscription.

Appointment types, and the update that does not work

Appointment types live in the appointmentTypes object of a profile. Settings control whether bookers can combine types, whether the list loads randomly and how types are grouped, and each type has its own duration, price and details. To create one, enable the feature on the profile first with a PATCH. Then send a POST to the appointment types endpoint with a description, name, duration in minutes, image URL and price. Prices follow the currency set on the profile. A DELETE removes a type, and existing bookings keep their data, but check the pages that reference a type before you delete it.

Updating is the weak spot. The guide says plainly that PATCH for appointment types is not working currently, even though the export still lists a partial update operation. Until the documentation changes, any integration that edits prices or durations of existing types has to delete the old type and create a new one. That changes its ID. Links or reports that referenced the old identifier may break, so test the round trip on a sandbox account first.

Bookings: reading, canceling and pulling history

Single bookings

Each completed booking becomes a resource with a unique UUID, and a calendar event is created at the same time. You can read, change, cancel or delete bookings. To read what a booker entered, GET the booking with fields for start, end and answers. Answers come back as codes and strings, such as EMAIL, FNAME and LNAME, which match the shorthand codes on the form. To cancel, PATCH the booking and set its cancellation field to true, as the bookings guide shows, and your configured notifications then fire. A DELETE also exists in the export. Use PATCH when the booker should be told.

Paging versus querying

A GET to the bookings endpoint returns 10 bookings per page, with pagination links in the Link header that move forwards or backwards by start time. The API sets the boundaries, so pages never repeat bookings. The query endpoint is the better tool for history. It filters by page, status, time range and search text, with a page size from 10 to 500 and 50 by default. The difference is large. Pulling a year of history for a busy account with 1,000 bookings takes 100 requests at ten per page, while the query endpoint can fetch the same history in two calls, by our arithmetic.

Status filters cover tentative, rejected, upcoming, in progress, finished, no-show and cancellations, and search text can match title, form answers or reference. That makes reporting simple: count no-shows, cancellations and volume per page by status and time range. CSV exports cover simple needs without code, while the API suits dashboards that refresh automatically. The docs say this endpoint uses a lenient rate limit for now, to be tightened later.

Building your own booking flow with intents

The booking flow is built around an intent, a recipe of selections such as team member, appointment type, time zone and duration. You POST to create the intent with the page's subdomain and a time zone, PATCH selections, ask for available times, PATCH a start time and confirm. The availability answer reflects every rule on the page, including notice periods and buffers. That is what makes a custom front end possible, with the page's own rules still in force. Confirming creates the booking and triggers notifications. On round robin pages, PATCH the start time first and then set the team member to AUTO, and the page's distribution rules pick the host.

A POST to a profile's intents endpoint creates a one-time booking link, valid for up to 180 days, with no cap on how many you create. Recruiting and sales teams use them to send each candidate or prospect a personal invitation that cannot be forwarded and reused, and a nightly job can generate fresh links for every new lead. The help center also shows how to build them through Zapier, which needs API access and a paid Zapier account.

Limits, errors and what the docs admit

The docs say a 429 response means your account hit the rate limit ^[4]. The threshold is not published and may change, and version 2 is planned with an exponential algorithm per endpoint type. Without a number, design every integration as if limits were tight. Queue requests, wait and retry after any 429 with increasing delays, and avoid tight loops that poll the bookings endpoint every few seconds. Calendly, by contrast, publishes 500 requests per user per minute on paid plans and 50 on Free, and offers an official MCP server. A published limit lets a team size its jobs in advance. An unpublished one forces defensive coding.

For errors, the export defines YcbmException and YcbmBindingError schemas. Binding errors usually mean a bad field, and adding a duplicate team member returns a clear message that the name already exists. Log the full response. Stoplight's Export button produces an OpenAPI 3.0.1 file with 14 operations, plus schemas you can use to generate typed clients. The guides describe more, including intents, permissions and the bookings query. Treat the guides as the fuller map.

The export also lists Salesforce task and upsert action types next to email, SMS and webhook, but the enterprise post says Salesforce works through Zapier. We could not confirm a native Salesforce setup, so ask sales before relying on it. Support will not carry you far either. YouCanBookMe support helps only with basic API questions, and the help center says it is not trained for in-depth troubleshooting and suggests a developer. Budget for your own engineering time.

Testing safely and handling the data

There is no sandbox for Stripe payments, so use a separate trial account or a test page for API work. Create test bookings, then cancel them with a PATCH, and never test bulk updates on live pages. Booking data is deleted 24 months after each booking by default. Data you pull through the API becomes your responsibility to protect, and as controller under GDPR, you decide how long to keep it. We did not call the API ourselves; this guide is built from the published docs and help center. A first session looks like this:

• Confirm you are on Team.
• Get the owner's key.
• Test Basic authentication with a GET to profiles.
• Use fields to trim responses.
• Build retries for 429 errors.
• Keep a test page for experiments.

The bottom line

The YouCanBookMe API is broad and honest about its gaps. Its limits are cost, owner-only keys, unpublished rate limits and an appointment type update that does not work. For simple automations, webhooks on Professional are the better value, and Zapier covers teams without developers. The API is a good fit for organizations already on Team that want to automate page management, reporting or a custom booking flow. It is a poor fit for solo users whose needs end at sending booking data somewhere. Read the guides, not just the export, and plan for retries.