API Reference

Timeline and search

Everything that happened with one contact, company or deal in your CRM, newest first, as its page in PristineSend shows it. And a search across companies, deals and contacts.

Overview

MethodPathDescription
GET/api/v1/timelineOne contact's, company's or deal's timeline, newest first.
GET/api/v1/crm/searchCompanies, deals and contacts that match some text.

Both need the crm:read scope and an account with the CRM turned on. Both only read.

A record's timeline

GET/api/v1/timeline?contact_id={id}
ParameterTypeDescription
contact_id / company_id / deal_idstringExactly one: the record whose timeline to read.
limitnumber1 to 100, 50 when left out.
cursorstringnext_cursor from the page before. A timeline's cursor is its own: use the one it gave.

Every timeline holds the replies and signups of its people (the contact, a company's contacts, a deal's contacts), the history and notes of its deals, and its own notes and tasks; a contact's also holds the emails you sent them. The timeline is built when it is read, so it always says what is true now: a note deleted in PristineSend is no longer on it.

import { PristineSend } from "pristinesend"

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

for await (const item of await ps.timeline.list({ contact_id: contactId })) {
  if (item.kind === "reply") console.log("replied", item.at, item.subject)
  if (item.kind === "note") console.log(item.note_kind, item.body)
}

What an item holds

Every item has kind, at (when it happened) and id, then the fields of its kind:

kindTypeDescription
emailkindOn a contact's timeline, a campaign or automation email you sent them: subject, and when it was delivered, opened, clicked, bounced, marked as spam, unsubscribed from or replied to.
replykindA reply to a tracked email: who wrote, to which address, its subject, whether a person wrote it or it was automatic, and what the pipeline did with it. Never the reply's words.
formkindA signup on one of your forms: the form, and when it was submitted and confirmed.
bookingkindA meeting booked on one of your booking pages or through Calendly or Cal.com (provider: pages, calendly or calcom): the guest, the meeting's name, starts_at and ends_at, the host, status (booked or canceled), who cancelled and when, and rescheduled_from_starts_at when it is a new time for an earlier booking. Never the booking's answers, location or link.
deal_eventkindA deal's history: made, moved, changed, a contact added, taken off or made the main contact, or marked replied, with who did it.
notekindA note: its kind, words and author.
taskkindA task: its title, due date, and when and by whom it was finished.

Errors

StatuscodeWhen
400missing_fieldNo record named, or a search with no q.
400invalid_fieldA parameter the endpoint does not take, an id that is not one, a record that isn't the account's, a cursor that isn't one the timeline gave, or q over 200 characters (param names it).
400invalid_requestTwo records named at once.
403insufficient_scopeThe key lacks crm:read.
403crm_not_enabledNobody has turned the CRM on for this account yet.
503service_unavailableA read behind the request failed: send the same request again.

See Error codes for the envelope and the full list.