Create a Timeline Event Type using POST /crm/v3/timeline/{appId}/event-templates with a name, headerTemplate (Handlebars template for the event title), detailTemplate, and an objectType of CONTACT
Define custom tokens for the event template using the tokens array, specifying name, type (string, number, date, enumeration), and label for each data field the event will carry
Record a timeline event by POSTing to /crm/v3/timeline/events with eventTemplateId, objectId (the HubSpot contact ID), timestamp, and tokens object containing the key-value data for the event
Retrieve events for a contact using GET /crm/v3/timeline/events?objectType=CONTACT&objectId={contactId} to verify events are appearing on the record
Update the Handlebars templates on an existing event template with PATCH /crm/v3/timeline/{appId}/event-templates/{eventTemplateId} if the display format needs changes without recreating the template
Ensure the connected app has the timeline scope granted; timeline events are app-specific and only visible in the context of the app that created them
Known gotchas
Timeline Event Types are scoped to a specific HubSpot app (identified by appId) — events created by one app are not visible or manageable by a different app even in the same portal
The objectId must be the HubSpot internal ID (numeric) for the contact, company, or deal — passing an email address or external ID without prior lookup returns a 404
Handlebars templates in event type definitions use HubSpot's restricted template syntax — full Handlebars features like helpers or partials are not supported and will cause rendering failures
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp