API Reference

Meetings

Every meeting booked on your booking pages and through Calendly or Cal.com, as the Meetings tab in PristineSend lists them. Read them, and cancel one booked on a booking page.

Overview

MethodPathDescription
GET/api/v1/meetingsThe account's meetings, upcoming or past, 50 a page.
GET/api/v1/meetings/{id}One meeting, a moved one included.
POST/api/v1/meetings/{id}/cancelCancel a meeting booked on one of your booking pages.

Reading needs the meetings:read scope, cancelling meetings:write, which is never part of the default access for new agents. The account needs to see the Meetings section; nothing of the CRM's setup is needed, no pipeline either. Cancels count against a limit of 120 a minute per account. A meeting holds what the Meetings tab shows: never the guest's answers to the page's questions, their phone number or the meeting's place.

The meeting object

FieldTypeDescription
idstring (uuid)The meeting's id.
providerstringWhere it was booked: pages (one of your booking pages), calendly or calcom.
namestring | nullThe meeting's name: Calendly's or Cal.com's event, or the booking page's title.
starts_at / ends_atstringWhen it starts and ends.
booked_atstringWhen the guest booked it.
statusstringbooked, canceled, or rescheduled: moved to another time, which is the meeting rescheduled_to_id.
canceled_by / canceled_atstring | nullWho cancelled it, guest or host (your team, a cancellation through the API included), and when.
rescheduled_fromobject | nullA meeting that replaced another: when that one was (starts_at), and its id, null when we never saw it (a Calendly or Cal.com booking made before you connected).
rescheduled_to_idstring | nullA moved meeting: the meeting at its new time, when we have it.
guestobjectemail, name, and contact_id: the contact with the guest's address, or null when they are not a contact.
hostobjectemail and name, as the booking named them.
booking_page_idstring | nullThe booking page it was booked on; null for Calendly and Cal.com.
can_cancelbooleanA booking page's meeting, booked and not yet started: the cancel endpoint takes it.

List and read

GET/api/v1/meetings
ParameterTypeDescription
whenstringupcoming (when left out): not yet over, soonest first, so a meeting under way stays until it ends. past: over, newest first.
emailstringOnly this guest's meetings, by their email address.
cursorstringnext_cursor from the page before.

The answer is a page of 50 (Pagination). A moved meeting is not listed: its new time is, with rescheduled_from naming the old one, which GET /api/v1/meetings/{id} reads. A guest's meetings are also on their contact's, company's and deal's timelines.

import { PristineSend } from "pristinesend"

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

for await (const meeting of await ps.meetings.list({ when: "upcoming" })) {
  console.log(meeting.starts_at, meeting.guest.email, meeting.provider)
}

Cancel a meeting

POST/api/v1/meetings/{id}/cancel
FieldTypeDescription
messagestring | nullWhat the guest reads in their cancellation email, at most 1,000 characters. Leave the body out, or send {}, for none.

Cancels a meeting booked on one of your booking pages, booked and not yet started (can_cancel), as the host's Cancel on the Meetings tab does: the guest is emailed the cancellation with your message, the time is free again on the page, and the host's email says which API key or connected AI cancelled it. The answer is the meeting, cancelled. A meeting already cancelled answers 200 as it is, so sending the same request again is safe. A meeting booked through Calendly or Cal.com is cancelled there, and the change comes back by itself.

const meeting = await ps.meetings.get(meetingId)

if (meeting.can_cancel) {
  await ps.meetings.cancel(meeting.id, {
    message: "Sorry, something came up. Please book another time on our page.",
  })
}
Cancelling emails the guest. Unlike most changes over the API, a cancel reaches someone outside your account. Ask before an AI cancels a meeting for you, and keep meetings:write for the keys and agents that need it.

Test keys

Meetings have no test copy: a ps_test_ key reads your real meetings. It may not cancel one, which is refused with 403 live_key_required, because cancelling emails the guest and a test key never sends. Use a ps_live_ key for that.

Webhooks

An endpoint can choose booking.created, booking.rescheduled and booking.canceled, for every meeting, on a booking page or through Calendly or Cal.com. Each carries the meeting as this API reads it when the event is delivered. See Webhooks. GET /api/v1/events shows them only to a key with meetings:read.

Errors

StatuscodeWhen
400invalid_fieldA parameter or field the endpoint does not take, a when other than upcoming or past, an email that isn't one, a cursor not from a page before, or a message over 1,000 characters (param names it).
400invalid_requestThe body is not a JSON object.
403insufficient_scopeThe key lacks meetings:read (reading) or meetings:write (cancelling).
403live_key_requiredA test key cancelling a meeting: see Test keys.
404not_foundThe account cannot see the Meetings section yet, or has no meeting with that id.
409conflictA meeting from Calendly or Cal.com (cancel it there), a moved one (the message names its new time's id), or one that has started.
429rate_limited120 changes to meetings a minute per account. Retry after Retry-After.
503service_unavailableA read or write behind the request failed: send the same request again. A meeting is cancelled once, however often the request is sent.

See Error codes for the envelope and the full list.