When an outside system talks to a customer, the sales team usually wants to see it in HubSpot: a support summary on the contact, a "call back on Friday" task for the owner, or a note on the deal saying a contract was signed. HubSpot stores these as engagements, and two of the most useful ones, notes and tasks, are ordinary CRM objects you can create with the v3 CRM API.
This guide shows how to create a note and a task, attach them to the right record in the same request, mark tasks complete, and find a user's open tasks. The examples use Node.js 18+ (built-in fetch) and a private app access token.
Before you start
- Create a private app (or use an OAuth app) and keep the access token on the server, never in browser code.
- Give the app the scopes listed on the notes and tasks reference pages, plus read/write scopes for the records you attach them to (for example
crm.objects.contacts.readandcrm.objects.contacts.write). - Know the ID of the record you want to attach to. If you only have an email address, look the contact up first with the CRM search API.
// hubspot.js - a tiny helper used by every example below
const BASE = 'https://api.hubapi.com';
export async function hs(path, { method = 'GET', body } = {}) {
const res = await fetch(BASE + path, {
method,
headers: {
Authorization: 'Bearer ' + process.env.HUBSPOT_TOKEN,
'Content-Type': 'application/json',
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.status === 204) return null;
const data = await res.json();
if (!res.ok) {
throw new Error('HubSpot ' + res.status + ': ' + (data.message || res.statusText));
}
return data;
}
The one property you must not forget: hs_timestamp
Both notes and tasks require hs_timestamp. It means different things for each object:
- On a note, it is when the note happened. It decides where the note appears on the record timeline.
- On a task, it is the due date.
HubSpot accepts either a Unix timestamp in milliseconds or an ISO 8601 UTC string. new Date().toISOString() is the simplest choice in JavaScript. Because the property is required, a create request without it fails.
Create a note attached to a contact
Send POST /crm/v3/objects/notes. The body text goes in hs_note_body (simple HTML is allowed), and hubspot_owner_id sets who the note is attributed to. The associations array links the note to a record in the same request, so you do not need a second call.
import { hs } from './hubspot.js';
export async function addNoteToContact(contactId, text, ownerId) {
return hs('/crm/v3/objects/notes', {
method: 'POST',
body: {
properties: {
hs_timestamp: new Date().toISOString(),
hs_note_body: text,
...(ownerId && { hubspot_owner_id: String(ownerId) }),
},
associations: [
{
to: { id: String(contactId) },
types: [
{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 202 },
],
},
],
},
});
}
const note = await addNoteToContact(
'51',
'<p>Support ticket #1042 closed. Customer confirmed the fix.</p>'
);
console.log('Created note', note.id);
The response contains the new note's id and its properties. Keep the ID if you may need to update or delete the note later.
Association type IDs for notes and tasks
The associationTypeId tells HubSpot what kind of link to create. It depends on both the source object (note or task) and the target object. These are the HubSpot-defined default IDs from the associations documentation:
| From | To contact | To company | To deal | To ticket |
|---|---|---|---|---|
| Note | 202 | 190 | 214 | 228 |
| Task | 204 | 192 | 216 | 230 |
Use associationCategory: 'HUBSPOT_DEFINED' with these IDs. A note can be associated with several records at once: add one object per record to the associations array, for example the contact and the deal it is about. If you are unsure of an ID, call GET /crm/v4/associations/notes/contacts/labels (swap the object names as needed) to list the valid types for your account.
Create a follow-up task for a deal owner
Tasks use POST /crm/v3/objects/tasks. Besides hs_timestamp (the due date), the most useful properties are:
hs_task_subject: the title shown in the task list.hs_task_body: the details.hs_task_status:NOT_STARTEDorCOMPLETED.hs_task_priority:LOW,MEDIUMorHIGH.hs_task_type: the kind of task, for exampleCALLorEMAIL. The tasks reference page lists every accepted value, including the generic to-do type.hubspot_owner_id: the user who should do the task. Without it, the task is unassigned.
import { hs } from './hubspot.js';
export async function createFollowUpTask({ dealId, ownerId, subject, details, dueInDays = 2 }) {
const due = new Date(Date.now() + dueInDays * 24 * 60 * 60 * 1000);
return hs('/crm/v3/objects/tasks', {
method: 'POST',
body: {
properties: {
hs_timestamp: due.toISOString(),
hs_task_subject: subject,
hs_task_body: details,
hs_task_status: 'NOT_STARTED',
hs_task_priority: 'HIGH',
hs_task_type: 'CALL',
hubspot_owner_id: String(ownerId),
},
associations: [
{
to: { id: String(dealId) },
types: [
{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 216 },
],
},
],
},
});
}
const task = await createFollowUpTask({
dealId: '9876543210',
ownerId: '123456',
subject: 'Call about renewal quote',
details: 'Customer asked for a 2-year price. Confirm seats and send the quote.',
});
console.log('Created task', task.id);
Owner IDs are not user IDs. Get them from GET /crm/v3/owners, which returns each owner's id and email address, and cache the mapping instead of looking it up on every request.
Mark a task complete
Updating works like any other CRM object: send a PATCH request to /crm/v3/objects/tasks/ followed by the task ID, with only the properties you want to change.
export async function completeTask(taskId) {
return hs('/crm/v3/objects/tasks/' + taskId, {
method: 'PATCH',
body: { properties: { hs_task_status: 'COMPLETED' } },
});
}
Find a user's open tasks
Tasks support the CRM search endpoint, so you can list everything still open for one owner, soonest due date first:
export async function openTasksForOwner(ownerId) {
const data = await hs('/crm/v3/objects/tasks/search', {
method: 'POST',
body: {
filterGroups: [
{
filters: [
{ propertyName: 'hubspot_owner_id', operator: 'EQ', value: String(ownerId) },
{ propertyName: 'hs_task_status', operator: 'NEQ', value: 'COMPLETED' },
],
},
],
sorts: [{ propertyName: 'hs_timestamp', direction: 'ASCENDING' }],
properties: ['hs_task_subject', 'hs_timestamp', 'hs_task_priority', 'hs_task_status'],
limit: 50,
},
});
return data.results;
}
Filters inside one filter group are combined with AND. If you expect more than 50 results, follow paging.next.after as described in our CRM search API guide.
Read the notes on a record
To show a contact's notes in your own app, first get the associated note IDs with the associations v4 endpoint, then read them in one batch:
export async function notesForContact(contactId) {
const links = await hs('/crm/v4/objects/contacts/' + contactId + '/associations/notes?limit=100');
const ids = links.results.map((r) => ({ id: String(r.toObjectId) }));
if (ids.length === 0) return [];
const batch = await hs('/crm/v3/objects/notes/batch/read', {
method: 'POST',
body: { inputs: ids, properties: ['hs_note_body', 'hs_timestamp', 'hubspot_owner_id'] },
});
return batch.results.sort(
(a, b) => new Date(b.properties.hs_timestamp) - new Date(a.properties.hs_timestamp)
);
}
Batch read accepts up to 100 inputs per call, which matches the page size used above. For records with more notes, follow the association paging and read in chunks.
Practical tips
- Avoid duplicates on retries. Creating a note is not idempotent. If your job may run twice, store the returned note or task ID next to your own event ID, and skip the create when it already exists.
- Escape the note body.
hs_note_bodyis rendered as HTML in HubSpot. If the text comes from a customer or another system, escape<,>and&before you send it. - Use UTC for due dates. Build task dates with
toISOString(). HubSpot shows them in each user's own time zone. - Respect rate limits. If you log many activities at once, use the batch create endpoints (
/crm/v3/objects/notes/batch/createand/crm/v3/objects/tasks/batch/create) and handle429responses with backoff, as shown in our rate limit guide. - Delete carefully. Sending a
DELETErequest to/crm/v3/objects/notes/followed by the note ID archives the note and removes it from the record timeline. Prefer completing tasks over deleting them, so the history stays visible.
Summary
Notes and tasks are regular CRM objects in HubSpot's v3 API. Always send hs_timestamp, attach the engagement to its record with the right associationTypeId in the create request, set hubspot_owner_id on tasks so they land in someone's queue, and use search and batch endpoints to read them back efficiently.
