Here's how to create a note on a contact through the API.

Developer Support APIs & Integrations
1

I spent hours fighting through this poorly designed API that HubSpot “convieniently” doesn’t let you have access to support for its usage. To help you get your note added without errors such as the ones below, I’m posting this thread.

Errors this will solve:

1. Cannot deserialize value of type `java.util.HashSet<com.hubspot.inbounddb.associations.base.AssociationSpec>` from Object value

2. What are the proper IDs for connecting a note to a contact, and where does the Contact ID actually go? Can I use an email, or does it need to be the contact ID?

So, first, let’s start with question #2, partially. No, you can’t use an email address as the ID, and it needs to be the numerical ID of the contact. Now, let’s examine the request.

POST /crm/v3/objects/notes

Using the official PHP SDK available on Github:

$this->hubspot->apiRequest([

‘method’ => ‘POST’,

‘path’ => ‘/crm/v3/objects/notes’,

‘body’ => [

‘properties’ => [

‘hs_timestamp’ => 1730678665,

‘hs_note_body’ => “Your note here.”,

],

‘associations’ => [

[

“to” => [

“id” => 123456789, // Don’t be decieved by some other posts with 51 or 305 or some short number here. This is the long contact ID from the URL on the contact’s profile page.

],

“types” => [

[ // IMPORTANT! Notice that this is a NESTED array! This took me all day to notice that they said typeS, not type, and that while you’ll only ever use one type, you need to make this single type nested.

“associationCategory” => “HUBSPOT_DEFINED”,

“associationTypeId” => 202, // This is the correct ID used for attaching this brand new note to an existing contact. Do not use 201, which is how you attach a brand new other object to an existing note.

],

],

],

],

],

]);

Problem 1 above is solved by nesting the array in “types” as noted in the comments. Problem #2 is also noted in the comments above. (Blame HubSpot for the lack of indentation on the code. I copy and pasted my indented code.)

Hopefully this saves someone else countless hours. I’m a seasoned software engineer of nearly 22 years, and this was not easy to come by.

2

@NSaad wrote:

I spent hours fighting through this poorly designed API that HubSpot “convieniently” doesn’t let you have access to support for its usage. To help you get your note added without errors such as the ones below, I’m posting this thread.

Errors this will solve:

1. Cannot deserialize value of type `java.util.HashSet<com.hubspot.inbounddb.associations.base.AssociationSpec>` from Object value

2. What are the proper IDs for connecting a note to a contact, and where does the Contact ID actually go? Can I use an email, or does it need to be the contact ID?

So, first, let’s start with question #2, partially. No, you can’t use an email address as the ID, and it needs to be the numerical ID of the contact. Now, let’s examine the request.

POST /crm/v3/objects/notes

Using the official PHP SDK available on Github:

$this->hubspot->apiRequest([

‘method’ => ‘POST’,

‘path’ => ‘/crm/v3/objects/notes’,

‘body’ => [

‘properties’ => [

‘hs_timestamp’ => 1730678665,

‘hs_note_body’ => “Your note here.”,

],

‘associations’ => [

[

“to” => [

“id” => 123456789, // Don’t be decieved by some other posts with 51 or 305 or some short number here. This is the long contact ID from the URL on the contact’s profile page.

],

“types” => [

[ // IMPORTANT! Notice that this is a NESTED array! This took me all day to notice that they said typeS, not type, and that while you’ll only ever use one type, you need to make this single type nested.

“associationCategory” => “HUBSPOT_DEFINED”,

“associationTypeId” => 202, // This is the correct ID used for attaching this brand new note to an existing contact. Do not use 201, which is how you attach a brand new other object to an existing note.

],

],

],

],

],

]);

Problem 1 above is solved by nesting the array in “types” as noted in the comments. Problem #2 is also noted in the comments above. (Blame HubSpot for the lack of indentation on the code. I copy and pasted my indented code.)

Hopefully this saves someone else countless hours. I’m a seasoned software engineer of nearly 22 years, and this was not easy to come by.

Thank you for sharing this solution

Just to clarify, when using the associationTypeId of 202, is this ID universal for all notes associated with contacts, or could it change depending on other factors, like custom object relationships? And with the hs_timestamp you provided, is that supposed to be in a specific timezone, or does HubSpot handle that automatically as UTC?

3

Super helpful thank you!! That probably saved me days

4

Super helpful thank you!! That probably saved me days
Raw JSON body for anyone to use is below

{

“properties”: {

“hs_timestamp”: {{timestampMs}},

“hs_note_body”: “Note number 9”

},

“associations”: [

{

“to”: {

“id”: {{replace with 10 digit string in contact url}}

},

“types”: [

{

“associationCategory”: “HUBSPOT_DEFINED”,

“associationTypeId”: 202

}

]

}

]

}
If in postman, here is the pre-request script that generates the right timestamp because the default is seconds, not miliseconds but hubspot only accepts miliseconds as the unix time stamp

// Generate the current timestamp in milliseconds

const timestampMs = new Date().getTime();

// Store the timestamp in an environment variable named ‘timestampMs’

pm.environment.set(‘timestampMs’, timestampMs);

5

Thank you! This was exactly what I needed.

6

I am still getting one major issue
Using this as Body

{

“properties”: {

“hs_note_body”: “AG Testing: note_body.”,

“hs_timestamp”: 1768688095000

},

“associations”: [

{

“to”: { “id”: “id” },

“types”: [

{

“associationCategory”: “HUBSPOT_DEFINED”,

“associationTypeId”: 202

}

]

}

]

}
URL: https://api.hubapi.com/crm/v3/objects/notes
I am getting 201 Created status too after creating
But major issue
That note is not visible in UI in that contact page. Why this is happening, Please help

7

Hey @aryang23-airmdr - thanks for following up here!
Were you able to utilize the raw JSON body provided by @NGonzalez5? I want to make sure we provide the Community all of the context possible to get this resolved for you!
Shane, Senior Community Moderator

8

Yes, I am using the same @STierney

9

Hey @aryang23-airmdr - thanks for confirming this!
@NGonzalez5, @Ben_M, and @Anton - any follow-up context on this inquiry?
Shane, Senior Community Moderator