Notes API

Overview

Notes are scoped to a contact — every note belongs to exactly one person. The list endpoint reflects that: you list a contact's notes, not all your notes flat. Updates and deletes are addressed by note ID directly.

For what notes are in product terms — back-dating, the 30-day deletion reality, the no-edit-history rule — see the user-facing Notes page.

Endpoints

Method	Path	Purpose
`GET`	`/api/v1/contacts/:contactId/notes`	List a contact's notes (most recent first).
`POST`	`/api/v1/contacts/:contactId/notes`	Create a note on a contact.
`PATCH`	`/api/v1/notes/:id`	Update a note's body or timestamp.
`DELETE`	`/api/v1/notes/:id`	Delete a note.

List a Contact's Notes

GET /api/v1/contacts/:contactId/notes

Response

{
  "data": [
    {
      "id": "1f2a...",
      "contactId": "8a1d...",
      "body": "Talked about the Q3 roadmap.",
      "occurredAt": "2026-04-30T19:21:00.000Z",
      "createdAt": "2026-04-30T19:21:00.000Z",
      "updatedAt": "2026-04-30T19:21:00.000Z"
    }
  ],
  "total": 12
}

Notes are returned ordered by occurredAt descending — newest first. Soft-deleted notes within the 30-day retention window are not returned; they're not reachable through the API.

404 if the contact doesn't exist or doesn't belong to your account.

Create a Note

POST /api/v1/contacts/:contactId/notes
Content-Type: application/json

{
  "body": "Quick coffee. He's looking to hire two senior PMs in Q3.",
  "occurredAt": "2026-04-30T18:00:00.000Z"
}

Body fields

Field	Type	Notes
`body`	string (1–10,000 chars)	Required. Plain text — no Markdown, no HTML. Whitespace is preserved.
`occurredAt`	ISO 8601 datetime	Optional. Defaults to "now" if omitted. Set this if the conversation didn't happen right now — back-dating is the most important note habit.

Response

201 Created

{ "data": { "id": "...", "body": "...", "occurredAt": "...", ... } }

Validation errors

422 Unprocessable Entity for empty body, body over 10,000 chars, or invalid date.

Update a Note

PATCH /api/v1/notes/:id
Content-Type: application/json

{
  "body": "Quick coffee. He's hiring three senior PMs in Q3, not two.",
  "occurredAt": "2026-04-30T18:30:00.000Z"
}

Both fields are optional. Include only the ones you want to change.

Response

{ "data": { "id": "...", "body": "...", "occurredAt": "...", ... } }

There is no edit history. The latest version is the only version visible through the API.

Delete a Note

DELETE /api/v1/notes/:id

Response

{ "success": true }

The note is removed from the API immediately. The underlying record is held in storage for 30 days and then permanently erased by a daily background job.

There is no API endpoint to restore a deleted note. The only in-product restore path is the Undo toast in the dashboard, which is only available for a few seconds after deletion. After that, the note is gone from any reachable surface — even though it's still in storage during the 30-day window. A restore endpoint is on the roadmap.

No restore through the API today

Treat DELETE as final from the moment you call it. If you need optimistic deletion with rollback in your client, do the rollback locally — Remy can't help you put the note back.

Example: Logging a Meeting in JavaScript

async function logMeeting(contactId, summary, when) {
  const res = await fetch(
    `https://app.remy.com/api/v1/contacts/${contactId}/notes`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.REMY_API_KEY}`,
      },
      body: JSON.stringify({ body: summary, occurredAt: when }),
    }
  );

  if (!res.ok) throw new Error(`Failed: ${res.status} ${await res.text()}`);
  return (await res.json()).data;
}

await logMeeting(
  "8a1d...",
  "Lunch with Alice. She's looking for a fintech CFO.",
  "2026-05-04T12:00:00Z"
);

Audit Trail

Every mutation lands in the Activity Log:

Note Created — POST to a contact's notes.
Note Updated — PATCH a note's body or occurredAt.
Note Deleted — DELETE a note.
Note Restored — only fired by the dashboard Undo toast; not reachable through the API.

Each entry carries authMethod: "api_key" and the IP and user-agent of the calling client.

On this page