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.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/notes | One record's notes, newest first. |
POST | /api/v1/notes | Write a note on a contact, a company or a deal. |
GET | /api/v1/tasks | The account's tasks, newest first, with filters. |
GET | /api/v1/tasks/{id} | One task. |
POST | /api/v1/tasks | Create 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.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | The note's id. |
kind | string | note, call, meeting or email: what it records. |
body | string | Its words, up to 5,000 characters. |
author | string | null | Who 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_id | string | null | The one record it is on. |
created_at / updated_at | string | When it was written, and last edited. |
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.
| Field | Type | Description |
|---|---|---|
contact_id / company_id / deal_id | string | Exactly one: the record to write it on. |
kind | string | note (when left out), call, meeting or email. |
body | string | Required, 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.
| Field | Type | Description |
|---|---|---|
id | string (uuid) | The task's id. |
kind | string | task (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). |
title | string | What to do, up to 200 characters. |
due_date | string | null | YYYY-MM-DD, a day in the account's time zone. |
assignee_email | string | null | Who it is for, by their email in the team. |
contact_id / company_id / deal_id | string | null | The record it is about, if any. |
about | object | null | That record named: record (contact, company or deal), id and name. |
done / done_at / done_by | boolean / string | null | Whether it is finished, when, and by whom. |
created_by / created_at | string | Who made it, and when. |
reply | object | null | On 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_at | string | Send it back exactly as read when you change its fields. |
| Parameter | Type | Description |
|---|---|---|
status | string | open or done. |
kind | string | task, reply, stop or rebook. |
assignee_email | string | This team member's tasks. |
contact_id / company_id / deal_id | string | At most one: the tasks about this record. |
limit / cursor | number / string | 1 to 100 (50 when left out), and next_cursor from the page before. |
GET /api/v1/tasks/{id} reads one.
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.
{ "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.
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.
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.
| Status | code | When |
|---|---|---|
400 | missing_field | A note with no body or no record, a task with no title, or a change to a task's fields with no updated_at. |
400 | invalid_field | A 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). |
400 | invalid_request | The 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. |
403 | insufficient_scope | The key lacks crm:read (reading) or crm:write (writing). |
403 | crm_not_enabled | Nobody has turned the CRM on for this account yet. |
404 | not_found | This account has no task with that id. |
409 | conflict | The task changed after the updated_at you sent: read it again and redo your change. |
429 | rate_limited | 120 CRM changes a minute per account. Retry after Retry-After. |
503 | service_unavailable | A 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.