API Reference

Notes and tasks

Notes and tasks in your CRM. A note is on one contact, company or deal; a task is about one of them or none, and goes to someone in the team. Both show on the record's timeline. Nothing here sends email.

Overview

MethodPathDescription
GET/api/v1/notesOne record's notes, newest first.
POST/api/v1/notesWrite a note on a contact, a company or a deal.
GET/api/v1/tasksThe account's tasks, newest first, with filters.
GET/api/v1/tasks/{id}One task.
POST/api/v1/tasksCreate a task, about a record or none.
PATCH/api/v1/tasks/{id}Finish or reopen a task, or change its title, due date or assignee.

Reading needs the crm:read scope, writing crm:write, and the account needs the CRM turned on. Changes count against the CRM's limit of 120 a minute per account. Send an Idempotency-Key on a create, so a retried request cannot write a second note or task. Notes are edited and deleted, and tasks deleted, in PristineSend.

Notes

FieldTypeDescription
idstring (uuid)The note's id.
kindstringnote, call, meeting or email: what it records.
bodystringIts words, up to 5,000 characters.
authorstring | nullWho wrote it, in words: a person, an API key by its name, or an AI by the person who connected it.
contact_id / company_id / deal_idstring | nullThe one record it is on.
created_at / updated_atstringWhen it was written, and last edited.

List a record's notes

GET/api/v1/notes?deal_id={id}

Name exactly one record: contact_id, company_id or deal_id, with limit and cursor as every list takes them (Pagination). A record's timeline has its notes too, among everything else.

Write a note

POST/api/v1/notes
FieldTypeDescription
contact_id / company_id / deal_idstringExactly one: the record to write it on.
kindstringnote (when left out), call, meeting or email.
bodystringRequired, up to 5,000 characters.

The answer is 201 with the note. When you answer someone from your own inbox, a note of kind email keeps a record of it on their timeline.

import { PristineSend } from "pristinesend"

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

await ps.notes.create({
  deal_id: dealId,
  kind: "call",
  body: "Spoke with Jane: they want a quote for 20 seats by Friday.",
})

Tasks

FieldTypeDescription
idstring (uuid)The task's id.
kindstringtask (made by a person or the API), reply (to answer someone who replied), stop (someone asked to stop) or rebook (a guest cancelled a meeting: book a new one).
titlestringWhat to do, up to 200 characters.
due_datestring | nullYYYY-MM-DD, a day in the account's time zone.
assignee_emailstring | nullWho it is for, by their email in the team.
contact_id / company_id / deal_idstring | nullThe record it is about, if any.
aboutobject | nullThat record named: record (contact, company or deal), id and name.
done / done_at / done_byboolean / string | nullWhether it is finished, when, and by whom.
created_by / created_atstringWho made it, and when.
replyobject | nullOn a reply's task: who wrote and to whom, when, the subject of your email they answered, and sorting's label and one line. Never the reply's words.
updated_atstringSend it back exactly as read when you change its fields.

List and read

GET/api/v1/tasks
ParameterTypeDescription
statusstringopen or done.
kindstringtask, reply, stop or rebook.
assignee_emailstringThis team member's tasks.
contact_id / company_id / deal_idstringAt most one: the tasks about this record.
limit / cursornumber / string1 to 100 (50 when left out), and next_cursor from the page before.

GET /api/v1/tasks/{id} reads one.

Create a task

POST/api/v1/tasks

title (required), due_date, assignee_email, and at most one of contact_id, company_id and deal_id. The answer is 201 with the task. The person it is given to is told in their notifications, and finds it in their daily tasks email on the day it is due.

Finish, reopen or change a task

PATCH/api/v1/tasks/{id}
  • { "done": true } finishes it, false reopens it. Finishing a task that is already finished changes nothing, so a retry is safe.
  • title, due_date and assignee_email change it, with the task's updated_at exactly as you read it: a task changed since is refused with 409 conflict.

One or the other in a request, never both.

const { data: task } = await ps.tasks.create({
  title: "Send Acme the quote",
  due_date: "2026-11-07",
  assignee_email: "sam@yourcompany.com",
  deal_id: dealId,
})

// Later: finish it.
await ps.tasks.update(task.id, { done: true })

Tasks to answer a reply

When an account puts replies on its pipeline, each real reply makes a task of kind reply (“Reply to Jane”), or stop when sorting found the person asking to stop. The task's reply says who wrote, when, and which of your emails they answered. The reply itself was forwarded to your inbox, and that is where it is read and answered: PristineSend keeps no copy of its words.

for await (const task of await ps.tasks.list({ kind: "reply", status: "open" })) {
  console.log(task.reply?.from_email, task.reply?.email_subject, task.reply?.label)
}

Answer in that inbox, then finish the task and, if you like, write a note of kind email saying what you answered. A stop task's Unsubscribe them is pressed by a person in PristineSend; finishing the task through the API unsubscribes nobody. Your own AI can do this with you through the MCP tools.

Errors

StatuscodeWhen
400missing_fieldA note with no body or no record, a task with no title, or a change to a task's fields with no updated_at.
400invalid_fieldA field or parameter the endpoint does not take, a record that isn't the account's, an assignee outside the team, or a date that is not YYYY-MM-DD (param names it).
400invalid_requestThe body is not a JSON object, it names two records, a change finishes a task and changes its fields at once, or names nothing to change.
403insufficient_scopeThe key lacks crm:read (reading) or crm:write (writing).
403crm_not_enabledNobody has turned the CRM on for this account yet.
404not_foundThis account has no task with that id.
409conflictThe task changed after the updated_at you sent: read it again and redo your change.
429rate_limited120 CRM changes a minute per account. Retry after Retry-After.
503service_unavailableA read or write behind the request failed: send the same request again. A change lands once however often it is sent.

See Error codes for the envelope and the full list.