The Note object
The following fields are accepted on write via POST /api/v1/notes.
| Field | Type | Notes |
|---|---|---|
id | string | CUID, assigned on create (read-only) |
body | string (required) | Max 10,000 characters |
pinned | boolean | Defaults to false |
externalId | string | null | Your system's ID — upsert key and dedupe handle (max 200 chars) |
contactId | string | null | Link to an existing contact by its agentlyleads record ID |
dealId | string | null | Link to an existing deal by its agentlyleads record ID |
companyId | string | null | Link to an existing company by its agentlyleads record ID |
contactExternalId | string | null | Resolve the linked contact by its externalId instead of contactId (max 200 chars) |
dealExternalId | string | null | Resolve the linked deal by its externalId instead of dealId (max 200 chars) |
companyExternalId | string | null | Resolve the linked company by its externalId instead of companyId (max 200 chars) |
createdAt | string (ISO 8601) | Assigned on create (read-only) |
updatedAt | string (ISO 8601) | Updated on every write (read-only) |
Example object
{
"id": "cmq1abc2def3ghi4jkl5",
"body": "Sent the revised proposal, waiting on legal sign-off.",
"pinned": false,
"externalId": "hs_note_321",
"contactId": null,
"dealId": "cmq6mno7pqr8stu9vwx0",
"companyId": null,
"createdAt": "2025-06-01T12:00:00.000Z",
"updatedAt": "2025-06-01T12:00:00.000Z"
}Notes on specific fields
body is the only required field. All other fields are optional on write.
pinned determines whether the note is surfaced at the top of the workspace notes list. Defaults to false when omitted on create.
externalId is the upsert key. A row with an externalId that matches an existing note in the workspace updates that note instead of creating a duplicate.
Linking a contact, deal, or company can be done either by agentlyleads record ID (contactId/dealId/companyId) or by an external system's ID (contactExternalId/dealExternalId/companyExternalId), which is resolved against that record's own externalId. If an *ExternalId is supplied but no matching record exists in the workspace, that row fails — it does not fall back to creating an unlinked note. A note can be linked to a contact, a deal, and a company simultaneously.