Skip to main content

HubSpot — Application Overview

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 Wrkflows 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​

  1. Create a new HubSpot Connected Account in Wrk.
  2. You will be redirected to HubSpot’s OAuth screen.
  3. Log in and approve the requested scopes.
  4. 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 Wrkflows 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)

Additional Resources​

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

OAuth Documentation: https://developers.hubspot.com/docs/api/oauth-quickstart-guide

Search API Documentation: https://developers.hubspot.com/docs/api/crm/search

Rate Limits & Usage Details: https://developers.hubspot.com/docs/api/usage-details