Actions

The ballerinax/hubspot.crm.engagement.notes package exposes the following clients:

Client	Purpose
Client	HubSpot Notes API: note CRUD, batch operations, and search.

---

Client

HubSpot Notes API: note CRUD, batch operations, and search.

Configuration

Field	Type	Default	Description
auth	http:BearerTokenConfig|OAuth2RefreshTokenGrantConfig|ApiKeysConfig	Required	Authentication configuration: OAuth 2.0 refresh token, bearer token, or API key.
httpVersion	http:HttpVersion	HTTP_2_0	HTTP protocol version.
timeout	decimal	30	Request timeout in seconds.
retryConfig	http:RetryConfig	()	Retry configuration for failed requests.
secureSocket	http:ClientSecureSocket	()	SSL/TLS configuration.
proxy	http:ProxyConfig	()	Proxy server configuration.
cache	http:CacheConfig	{}	HTTP cache configuration.
compression	http:Compression	AUTO	Response compression mode.
validation	boolean	true	Enable/disable payload validation.

Initializing the client

import ballerinax/hubspot.crm.engagement.notes as hsnotes;

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;

hsnotes:Client notesClient = check new ({
    auth: {
        clientId: clientId,
        clientSecret: clientSecret,
        refreshToken: refreshToken,
        refreshUrl: "https://api.hubapi.com/oauth/v1/token"
    }
});

Operations

Single note operations

Create a note

Signature: post /

Creates a new engagement note with the specified properties and optional associations to other CRM objects.

Parameters:

Name	Type	Required	Description
payload	SimplePublicObjectInputForCreate	Yes	Note properties and associations.
headers	map<string|string[]>	No	Custom HTTP headers.

Returns: SimplePublicObject|error

Sample code:

hsnotes:SimplePublicObject note = check notesClient->/.post({
    properties: {
        "hs_timestamp": "2025-10-30T03:30:17.883Z",
        "hs_note_body": "Meeting summary: Discussed Q4 goals"
    },
    associations: [
        {
            types: [
                {
                    associationCategory: "HUBSPOT_DEFINED",
                    associationTypeId: 190
                }
            ],
            to: {
                id: "91327871528"
            }
        }
    ]
});

Sample response:

{
  "id": "55037676923",
  "properties": {
    "hs_createdate": "2025-10-30T05:00:12.572Z",
    "hs_lastmodifieddate": "2025-10-30T05:00:12.572Z",
    "hs_note_body": "Meeting summary: Discussed Q4 goals",
    "hs_object_id": "55037676923",
    "hs_timestamp": "2025-10-30T03:30:17.883Z"
  },
  "createdAt": "2025-10-30T05:00:12.572Z",
  "updatedAt": "2025-10-30T05:00:12.572Z",
  "archived": false
}

Read a note by ID

Signature: get /[string noteId]

Retrieves a single engagement note by its ID, optionally including associations and property history.

Parameters:

Name	Type	Required	Description
noteId	string	Yes	The ID of the note to retrieve.
properties	string[]	No	Specific properties to return.
associations	string[]	No	Association types to include.
archived	boolean	No	Whether to return archived notes.

Returns: SimplePublicObjectWithAssociations|error

Sample code:

hsnotes:SimplePublicObjectWithAssociations note = check notesClient->/["55037676923"].get();

Sample response:

{
  "id": "55037676923",
  "properties": {
    "hs_createdate": "2025-10-30T05:00:12.572Z",
    "hs_lastmodifieddate": "2025-10-30T05:00:12.572Z",
    "hs_note_body": "Meeting summary: Discussed Q4 goals",
    "hs_object_id": "55037676923",
    "hs_timestamp": "2025-10-30T03:30:17.883Z"
  },
  "createdAt": "2025-10-30T05:00:12.572Z",
  "updatedAt": "2025-10-30T05:00:12.572Z",
  "archived": false
}

Update a note

Signature: patch /[string noteId]

Updates the properties of an existing engagement note by its ID.

Parameters:

Name	Type	Required	Description
noteId	string	Yes	The ID of the note to update.
payload	SimplePublicObjectInput	Yes	Properties to update.
idProperty	string	No	The property to use as the unique identifier.

Returns: SimplePublicObject|error

Sample code:

hsnotes:SimplePublicObject updated = check notesClient->/["55037676923"].patch({
    properties: {
        "hs_note_body": "Updated meeting summary: Finalized Q4 goals and budget"
    }
});

Sample response:

{
  "id": "55037676923",
  "properties": {
    "hs_createdate": "2025-10-30T05:00:12.572Z",
    "hs_lastmodifieddate": "2025-10-30T06:15:30.100Z",
    "hs_note_body": "Updated meeting summary: Finalized Q4 goals and budget",
    "hs_object_id": "55037676923",
    "hs_timestamp": "2025-10-30T03:30:17.883Z"
  },
  "createdAt": "2025-10-30T05:00:12.572Z",
  "updatedAt": "2025-10-30T06:15:30.100Z",
  "archived": false
}

Archive a note

Signature: delete /[string noteId]

Archives (soft-deletes) an engagement note by its ID.

Parameters:

Name	Type	Required	Description
noteId	string	Yes	The ID of the note to archive.

Returns: error?

Sample code:

check notesClient->/["55037676923"].delete();

List notes

Signature: get /

Lists all engagement notes with optional filtering, pagination, and association expansion.

Parameters:

Name	Type	Required	Description
limit	int	No	Maximum number of results to return per page.
after	string	No	Cursor for the next page of results.
properties	string[]	No	Specific properties to return.
associations	string[]	No	Association types to include.
archived	boolean	No	Whether to return archived notes.

Returns: CollectionResponseSimplePublicObjectWithAssociationsForwardPaging|error

Sample code:

hsnotes:CollectionResponseSimplePublicObjectWithAssociationsForwardPaging notes = check notesClient->/.get();

Sample response:

{
  "results": [
    {
      "id": "55037676923",
      "properties": {
        "hs_createdate": "2025-10-30T05:00:12.572Z",
        "hs_lastmodifieddate": "2025-10-30T05:00:12.572Z",
        "hs_note_body": "Meeting summary: Discussed Q4 goals",
        "hs_object_id": "55037676923"
      },
      "createdAt": "2025-10-30T05:00:12.572Z",
      "updatedAt": "2025-10-30T05:00:12.572Z",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "55037676924",
      "link": "https://api.hubapi.com/crm/v3/objects/notes?after=55037676924"
    }
  }
}

Search notes

Signature: post /search

Searches for engagement notes using filters, query text, sorting, and pagination.

Parameters:

Name	Type	Required	Description
payload	PublicObjectSearchRequest	Yes	Search criteria including filters, sorts, query, and pagination.

Returns: CollectionResponseWithTotalSimplePublicObjectForwardPaging|error

Sample code:

hsnotes:CollectionResponseWithTotalSimplePublicObjectForwardPaging results = check notesClient->/search.post({
    filterGroups: [
        {
            filters: [
                {
                    propertyName: "hs_note_body",
                    operator: "CONTAINS_TOKEN",
                    value: "meeting"
                }
            ]
        }
    ],
    properties: ["hs_note_body", "hs_timestamp"],
    limit: 10
});

Sample response:

{
  "total": 1,
  "results": [
    {
      "id": "55037676923",
      "properties": {
        "hs_createdate": "2025-10-30T05:00:12.572Z",
        "hs_lastmodifieddate": "2025-10-30T05:00:12.572Z",
        "hs_note_body": "Meeting summary: Discussed Q4 goals",
        "hs_object_id": "55037676923",
        "hs_timestamp": "2025-10-30T03:30:17.883Z"
      },
      "createdAt": "2025-10-30T05:00:12.572Z",
      "updatedAt": "2025-10-30T05:00:12.572Z",
      "archived": false
    }
  ],
  "paging": {}
}

Batch operations

Create a batch of notes

Signature: post /batch/create

Creates multiple engagement notes in a single request.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectInputForCreate	Yes	Array of note inputs with properties and associations.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

hsnotes:BatchResponseSimplePublicObject|hsnotes:BatchResponseSimplePublicObjectWithErrors batchResult =
    check notesClient->/batch/create.post({
        inputs: [
            {
                properties: {
                    "hs_timestamp": "2025-10-30T03:30:17.883Z",
                    "hs_note_body": "First batch note"
                },
                associations: []
            },
            {
                properties: {
                    "hs_timestamp": "2025-10-30T04:00:00.000Z",
                    "hs_note_body": "Second batch note"
                },
                associations: []
            }
        ]
    });

Sample response:

{
  "completedAt": "2025-10-30T05:01:00.000Z",
  "startedAt": "2025-10-30T05:00:59.500Z",
  "results": [
    {
      "id": "55037676930",
      "properties": {
        "hs_note_body": "First batch note",
        "hs_object_id": "55037676930",
        "hs_timestamp": "2025-10-30T03:30:17.883Z"
      },
      "createdAt": "2025-10-30T05:01:00.000Z",
      "updatedAt": "2025-10-30T05:01:00.000Z",
      "archived": false
    },
    {
      "id": "55037676931",
      "properties": {
        "hs_note_body": "Second batch note",
        "hs_object_id": "55037676931",
        "hs_timestamp": "2025-10-30T04:00:00.000Z"
      },
      "createdAt": "2025-10-30T05:01:00.000Z",
      "updatedAt": "2025-10-30T05:01:00.000Z",
      "archived": false
    }
  ],
  "status": "COMPLETE"
}

Read a batch of notes by ID

Signature: post /batch/read

Reads multiple engagement notes by their internal IDs or unique property values.

Parameters:

Name	Type	Required	Description
payload	BatchReadInputSimplePublicObjectId	Yes	Batch of note IDs and properties to retrieve.
archived	boolean	No	Whether to return archived notes.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

hsnotes:BatchResponseSimplePublicObject|hsnotes:BatchResponseSimplePublicObjectWithErrors batchRead =
    check notesClient->/batch/read.post({
        inputs: [
            { id: "55037676930" },
            { id: "55037676931" }
        ],
        properties: ["hs_note_body", "hs_timestamp"],
        propertiesWithHistory: []
    });

Sample response:

{
  "completedAt": "2025-10-30T05:02:00.000Z",
  "startedAt": "2025-10-30T05:01:59.800Z",
  "results": [
    {
      "id": "55037676930",
      "properties": {
        "hs_note_body": "First batch note",
        "hs_timestamp": "2025-10-30T03:30:17.883Z"
      },
      "createdAt": "2025-10-30T05:01:00.000Z",
      "updatedAt": "2025-10-30T05:01:00.000Z",
      "archived": false
    },
    {
      "id": "55037676931",
      "properties": {
        "hs_note_body": "Second batch note",
        "hs_timestamp": "2025-10-30T04:00:00.000Z"
      },
      "createdAt": "2025-10-30T05:01:00.000Z",
      "updatedAt": "2025-10-30T05:01:00.000Z",
      "archived": false
    }
  ],
  "status": "COMPLETE"
}

Update a batch of notes

Signature: post /batch/update

Updates multiple engagement notes by their internal IDs or unique property values.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectBatchInput	Yes	Array of note IDs and properties to update.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

hsnotes:BatchResponseSimplePublicObject|hsnotes:BatchResponseSimplePublicObjectWithErrors batchUpdate =
    check notesClient->/batch/update.post({
        inputs: [
            {
                id: "55037676930",
                properties: {
                    "hs_note_body": "Updated first batch note"
                }
            },
            {
                id: "55037676931",
                properties: {
                    "hs_note_body": "Updated second batch note"
                }
            }
        ]
    });

Sample response:

{
  "completedAt": "2025-10-30T05:03:00.000Z",
  "startedAt": "2025-10-30T05:02:59.700Z",
  "results": [
    {
      "id": "55037676930",
      "properties": {
        "hs_note_body": "Updated first batch note",
        "hs_object_id": "55037676930"
      },
      "createdAt": "2025-10-30T05:01:00.000Z",
      "updatedAt": "2025-10-30T05:03:00.000Z",
      "archived": false
    },
    {
      "id": "55037676931",
      "properties": {
        "hs_note_body": "Updated second batch note",
        "hs_object_id": "55037676931"
      },
      "createdAt": "2025-10-30T05:01:00.000Z",
      "updatedAt": "2025-10-30T05:03:00.000Z",
      "archived": false
    }
  ],
  "status": "COMPLETE"
}

Upsert a batch of notes

Signature: post /batch/upsert

Creates or updates a batch of engagement notes by unique property values.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectBatchInputUpsert	Yes	Array of note data for upsert operations.

Returns: BatchResponseSimplePublicUpsertObject|BatchResponseSimplePublicUpsertObjectWithErrors|error

Sample code:

hsnotes:BatchResponseSimplePublicUpsertObject|hsnotes:BatchResponseSimplePublicUpsertObjectWithErrors upsertResult =
    check notesClient->/batch/upsert.post({
        inputs: [
            {
                id: "55037676930",
                idProperty: "hs_object_id",
                properties: {
                    "hs_note_body": "Upserted note content"
                }
            }
        ]
    });

Sample response:

{
  "completedAt": "2025-10-30T05:04:00.000Z",
  "startedAt": "2025-10-30T05:03:59.500Z",
  "results": [
    {
      "id": "55037676930",
      "properties": {
        "hs_note_body": "Upserted note content",
        "hs_object_id": "55037676930"
      },
      "createdAt": "2025-10-30T05:01:00.000Z",
      "updatedAt": "2025-10-30T05:04:00.000Z",
      "archived": false,
      "new": false
    }
  ],
  "status": "COMPLETE"
}

Archive a batch of notes

Signature: post /batch/archive

Archives (soft-deletes) multiple engagement notes by their IDs in a single request.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectId	Yes	Array of note IDs to archive.

Returns: error?

Sample code:

check notesClient->/batch/archive.post({
    inputs: [
        { id: "55037676930" },
        { id: "55037676931" }
    ]
});