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>:
- 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
- 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
- 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
- Start here: list owners (saves
ownerId), read contact properties, list deal pipelines (savespipelineIdanddealStage). - Contacts: create (saves
contactId), read by ID or by email, update, list. - Companies and Deals: create (saves
companyId,dealId), each created with an inline association. - Associations: link the contact to the company, label it as primary, list associations.
- 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 / category | Meaning | Fix |
|---|---|---|
401 INVALID_AUTHENTICATION | Missing or bad token | Check accessToken and the Bearer header. |
403 MISSING_SCOPES | Token lacks a scope | Add the scope to the key or app. |
404 OBJECT_NOT_FOUND | Wrong record ID or archived record | Check the ID variable. |
409 CONFLICT | A contact with that email already exists | Update the existing record (the error message includes its ID). |
400 VALIDATION_ERROR | Unknown property or bad enumeration value | Use internal property names and option values. |
| 429 | Rate limit | Back 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 - Links
- Documentation
How to test the HubSpot CRM API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the HubSpot CRM API collection, without the publisher's secrets.
- 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.
- 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.