HubSpot

Create, update, and look up HubSpot CRM contacts

Overview

The HubSpot tools integrate with the HubSpot CRM API to manage contacts from your workflows. Both tools key on the email address, so you can reconcile records without going through the Search API and its rate limit.

Key Features

• HUBSPOT_UPSERT_CONTACT
  • Create a contact, or update the existing one with the same email address. Supports custom properties.
• HUBSPOT_GET_CONTACT
  • Fetch a contact by object ID or by email address. Returns found: false instead of failing when no contact matches.

Authentication

For setup instructions, see the HubSpot credentials page.

Config field	Description
access_token	A HubSpot access token (select from workspace secrets). Needs the crm.objects.contacts.read and crm.objects.contacts.write scopes.

Example: Look Up a Contact, Then Create or Update It

- id: find_contact
  tool: HUBSPOT_GET_CONTACT
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: email
      value: "[e-mail]"
    - name: properties
      value: "email, firstname, lastname, company"
- id: upsert_contact
  tool: HUBSPOT_UPSERT_CONTACT
  config:
    - name: access_token
      value: "{{secrets.HUBSPOT_ACCESS_TOKEN}}"
  input:
    - name: email
      value: "[e-mail]"
    - name: firstname
      value: "Ada"
    - name: lastname
      value: "Lovelace"
    - name: lifecyclestage
      value: "lead"
    - name: properties
      value: '{"hs_lead_status":"OPEN"}'

Inputs

HUBSPOT_UPSERT_CONTACT

Input	Required	Description
email	Yes	The lookup key. An existing contact with this email is updated, otherwise a new one is created.
firstname, lastname, phone, company, jobtitle, website	No	Standard contact properties.
lifecyclestage	No	e.g. subscriber, lead, marketingqualifiedlead, customer.
properties	No	Any other HubSpot properties as a JSON object of internal name → value, e.g. {"hs_lead_status":"OPEN"}. A null value clears the property.

A named input left blank is skipped, not sent — HubSpot reads an empty string as “clear this property”, so clearing has to be asked for explicitly through properties ({"firstname": null}). Named inputs win over the same key inside properties. Setting properties.email to something other than the email input is rejected. A difference in letter case alone is treated as the same address.

Returns result.id, result.created, result.properties, and the raw result.contact.

HUBSPOT_GET_CONTACT

Input	Required	Description
contact_id	One of the two	HubSpot contact object ID.
email	One of the two	Contact email address.
properties	No	Comma-separated property names, e.g. email, firstname, company. HubSpot returns only a minimal set when this is empty. Custom properties use their internal name, which you can find under Settings → Properties.
associations	No	Comma-separated object types to also fetch associated record IDs for, e.g. companies, deals.

Returns result.found, result.id, result.properties, result.associations, and the raw result.contact.

Notes

• Not found is not an error: HUBSPOT_GET_CONTACT returns result.found = false on a missing contact, so “look up, and create it if missing” can be an ordinary condition step.
• Concurrent writes are last-write-wins: HubSpot’s CRM API has no optimistic locking, so overlapping updates resolve per property. Do not use HUBSPOT_UPSERT_CONTACT for read-modify-write accumulation (reading a score, adding to it, writing it back) across runs that may overlap — use a HubSpot calculated property instead.
• Archived contacts: a contact in HubSpot’s recycle bin still reserves its email address, so an upsert against it cannot succeed. Restore it from the recycle bin, or use a different address.
• Timeouts: every request has a 30-second timeout, with automatic retries on rate limits and transient server errors.