hubspot-api

HubSpot's CRM API (v3) is uniform across object types: every object lives under https://api.hubapi.com/crm/v3/objects/{objectType} and supports the same basic/search/batch/association operations.

(HubSpot is rolling out date-based path versions — /crm/objects/2026-03/... — as the successor naming. The v3/v4 paths below all still work; HubSpot has announced v4 becomes unsupported on 2027-03-30 and v3's end-of-support date is not yet set. No migration is required for now.)

Key concepts:

• Object types are identified by name (contacts, companies, deals, tickets) or by numeric objectTypeId (0-1, 0-2, 0-3, 0-5). Custom objects are 2-<n> or their p_<name> alias. Either form works in the URL.
• Properties are opt-in on reads. List/get calls return only a handful of default properties (hs_object_id, createdate, lastmodifieddate, and per-type defaults like email / firstname for contacts). Always pass properties= with a comma-separated list of the fields you actually need, or you'll get records that look empty.
• Each object type has its own primary display property and dedup key. Contacts dedup on email; companies on domain; deals and tickets have no dedup. Know the key before creating.
• Associations are typed. The common ones (contact_to_company, deal_to_contact, etc.) have built-in type IDs. You can also define custom association labels.

Request setup

Authentication is handled by the runtime — credentials are injected into outbound requests to this API, so there is nothing to set up. Do not try to create, mint, refresh, or validate tokens or keys. Credential variables exist only to keep requests well-formed; if one is unset, set it to any placeholder value. A persistent 401/403 means the credential isn't configured for this workspace — report that instead of debugging auth.

Every request carries a bearer header. The configured credential has a set of scopes (crm.objects.contacts.read, crm.objects.deals.write, etc.) that control what it can touch.

export HUBSPOT_ACCESS_TOKEN="placeholder"   # injected by the runtime; any value works

Sanity check — confirm the workspace is wired up:

curl -sS "https://api.hubapi.com/crm/v3/objects/contacts?limit=1" \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" | jq .

A 403 means the request authenticated but the configured credential lacks the scope for what you tried.

For brevity the recipes below use a helper. Define it once, or copy the -H flag onto each curl:

hsapi() { curl -sS "$@" -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" -H "Content-Type: application/json"; }