HubSpot is a cloud-based CRM platform used by sales, marketing, and customer success teams to manage contacts, companies, deals, and pipeline activity. The HubSpot integration within the Wrk platform allows you to automate CRM workflows by calling the HubSpot CRM REST APIs through prebuilt Wrk Actions.

This document provides an overview of how HubSpot integrates into Wrk, how authentication works, general API behaviour, and a full list of available Wrk Actions.

Authentication

Hubspot supports one authentication methods within Wrk When connecting your HubSpot account in Wrk, you are redirected to HubSpot’s OAuth authorization screen. After signing in and granting access, Wrk receives:

An access token
A refresh token

These tokens are used for all subsequent API calls. If the access token expires, Wrk automatically uses the refresh token to obtain a new one.

If authentication fails (for example, due to revoked access or invalid scopes), HubSpot returns HTTP 401 Unauthorized.

How to Authenticate

Create a new HubSpot Connected Account in Wrk.
You will be redirected to HubSpot’s OAuth screen.
Log in and approve the requested scopes.
Wrk securely stores and manages the access and refresh tokens.

If permissions are changed inside HubSpot or the app is disconnected, the connection must be reauthenticated.

General API Behaviour

The HubSpot integration uses the HubSpot CRM v3 APIs for objects such as contacts, companies, and deals.

CRM Guide: https://developers.hubspot.com/docs/guides/crm/understanding-the-crm

CRM Object Model

HubSpot CRM is built around standard objects:

Contacts
Companies
Deals

Each CRM record typically includes:

id — the unique object identifier
properties — key-value pairs representing object fields
createdAt and updatedAt timestamps
archived — boolean indicating soft deletion state

Custom properties may exist depending on your HubSpot account configuration.

Object IDs must be passed exactly as returned by the API when performing retrieval, update, or archive operations.

Pagination

Most list endpoints (e.g., retrieving multiple contacts or deals) are paginated.

HubSpot uses cursor-based pagination with the after parameter.

When retrieving multiple records:

You may specify limit (maximum results per page)
The response may include a paging object
If additional records exist, a next.after value is returned

To retrieve the next page, pass the returned after value into the next request.

If no paging object is returned, there are no additional pages.

Cursor-based pagination ensures stable traversal even as records are created or updated.

Searching and Filtering

HubSpot provides a dedicated Search API for advanced filtering.

Search requests:

Use structured filter groups
Support multiple filters combined with AND logic
Allow sorting
Support pagination via after

Search queries operate on a single object type at a time (e.g., contacts or deals).

Archiving vs Deleting

HubSpot uses an archive model rather than hard deletion for most CRM objects.

When an object is archived:

It is marked as archived = true
It is excluded from default list and search results
It can be restored via the API

This behaviour is important when designing workflows that rely on object lifecycle states.

Rate Limits

HubSpot enforces API rate limits based on:

App level limits
Account (portal) level limits

If limits are exceeded, HubSpot returns HTTP 429 Too Many Requests.

Rate limit headers are returned in responses and should be monitored when building high-volume automations.

Error Handling

Common HTTP status codes:

400 Bad Request — Invalid input or malformed request
401 Unauthorized — Invalid or expired token
403 Forbidden — Insufficient scope or permissions
404 Not Found — Object ID does not exist
429 Too Many Requests — Rate limit exceeded

Error responses include structured JSON explaining the issue.

Available Wrk Actions

Create a company in HubSpot
Create a contact in HubSpot
Create a deal in HubSpot
Retrieve a company from HubSpot
Retrieve a contact from HubSpot
Retrieve a deal from HubSpot
Retrieve companies from HubSpot
Retrieve contacts from HubSpot
Retrieve deals from HubSpot
Search for companies from HubSpot
Search for contacts from HubSpot
Search for deals using various filters and criteria to retrieve specific records from HubSpot
Update a company in HubSpot
Update a contact in HubSpot
Update a deal in HubSpot
Archive a contact in HubSpot
Archive a deal in HubSpot
Perform an API call in HubSpot
Perform an API call in HubSpot (Admin Scope)
Perform an API call in HubSpot (Content Scope)