Notes

Please note: This API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer TermsDeveloper Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API. For the latest stable version of the engagements API, check out the legacy engagements overview.

You can log notes on CRM records to add information to the record timeline. 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 the conversation details. Other users in the account will then be able to view and reference that note.

You can manage notes either in HubSpot or through 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, which can contain the following fields:

Use this table to describe parameters / fields
FieldDescription
hs_timestamp

Required. This field marks the note's time of creation and determines where the note sits on the record timeline. You can use either a Unix timestamp in milliseconds or UTC format. 

hs_note_body

The note's text content, limited to 65,536 characters.

hubspot_owner_id

The ID of the owner associated with the note. This field determines the user listed as the note creator on the record timeline in HubSpot.

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

JSON
// Example POST request to https://api.hubspot.com/crm/v3/objects/notes
{
  "properties": {
     "hs_timestamp": "2021-11-12T15:48:22Z",
     "hs_note_body": "Spoke with decision maker Carla.",
     "hubspot_owner_id": "14240720"
  }
}

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

Associate notes with records

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}/{associationType}. The request URL contains the following fields:

Use this table to describe parameters / fields
FieldDescription
noteId

The ID of the note.

toObjectType

The type of object that you want to associate the note with (e.g., contact or company)

toObjectId

The ID of the record that you want to associate the note with.

associationType

The ID of the association type between the note and the other object type. You can retrieve this value through the associations API.

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}/{associationType}

Retrieve notes

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 of notes, make a GET request to /crm/v3/objects/notes.

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

Use this table to describe parameters / fields
ParameterDescription
properties

A comma separated list of the properties to be returned in the response. If the requested note doesn't have a value for a property, it will not appear in the response.

associations

A comma separated list of object types to retrieve associated IDs for. Any specified associations that don't exist will not be returned in the response.

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.

Update notes

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:

JSON
// Example PATCH request to https://api.hubspot.com/crm/v3/objects/notes/{noteID}
{
"properties": {
    "hs_timestamp": "2021-11-12T15:48:22Z",
    "hs_note_body": "Spoke with decision maker Carla.",
    "hubspot_owner_id": "14240720"
    }
  }

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.

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.

Delete notes

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.


Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.