Register a timeline event type for your app by POSTing to the Timeline Event Types API, specifying the object type (CONTACT, COMPANY, DEAL), a name, and header/detail templates using HubSpot template tokens
Define event type properties (templateTokens) on the event type to declare what data fields each event will carry, specifying the name, type, and optional label
Create timeline events by POSTing to the events endpoint with the eventTemplateId, the objectId of the CRM record to attach the event to, and a tokens object with values for each declared property
Use a deterministic id for each event to make event creation idempotent; reposting the same id updates the event instead of creating a duplicate
Verify the events appear on the CRM record's activity timeline in the HubSpot UI by navigating to the contact or company record
Retrieve events for a record programmatically using the GET events endpoint filtered by eventTemplateId and objectId
Known gotchas
Timeline event types are scoped to the HubSpot app (not the portal); the app must be installed in the target portal for events to appear, and the eventTemplateId is app-specific
The header and detail templates use Mustache-style token syntax referencing the declared templateTokens; malformed templates render as empty strings on the timeline without surfacing an error
Timeline events do not appear in CRM search results or workflow enrollment criteria; they are display-only in the timeline and cannot be used as segmentation or automation triggers
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