HubSpot

HubSpot CRM API

Contacts, companies and deals CRUD, search, associations, properties and owners on HubSpot's date-versioned 2026-09 CRM API.

Productivity & workspaceGuided#crm#contacts#deals#sales#marketing#associations

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The HubSpot CRM API reads and writes the records in a HubSpot account: contacts, companies, deals and the links (associations) between them, plus the property definitions and owners those records use. This guided collection covers the everyday CRM sync flow: create or update records, find them with search, link them together and assign them to an owner.

API versions (date-based)

Since 30 March 2026 HubSpot versions its REST APIs by release date instead of v1 to v4. A new version ships every March and September; the newest is 2026-09, and it sits in the URL right after the API family, for example /crm/objects/2026-09/contacts, /crm/properties/2026-09/contacts and /crm/owners/2026-09. The older semantic paths (/crm/v3/objects/..., /crm/v4/associations/...) still work, so code you already have keeps running. This collection puts the version in the apiVersion variable. See https://developers.hubspot.com/docs/developer-tooling/platform/versioning.

Getting a token

Every option below gives a token you send as Authorization: Bearer <token>:

  1. Service key (simplest for one account): in HubSpot open Development > Keys > Service keys > Create service key, name it, add scopes, create, then Show and Copy the key. Guide: https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys
  2. App with static auth on the developer platform, if you also need webhooks or UI extensions: the access token is in the app's settings. https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/overview
  3. Legacy private app token: still works if you already have one (Development > Legacy apps > your app > Auth > Show token), but new legacy private apps can no longer be created since 26 October 2026.

Scopes this collection needs: crm.objects.contacts.read/write, crm.objects.companies.read/write, crm.objects.deals.read/write, crm.objects.owners.read, and crm.schemas.contacts.read for properties. Use a free developer test account (https://developers.hubspot.com/get-started) rather than production data. Paste the token into accessToken (secret).

Base URL

https://api.hubapi.com for every account; there is no separate sandbox host (use a test account or a HubSpot sandbox account instead).

Run order

  1. Start here: list owners (saves ownerId), read contact properties, list deal pipelines (saves pipelineId and dealStage).
  2. Contacts: create (saves contactId), read by ID or by email, update, list.
  3. Companies and Deals: create (saves companyId, dealId), each created with an inline association.
  4. Associations: link the contact to the company, label it as primary, list associations.
  5. Search across contacts and deals. 6. Clean up archives the test records.

Limits

Calls are limited per app or key in a 10-second burst window and per day, and the numbers depend on the account's subscription. CRM search has its own limit of five requests per second per account, at most 200 records per page and 10,000 results per query. Over the limit you get 429. Details: https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines

Common errors

Status / categoryMeaningFix
401 INVALID_AUTHENTICATIONMissing or bad tokenCheck accessToken and the Bearer header.
403 MISSING_SCOPESToken lacks a scopeAdd the scope to the key or app.
404 OBJECT_NOT_FOUNDWrong record ID or archived recordCheck the ID variable.
409 CONFLICTA contact with that email already existsUpdate the existing record (the error message includes its ID).
400 VALIDATION_ERRORUnknown property or bad enumeration valueUse internal property names and option values.
429Rate limitBack off; check Retry-After.

Links

  • API reference (2026-09): https://developers.hubspot.com/docs/api-reference/latest/overview
  • Contacts: https://developers.hubspot.com/docs/api-reference/latest/crm/objects/contacts/guide
  • Associations: https://developers.hubspot.com/docs/api-reference/latest/crm/associations/associate-records/guide
  • Search: https://developers.hubspot.com/docs/api-reference/latest/crm/search-the-crm

Endpoints 25

1. Start here

  • GETList owners/crm/owners/{{apiVersion}}Returns the users who can own records (id, email, firstName, lastName, userId, teams). Owner id is what goes into the hubspot_owner_id property of contacts,…
  • GETRead all contact properties/crm/properties/{{apiVersion}}/contactsLists every property defined for contacts, default and custom, with name (the internal name you use in requests), label, type, fieldType and, for…
  • GETRead one property/crm/properties/{{apiVersion}}/contacts/lifecyclestageReads one property by internal name, here lifecyclestage, including its options. Handy to fetch the current list of lifecycle stages or of a custom dropdown…
  • GETList deal pipelines and stages/crm/pipelines/{{apiVersion}}/dealsLists the account's deal pipelines with their stages. Stage and pipeline IDs differ between accounts, so read them here: the first pipeline's id is saved into…

2. Contacts

  • POSTCreate a contact/crm/objects/{{apiVersion}}/contactsCreates a contact from a properties object of internal names. Include at least email, firstname or lastname; always send email, because HubSpot deduplicates…
  • GETGet a contact by ID/crm/objects/{{apiVersion}}/contacts/{{contactId}}Reads the contact in contactId. Only a few default properties come back unless you list more in properties (comma separated). Add associations=companies,deals…
  • GETGet a contact by email/crm/objects/{{apiVersion}}/contacts/{{contactEmail}}Reads a contact using a unique property instead of the record ID: put the email in the path and set idProperty=email. This is the usual way to look up a…
  • PATCHUpdate a contact/crm/objects/{{apiVersion}}/contacts/{{contactId}}Partially updates the contact in contactId: only the properties you send change. Send an empty string to clear a value. To update by email instead, put the…
  • GETList contacts/crm/objects/{{apiVersion}}/contactsReads a page of contacts, oldest first. limit is up to 100; follow paging.next.after with the after parameter for the next page. Name the properties you need…

3. Companies and deals

  • POSTCreate a company/crm/objects/{{apiVersion}}/companiesCreates a company and, in the same call, associates it with the contact in contactId through the associations array (associationTypeId 280 is company to…
  • PATCHUpdate a company/crm/objects/{{apiVersion}}/companies/{{companyId}}Partially updates the company in companyId, for example to set an owner or the number of employees. Only the properties you send change.
  • POSTCreate a deal/crm/objects/{{apiVersion}}/dealsCreates a deal. Send dealname, dealstage and, if the account has more than one deal pipeline, pipeline; both must be internal IDs, taken here from pipelineId…
  • PATCHMove a deal to another stage/crm/objects/{{apiVersion}}/deals/{{dealId}}Updates the deal in dealId. Changing dealstage moves it through the pipeline: set nextDealStage to another stage id from 'List deal pipelines and stages'…
  • GETGet a deal with associations/crm/objects/{{apiVersion}}/deals/{{dealId}}Reads the deal in dealId with chosen properties and the IDs of its associated contacts and companies, which confirms the inline associations from the create…

4. Associations

  • PUTAssociate records (default, no label)/crm/objects/{{apiVersion}}/contacts/{{contactId}}/associations/default/companies/{{companyId}}Creates the default, unlabeled association between two existing records: here contact contactId to company companyId. No body is needed. It is safe to repeat;…
  • PUTAssociate records with a label/crm/objects/{{apiVersion}}/contacts/{{contactId}}/associations/companies/{{companyId}}Creates or updates a labeled association between the contact and company. The body is an array of associationCategory (HUBSPOT_DEFINED or USER_DEFINED) and…
  • GETList a contact's company associations/crm/objects/{{apiVersion}}/contacts/{{contactId}}/associations/companiesLists the companies associated with the contact in contactId, with every association type (label) on each link. A link carrying type 279 (unlabeled) and type…
  • GETList association labels (contact to deal)/crm/associations/{{apiVersion}}/contacts/deals/labelsReturns the association types available between two objects, both HubSpot-defined and your custom labels, with typeId, category and label. Use the returned…
  • DELETERemove all associations between two records/crm/objects/{{apiVersion}}/contacts/{{contactId}}/associations/companies/{{companyId}}Deletes every association (labeled and unlabeled) between the contact and the company. Returns 204. To drop just one label, use the batch label-delete…

5. Search

  • POSTSearch contacts/crm/objects/{{apiVersion}}/contacts/searchFinds contacts with filterGroups: filters inside one group are combined with AND, separate groups with OR (at most 5 groups, 6 filters per group, 18 in…
  • POSTSearch deals above an amount/crm/objects/{{apiVersion}}/deals/searchFinds deals in pipeline pipelineId worth more than a threshold, newest first. Shows GT on a number property and EQ on the pipeline; add a NEQ filter on…
  • POSTSearch companies by text/crm/objects/{{apiVersion}}/companies/searchFull-text search with query: matches the company's default searchable text properties (name, domain and similar). Combine with filterGroups to narrow further.…

6. Clean up

  • DELETEArchive the deal/crm/objects/{{apiVersion}}/deals/{{dealId}}Moves the deal in dealId to the recycling bin. Returns 204. Archiving does not delete the associated contact or company.
  • DELETEArchive the company/crm/objects/{{apiVersion}}/companies/{{companyId}}Moves the company in companyId to the recycling bin. Returns 204. Its associations are removed with it.
  • DELETEArchive the contact/crm/objects/{{apiVersion}}/contacts/{{contactId}}Moves the contact in contactId to the recycling bin; it can be restored for 90 days. Returns 204. To permanently erase personal data use the GDPR delete…

API details

Base URL
https://api.hubapi.com
Authentication
A bearer token in the Authorization header
Operations
25 operations on 25 pathsGET 10POST 6DELETE 4PATCH 3PUT 2
Main resources
1. Start here 42. Contacts 53. Companies and deals 54. Associations 55. Search 36. Clean up 3
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-18

How to test the HubSpot CRM API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the HubSpot CRM API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “List owners” (GET /crm/owners/{{apiVersion}}), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the HubSpot CRM API?

Contacts, companies and deals CRUD, search, associations, properties and owners on HubSpot's date-versioned 2026-09 CRM API. It is listed under Productivity & workspace and has 25 endpoints.

Who publishes the HubSpot CRM API?

It is listed from HubSpot's public API description (an OpenAPI document), not published by HubSpot on Swastik Codes. Anyone who controls hubapi.com can claim the profile by adding a DNS TXT record.

What is the base URL of the HubSpot CRM API?

Requests go to https://api.hubapi.com. Endpoint paths are added to this base URL.

How do I authenticate with the HubSpot CRM API?

With A bearer token in the Authorization header.

How many endpoints does the HubSpot CRM API have?

25 operations on 25 paths (10 GET, 6 POST, 4 DELETE, 3 PATCH, 2 PUT). The largest groups are 1. Start here, 2. Contacts, 3. Companies and deals, 4. Associations.

Is forking the HubSpot CRM API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.