HubSpot

The HubSpot CRM over the API an integration actually calls: contacts, companies, deals, notes and tasks with string-typed properties, associations written in both directions, batch writes that can come back part-failed, and a search index that is behind the writes until the sandbox is advanced. Slug: hubspot

The Attio twin already covers “a CRM”

So this one is not another object-and-record model. It is the three behaviours a HubSpot test portal cannot give you.

1. The search index lags the write

A contact created through POST /crm/v3/objects/contacts is not returned by POST /crm/v3/objects/contacts/search until HubSpot has indexed it. Agents that create a record and then search for it work on a developer’s machine and fail in production — and you cannot ask HubSpot to be slow on demand, so there is no way to test the branch against a real portal. Here the lag is state. The default is one advance, so create-then-search fails out of the box; POST /__twin__/v1/advance closes the gap, and set_search_lag makes it longer or turns it off for a test that does not want the behaviour. The record is readable by id the whole time: it exists, only the index is behind.

2. Everything in `properties` is a string

Numbers, booleans, enumerations, datetimes — all of them. "17", not 17; "true", not true. A caller that assumes typed JSON breaks against HubSpot, and a twin that returned typed JSON would break the pinned SDK, which annotates the map dict[str, str]. Values are coerced to the string form their property’s type has and stored that way, so the round trip is stable in both directions.

3. Duplicate contacts and batch partial failures

A contact create carrying an email another contact holds is a 409 whose message names the existing record’s id — integrations parse it out to recover, which is why it is load-bearing. And a batch can answer 207 multi-status with some rows written and some refused, which the pinned SDK deserializes into a different model from the success: a caller that only handled the success shape reads an AttributeError rather than a failure, and because 207 is a 2xx, nothing raises. Neither is reachable on demand in a shared portal.

Two versions in the paths is not a mistake

HubSpot versions its CRM by path and by nothing else — no dated version, no version header. Objects, properties, owners and pipelines are /crm/v3; associations are /crm/v4. The manifest publishes v3+v4 so this is on the record rather than looking like a typo.

What it models

Area	Modelled
The portal	One HubSpot account per container, configured and empty the way a fresh portal with a private app is: two owners, two deal pipelines with their stages — `default` with HubSpot’s own seven and `enterprise` with three, so a stage from the wrong pipeline is reachable — and the property definitions of all five object types
Authentication	`Authorization: Bearer pat-na1-…` and nothing else, because the pinned SDK builds no other presentation. `401 INVALID_AUTHENTICATION` for a missing header, a scheme that is not `Bearer`, a token that is not shaped like one and a well-formed token nothing recognises
Scopes	HubSpot’s granular scopes as container state, with `403 MISSING_SCOPES` naming what the call needed in both places HubSpot puts them. Notes and tasks are covered by the contacts scopes, which is HubSpot’s own grouping rather than an omission
Rate limits	`429 RATE_LIMIT` with the `X-HubSpot-RateLimit-*` headers, a `Retry-After` and the `policyName` a caller branches on. The window is configurable rather than a claim about a subscription tier, because HubSpot’s limits differ by tier — and the budget headers ride on every answer, not only the refusal
Objects	Create, read, update, archive and list for contacts, companies, deals, notes and tasks, with `idProperty` lookups that address a contact by email address, `properties` and `propertiesWithHistory` selection, inline `associations` on create, and the `associations` expansion on a read
Properties	The full string coercion per type, unknown property names refused rather than stored, read-only and calculated properties refusing a write, enumeration options enforced, and a custom property created through `POST /crm/v3/properties/{type}` validated exactly like a stock one
Archiving	HubSpot’s delete is a soft archive, so “never existed” and “was deleted” are different states: a plain read is `404`, `archived=true` finds it, an archived record refuses a `PATCH`, and its email address is still taken
Associations	`v4` in both directions from one call, HubSpot’s own defined type ids — contact→company `279` with its `Primary` label `1`, and the inverse pair `280` and `2` — the default endpoint writing the most generic type, labelled writes by id, a type id that does not exist for the pair refused, and a company’s associated-contact count derived rather than stored
Search	`filterGroups` ORed across groups and ANDed within one, every operator in HubSpot’s enum, `sorts` in both spellings HubSpot answers to, numeric and datetime properties compared as numbers rather than as text, and the paging ceiling past which HubSpot refuses rather than answering an empty page
Batch	`batch/create` at `201`, `batch/read` with a body-level `idProperty`, `batch/update`, `batch/upsert` with its `new` flag, `batch/archive` at `204`, the hundred-record cap refused before anything is written, and `207` per-row failures a directive can arm on demand
Owners and pipelines	Read-only, because a deal cannot be created without a stage and a record cannot be assigned without an owner. A pipeline carries its stages inline, the default pipeline reports the epoch as its create date, and a write to either is refused as not modelled rather than as missing
Paging	Forward-only, with `after` as the position it actually is — the id of the next record to read, in `hs_object_id` ascending order — `paging` absent on the last page rather than empty, a `limit` above the maximum refused rather than clamped, and `paging.next.link` built on the container’s own host so a paginating client stays inside the sandbox

Advancing the sandbox steps five things, in order: the search index catches up by one, any rate-limit window expires, deals move one stage along their own pipeline stamping the stage’s entered date, contacts move one step along the lifecycle stage sequence stamping its date, and tasks past their due date become overdue. All five are finite, so advancing repeatedly settles rather than reporting forever.

Idempotency

HubSpot has no idempotency keys. It has two other mechanisms and both are modelled: batch/upsert with an idProperty, where a replay updates rather than duplicating and new says which happened; and the duplicate-contact 409 naming the existing id, which is how a caller recovers without one. A replay of any other create makes a second record, and so does this twin.

Scenarios

search-lagging, crm-with-pipeline, paged-contacts, throttled, missing-scope, duplicate-contact, archived-contact.

Not modelled

OAuth app installs and token refresh, webhooks and the CRM card and extension surfaces, Marketing Hub, tickets, line items, products, quotes and custom objects, the timeline API, imports and exports, merge and gdpr-delete, the v4 association batch surface, association labels and limits, property groups and the property batch endpoints, and HubSpot lists. An endpoint HubSpot has and this twin has not built is refused 501 with category: "NOT_MODELED" — never 404 OBJECT_NOT_FOUND, which means a record does not exist and which a caller could reasonably read as an endpoint that was retired. There is no live HubSpot portal behind this twin. Every path, status, required member and page size came from the pinned hubspot-api-client 12.0.0 and HubSpot’s own published OpenAPI documents; the association type ids came from HubSpot’s association-details reference. The twin’s README records every decision the sources left open and which artefact settled the rest.

Getting Started

Concepts

Interfaces

The Attio twin already covers “a CRM”

1. The search index lags the write

2. Everything in `properties` is a string

3. Duplicate contacts and batch partial failures

Two versions in the paths is not a mistake

What it models

Idempotency

Scenarios

Not modelled

​The Attio twin already covers “a CRM”

​1. The search index lags the write

​2. Everything in properties is a string

​3. Duplicate contacts and batch partial failures

​Two versions in the paths is not a mistake

​What it models

​Idempotency

​Scenarios

​Not modelled

The Attio twin already covers “a CRM”

1. The search index lags the write

2. Everything in `properties` is a string

3. Duplicate contacts and batch partial failures

Two versions in the paths is not a mistake

What it models

Idempotency

Scenarios

Not modelled