API Reference

Booking pages

Your booking pages, the times each one offers, and busy times from your AI's calendar, which are kept off every booking page of the person they belong to. The meetings booked on them are in the Meetings API.

Overview

MethodPathDescription
GET/api/v1/booking-pagesEvery booking page of the account.
GET/api/v1/booking-pages/{id}/free-timesA page's free times, as the page offers them.
GET/api/v1/busy-timesA team member's busy times from their AI.
PUT/api/v1/busy-timesReplace a team member's busy times inside a window.

Reading needs the meetings:read scope, sending busy times meetings:write, which is never part of the default access for new agents. The account needs to see the Meetings section and booking pages. Sending busy times counts against the same limit as cancelling meetings, 120 a minute per account. Nothing here books a meeting for anyone, or changes a page.

The booking page object

GET/api/v1/booking-pages
FieldTypeDescription
idstring (uuid)The page's id.
titlestringThe page's title.
hostobjectemail and name of the team member whose hours the page offers.
statusstringdraft or live.
pausedbooleanPaused by its safety check or by PristineSend: it takes no bookings until it is resumed.
in_reviewbooleanA change has been published and waits for its check.
urlstring | nullThe page's address, once it has been live (kept from then on); null before.
lengthsnumber[]The meeting lengths a visitor chooses from, in minutes: the live version's while the page is live, else the draft's.
time_zonestring | nullThe host's time zone, from their hours; null before they set them.

The answer lists every page that is not deleted, newest first. An account keeps at most 50, so there is no cursor.

import { PristineSend } from "pristinesend"

const ps = new PristineSend(process.env.PRISTINESEND_API_KEY!)

for (const page of await ps.bookingPages.list()) {
  console.log(page.title, page.status, page.url)
}

Free times

GET/api/v1/booking-pages/{id}/free-times
ParameterTypeDescription
fromstringThe first day, YYYY-MM-DD, in time_zone. Today there when left out.
daysnumberHow many days from from, 1 to 31. 7 when left out.
lengthnumberThe meeting's length in minutes, one of the page's lengths. The shortest when left out; another is refused, naming the page's.
time_zonestringThe time zone the days are grouped in, such as Europe/Berlin. The host's when left out.

The times are worked out exactly as the page offers them: its live version, the host's hours and changes for a date, their meetings, blocked time and busy times, the notice, how far ahead it books and its daily limit. They are worked out when you ask, and a time can be taken by someone else meanwhile: the page checks again when a person books.

FieldTypeDescription
taking_bookingsbooleanWhether the page takes bookings now.
reasonstring | nullWhy not, while it takes none (below); null while it does.
length / time_zonenumber / stringThe length and the zone the times are for; null while the page takes no bookings.
daysobject[]Every day asked, each with date and times, a day with none included; empty while the page takes no bookings.
days[].times[]objectstarts_at, ends_at, and book_url: the page's own address for that time, which opens its details step.

Each time carries book_url, the page's own address for it. Offer someone that link and they book it themselves, on your page, with its questions and its emails. While the page takes no bookings, reason is one of these:

  • not_live: Never published, or taken down.
  • paused: Paused by its safety check or by PristineSend.
  • account_paused: The account's sending is paused or suspended.
  • turned_off: Booking pages are turned off for the account.
  • no_hours: The host has no booking hours.
  • not_ready: The account can't send yet: a verified sending domain, a default sender or the mailing address is missing.
  • email_allowance: The account's email allowance and its overage cap are used up.
  • plan: The plan takes bookings on fewer pages: an earlier page takes them.
  • unavailable: Booking pages are closed for now, for every account.
const free = await ps.bookingPages.freeTimes(pageId, { days: 7, time_zone: "America/New_York" })

if (free.taking_bookings) {
  for (const day of free.days) {
    for (const t of day.times) console.log(t.starts_at, t.book_url)
  }
} else {
  console.log("Not taking bookings:", free.reason)
}

Busy times

PristineSend doesn't read anyone's calendar. Your own AI can: connect your calendar to it (Google Calendar, Outlook) as well as PristineSend, and have it send the times you're busy, as far ahead as your pages book, before you share a page, whenever your calendar changes, and at least once a day. Busy times are kept off every booking page of the person they belong to.

PUT/api/v1/busy-times
FieldTypeDescription
personstringThe team member's email address. An AI connected through MCP may leave it out to mean the person who connected it; an API key names one.
from / tostringThe window, as times with their zone. to is in the future, at most 90 days from now; from is at most 24 hours ago.
busyobject[]The busy times inside the window, each starts_at and ends_at, at most 500; [] clears the window. Times that overlap or touch are merged.

A send replaces the person's busy times inside the window, and only there: those outside it stay, and one crossing an edge keeps its part outside. So sending the next two weeks each day keeps them current. The answer is their busy times now inside the window, as stored. A meeting already booked in a busy time stays booked: busy times only keep free times off a page. If the AI stops sending, its last busy times stay until they pass. At most 500 are kept for a person from now on. The person needs booking hours, set on Meetings → Your hours.

// What your calendar says is busy for the next two weeks, as one change.
const set = await ps.busyTimes.set({
  person: "sam@yourcompany.com",
  from: "2026-11-20T00:00:00Z",
  to: "2026-12-04T00:00:00Z",
  busy: [
    { starts_at: "2026-11-20T09:00:00Z", ends_at: "2026-11-20T10:30:00Z" },
    { starts_at: "2026-11-24T13:00:00Z", ends_at: "2026-11-24T17:00:00Z" },
  ],
})

const now = await ps.busyTimes.get({ person: "sam@yourcompany.com" })
console.log(now.updated_at, now.updated_by, now.busy.length)

GET /api/v1/busy-times?person=… answers the person's busy times that have not ended, whether they have booking hours (has_hours), and when and by whom busy times were last sent (updated_at, updated_by). The person sees them on Meetings → Your hours too, and can clear them there.

Busy times change what every visitor is offered. Keep meetings:write for the keys and agents that send them, and send each person's from their own calendar.

Test keys

Booking pages have no test copy: a ps_test_ key reads your real pages, free times and busy times. It may not send busy times, which is refused with 403 live_key_required, because they change the times every visitor is offered. Use a ps_live_ key for that.

Errors

StatuscodeWhen
400invalid_fieldA parameter or field the endpoint does not take, a day, number, zone or time that can't be read, a length the page doesn't offer, a window out of bounds, a busy time outside the window, or a person not on the team (param names it).
400missing_fieldfrom, to or busy left out, or person left out with an API key.
400invalid_requestThe body is not a JSON object.
403insufficient_scopeThe key lacks meetings:read (reading) or meetings:write (sending busy times).
403live_key_requiredA test key sending busy times: see Test keys.
404not_foundThe account cannot see the Meetings section or booking pages yet, or has no booking page with that id.
409conflictThe person has no booking hours yet, or would have more than 500 busy times from now on.
429rate_limited120 changes to meetings and busy times a minute per account. Retry after Retry-After.
503service_unavailableA read or write behind the request failed: send the same request again. Sending the same busy times twice changes nothing more.

See Error codes for the envelope and the full list.