Notes

You can log notes on CRM records to add information to the record timeline or associate an attachment with a record. For example, if you need to keep track of an offline conversation you had with a contact, you can add a note to their contact record with details and documents related to the conversation. Other users in the account will then be able to view and reference that note.

You can manage notes either in HubSpot or through the notes API. Below, learn the basic methods of managing notes through the API. You can review all available endpoints on the Endpoints tab at the top of this article.

Create a note

To create a note, make a POST request to /crm/v3/objects/notes.

In the request body, add note details in a properties object. You can also add an associations object to associate your new note with an existing record (e.g., contacts, companies).

To create and associate a note with existing records, include an associations object in your request. For example, to create a note and associate it with a company and deal, your request body might look similar to the following:

In the associations object, you should include the following:

Learn more about batch creating notes on the Endpoints tab at the top of this article.

You can retrieve notes individually or in batches. To retrieve an individual note, make a GET request to /crm/v3/objects/notes/{noteId}.

To request a list of all notes, make a GET request to /crm/v3/objects/notes.

For both endpoints, you can include the following query parameters in the request URL:

For example, to retrieve notes with their text content and any associated contact IDs, your request URL might look similar to the following:

https://api.hubapi.com/crm/v3/objects/notes?limit=10&properties=hs_note_body&associations=contact&archived=false.

Learn more about retrieving a batch of notes by internal ID or unique property value on the Endpoints tab at the top of this article.

You can update notes individually or in batches. To update an individual note by its note ID, make a PATCH request to /crm/v3/objects/notes/{noteId}. 

In the request body, include the note properties that you want to update:

HubSpot will ignore values for read-only and non-existent properties. To clear a property value, pass an empty string for the property in the request body.

Learn more about batch updating notes on the Endpoints tab at the top of this article.

To associate a note with other CRM records, such as a contact, make a PUT request to /crm/v3/objects/notes/{noteId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. The request URL contains the following fields:

For example, your request URL might look similar to the following:

https://api.hubspot.com/crm/v3/objects/notes/17147287858/associations/contact/581751/202

Remove an association

To remove an association between a note and a record, make a DELETE request to the same URL as above:

/crm/v3/objects/notes/{noteId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

You can pin a note on a record so it remains on the top of the record's timeline. The note must already be associated with the record prior to pinning, and you an only pin one activity per record. To pin a note, include the note's id in the hs_pinned_engagement_id field when creating or updating a record via the object APIs. Learn more about using the companies,contacts, deals, tickets, and custom objects APIs.

You can delete notes individually or in batches, which will add the note to the recycling bin in HubSpot. You can later restore the note from the record timeline.

To delete an individual note by its note ID, make a DELETE request to /crm/v3/objects/notes/{noteId}.

Learn more about batch deleting notes on the Endpoints tab at the top of this article.