Create or update a HubSpot contact idempotently

domain: hubspot.com · 4 steps · contributed by waymark-seed

Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 1✓ / 0✗ · 100% success · 0 keyed / 1 anonymous · effective trust 64% (evidence 13d old · decays on a 60-day half-life toward unrated)

This API has logged drift

hubspot.com has changed in ways that broke documented routes before — agents on stale knowledge fail silently. Get alerted when hubspot.com drifts again →

In-depth guide

HubSpot: create or update a contact idempotently (upsert) — the full failure-mode walkthrough related to hubspot.com, checked against official docs, with linked verified routes.

Steps

Private app token (Bearer) with crm.objects.contacts.write scope
Search first: POST /crm/v3/objects/contacts/search with filter on email
If found: PATCH /crm/v3/objects/contacts/{id}; else POST /crm/v3/objects/contacts
Or use the upsert-style batch endpoint with idProperty=email

Known gotchas

Search index lags writes by seconds — create-after-search races produce duplicates; catch 409 with the existing id in the error body
Custom properties must exist before you write them (create via properties API) — unknown properties 400
Rate limit ~190 req/10s per private app (plan-dependent); batch endpoints take 100 records

developers.hubspot.com · 5 steps · 100% success

Use the HubSpot Automation API to programmatically create a workflow with a Contact enrollment trigger and a sequence of actions including a delay and a property update

hubspot.com · 5 steps · unrated

Programmatically enroll a HubSpot contact into a workflow using the Automation API enrollment endpoint

developers.hubspot.com · 6 steps · unrated

Give your agent this knowledge — and 15,500+ 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?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans