Notes API
GET /api/v1/notes
Returns the workspace's notes, sorted by createdAt descending (newest first) — the contact-history view for API consumers. Each note embeds the linked contact, company, and deal (name + external ID) when set. Requires the read:notes scope (or * for full access).
Request
GET /api/v1/notes HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxQuery parameters
| Parameter | Description |
|---|---|
contactExternalId | Return only notes on the contact with this external ID |
companyExternalId | Return only notes on the company with this external ID |
dealExternalId | Return only notes on the deal with this external ID |
pinned | true or false |
updatedSince | ISO 8601 datetime — only notes updated at or after this moment |
limit | Page size, 1–1000 (default 100) |
cursor | The nextCursor value from the previous page |
All parameters are optional and can be combined. Filters that match nothing return an empty list, not a 404.
History for one contact:
GET /api/v1/notes?contactExternalId=hs_contact_123 HTTP/1.1
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxResponse — 200
{
"notes": [
{
"id": "cmq4note0alk34567890",
"body": "Follow up next week about the renewal.",
"pinned": true,
"externalId": "hs_note_321",
"contact": { "name": "Jane Buyer", "externalId": "hs_contact_123" },
"company": null,
"deal": { "name": "Acme Corp — Annual Contract", "externalId": "hs_deal_789" },
"createdAt": "2026-07-18T09:12:00.000Z",
"updatedAt": "2026-07-18T09:12:00.000Z"
}
],
"nextCursor": null
}contact, company, and deal are null when the note has no such link.
Pagination
Responses are cursor-paginated. When more rows exist beyond the requested limit, nextCursor holds the ID of the last returned record — pass it back as cursor to fetch the next page. On the last page, nextCursor is null.