Register and use HubSpot Timeline Events API to create custom event types and write behavioral events on CRM contacts
domain: developers.hubspot.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Create an event template via POST /crm/v3/timeline/<appId>/event-templates with a name and tokens array defining custom data fields
Each token has name, label, type (date, string, number, enumeration) and optional options for enumeration types
Write an event instance via POST /crm/v3/timeline/<appId>/events with objectId (the contact's HubSpot ID), eventTemplateId, and a tokens map
Events appear on the contact timeline in the HubSpot UI immediately after successful creation
Use the extraData field to embed structured JSON that renders as a detail section below the event headline on the timeline
Query events for a contact by GET /crm/v3/timeline/<appId>/events/<eventTemplateId> filtered by objectId
Known gotchas
Timeline event templates are scoped to a specific app ID; templates created under one app are not visible to other apps in the same portal
Events cannot be updated after creation; if a correction is needed a new event must be written; plan for idempotent event IDs using a client-assigned id field to prevent duplicates on retry
The API requires a private app token or OAuth token with the timeline scope; using a legacy API key with timeline endpoints returns an authorization error
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?