HubSpot API 400: property does not exist"

TL;DR

HubSpot properties are addressed by internal name, not label, and the two often differ. Fetch the property list for the object, copy the exact internal name, and fix your payload. Cache the property map so agents stop guessing names at runtime.

Error

{
  "status": "error",
  "message": "Property "company_size" does not exist",
  "correlationId": "aaaa-bbbb-cccc"
}

Steps

1. GET /crm/v3/properties/companies (or contacts, deals) to list every property with its internal name and label. Expected: you see the real name, for example "hscompanysize" vs the label "Company size".
2. Replace the wrong name in your payload with the exact internal name, case-sensitive. Expected: the 400 becomes a 200.
3. For search filters, the property name in filterGroups must also be the internal name. Expected: search 400s clear up too.
4. Cache the property name map in your agent at startup and refresh it daily. Expected: schema drift stops breaking the agent at 3am.
5. When creating custom properties, record the internal name you chose at creation time. Expected: no label-guessing ever again.

When to use

• HubSpot API returns 400 saying a property does not exist.
• Search API filterGroups fail on a property name.
• An agent worked yesterday and fails today after someone renamed a property label.

When not to use

• ASSOCIATIONLIMITREACHED (associations, not properties).
• 403 errors (permissions, not names).
• Salesforce field errors (different platform).

Tool compatibility

• HubSpot CRM API v3 properties endpoints for contacts, companies, deals, tickets.
• Private apps with the appropriate property read scopes.

Variant phrasings

Property values were not valid

A sibling error: the name exists but the value violates the type or options.

filterGroups invalid on property

Same root cause in search filters; use the internal name there too.

Why it happens

HubSpot shows friendly labels in the UI but the API only accepts internal names, which are often prefixed or snake_cased differently. Renaming a label never changes the internal name, but humans and agents both reach for the label first.

Edge cases

• Deleted properties keep their internal names reserved for a time; recreating with the same name can fail.
• Calculated properties cannot be written; they read fine but updates 400.
• Property groups and labels localize; internal names do not, so always map from the API list.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CP9nA7987h6cZeeggjhVrg