HubSpot integration

HubSpot is a customer relationship management (CRM) platform that helps businesses manage sales, marketing, and customer service.

With this integration, you can import, create, update, and manage HubSpot objects directly in Clay.

Creating a table with HubSpot

1. In a workbook, click + Add at the bottom.
2. Search for HubSpot and select it from the results.
3. In the modal, you will be asked to select your HubSpot account.
   • If you haven't connected your HubSpot account yet, click + Add account and complete authentication.

Source Import objects from HubSpot

Use this source to import objects from HubSpot into Clay.

Inputs

Required:

• Object Type: The HubSpot object type you want to import. The list is pulled from your own portal, so it includes your custom objects as well as the standard ones.

Optional:

• List to pull objects from: Select a list to pull objects from. If you don't select a list, all objects will be pulled.
• Include Read Only Properties?: Include all HubSpot calculated fields for each record (e.g., hs_analytics_first_timestamp). If not selected, only editable properties will be included (e.g., domain).
• Exclude empty properties?: Exclude all empty properties from the response. If not selected, all properties will be included, even those with empty values.

Enriching data with HubSpot

1. While in a Clay table, click Add enrichment and search for HubSpot.
2. Under Integrations, select one of the HubSpot options.
3. In the modal, select your HubSpot account.
   • If you haven't connected your HubSpot account yet, click + Add account and complete authentication.

The object actions all start with Object Type, and the fields underneath it change to match the type you pick. Those fields come from your own portal, so what you see reflects the properties and custom objects you've actually set up in HubSpot.

Action Create object

Use this action to create an object in HubSpot.

Inputs

Required:

• Object Type: The type of HubSpot object to create.

Optional:

• Association Fields: Appears only when the object type is Lead, and lets you associate the new lead as you create it. It contains Association Object Type (either Company or Contact), Association Type, and To Object ID.
• Keep subdomains in Company domain: Off by default. When on, the domain you write to a Company keeps its subdomain, so shop.example.com stays as it is. When off, it's reduced to the root domain, example.com.

Once you've picked an object type, the writable properties for that type appear below, ready to map to your Clay columns. For the Deal object type, this includes your pipelines and their stages.

Action Look up object

Use this action to look up an object in HubSpot.

Inputs

Required:

• Object Type: The type of HubSpot object to look up.
• Fields to filter by: The properties you want to search on. You can pick more than one, and each one you pick gets its own value field below. HubSpot Object ID sits at the top of the list, since matching on the record ID is the most precise option available.

Optional:

• Search Operator: Appears once you're filtering on two or more fields. AND requires every field to match, OR requires at least one. AND is the default.
• Match subdomains in Domain filter: Off by default. When on, the Domain filter keeps subdomains, so purchasing.utah.edu stays as it is. When off, the filter is reduced to the root domain, utah.edu.
• Remove blank values from results: On by default. Drops blank values from the objects found, which helps reduce the size of the result.
• Limit: Maximum number of objects to return. Defaults to 10, and the maximum is 200.

Action Update object

Use this action to update an object in HubSpot.

Inputs

Required:

• Object Type: The type of HubSpot object to update.
• HubSpot Object ID: The unique identifier of the object you want to update.

Optional:

• Ignore blank values: On by default, so blank values coming from Clay are left alone in HubSpot. Turn it off if you want blank values sent through and existing HubSpot values overwritten with them.
• Keep subdomains in Company domain: Off by default. When on, the domain you write to a Company keeps its subdomain, so shop.example.com stays as it is. When off, it's reduced to the root domain, example.com.

As with Create object, the writable properties for the type you pick appear below, ready to map to your Clay columns.

Action Create association

Use this action to create an association between two objects in HubSpot.

Inputs

Required:

• From Object Type: The type of the object to associate.
• To Object Type: The type of the object to associate it to.
• Association Type: The type of association to create between the two objects. The options depend on the two types you picked, so choose those first.
• From Object ID: The unique identifier of the object you want to associate.
• To Object ID: The unique identifier of the object you want to associate it to.

Action Get associated objects

Use this action to retrieve associations between two objects in HubSpot.

Inputs

Required:

• From Object Type: The type of the object you want to look up associations on.
• To Object Type: The type of object you want to look up associations for.
• From Object ID: The unique identifier of the object you want to look up associations on.

Optional:

• Remove blank values from results: On by default. Drops blank values from the associations found.
• Include read only properties: Include HubSpot's calculated fields for each association (e.g., hs_analytics_first_timestamp). If not selected, only editable properties will be included.
• Limit: Maximum number of associations to return. Defaults to 20, which is also the maximum.

Action Find owner

Use this action to find a HubSpot owner by ID or email address.

Inputs

• Owner ID: (Required if Email is not provided) The HubSpot owner ID to search for.
• Email: (Required if Owner ID is not provided) The email address of the owner to search for.

If you provide both, the email is validated against the owner found by ID. Where you have the ID available, it's the more reliable of the two — an email column coming out of an enrichment often won't belong to a HubSpot owner at all.

Action Add record to list

Use this action to add a HubSpot record to a static list, so your team can work it as a segment.

Inputs

Required:

• Object type: The type of HubSpot record you want to add to a list. Company, Contact, Deal, and Lead are always there, with your portal's custom objects listed after them.
• List: The list to add the record to. Pick an Object type first — the dropdown fills in once you have, and shows the lists built on that type.
• HubSpot record ID: The unique identifier of the record to add, such as the record ID that Create object returns. It has to be HubSpot's numeric ID, so a row carrying an email address or a domain here won't run.

Outputs

• Added to list: true when the record was added to the list, false when it wasn't.

Only lists whose membership you can edit appear in List. HubSpot recalculates the membership of an active list from that list's filters, so those aren't offered — create a static list in HubSpot for the records you're sending over.

A row can succeed with Added to list set to false, which means HubSpot took the request but didn't add the record, because it's already in the list or isn't eligible for it. A record ID that doesn't exist in your portal fails that row instead.

Note: this action needs the Create and edit lists, including adding records to a list permission. HubSpot asks for it by default when you connect. If your connection doesn't have it, List shows an error asking you to reconnect your account and select it.

Action Enroll a contact in a sequence

Use this action to enroll a HubSpot contact in a sequence, which then sends automated follow-ups.

Inputs

Required:

• Contact ID: The unique identifier of the HubSpot contact to enroll.
• Sequence: The sequence to enroll the contact in. Displays as a dropdown populated from your HubSpot account.
• Sender email: The email address of the user who will send the sequence emails.

Optional:

• Sender alias address: An alternate address the sequence emails will appear to come from. Alternate email addresses must be set up in HubSpot first.

Action Get enrollment status of a contact

Use this action to check whether a contact is already enrolled in any sequences.

Inputs

Required:

• Contact ID: The unique identifier of the HubSpot contact to check.

Run settings

• Auto-update
• Only run if: The enrichment will only run when conditions are met. Learn more about conditional formulas.

OAuth scopes

When connecting your HubSpot account, Clay uses optional OAuth scopes to give you fine-grained control over permissions.

Learn more about optional scopes.

Required scopes

These permissions cannot be disabled and are always requested:

• crm.lists.read — View details about contact lists.
• crm.objects.contacts.read — View properties and other details about contacts.
• crm.objects.companies.read — View properties and other details about companies.
• crm.objects.leads.read — View properties and other details about leads.
• crm.objects.owners.read — View details about users assigned to CRM records.
• crm.schemas.companies.read — View details about property settings for companies.
• crm.schemas.contacts.read — View details about property settings for contacts.

Optional scopes (enabled by default)

These permissions are requested by default but can be disabled:

• crm.objects.companies.write — View properties and create, delete, or make changes to companies.
• crm.objects.contacts.write — View properties and create, delete, or make changes to contacts.
• crm.objects.leads.write — Create, delete, or make changes to leads.
• crm.lists.write — Create and edit lists, including adding records to a list.
• crm.objects.deals.read — View properties and other details about deals.
• crm.objects.deals.write — View properties and create, delete, or make changes to deals.
• crm.schemas.deals.read — View details about property settings for deals.
• crm.export — Export CRM data in bulk for Audiences import.

Optional scopes (disabled by default)

These permissions are available but not requested by default:

• crm.schemas.custom.read — View details about custom object definitions in the HubSpot CRM.
• crm.objects.custom.read — View details about custom objects.
• crm.objects.custom.write — Create, delete, or make changes to custom objects.
• automation.sequences.read — View details about sequences.
• automation.sequences.enrollments.write — Enroll contacts in a sequence.

Troubleshooting

Connecting HubSpot fails with "An unexpected error occurred during the app authorization process"

The three custom object permissions — crm.schemas.custom.read, crm.objects.custom.read, and crm.objects.custom.write — are available on HubSpot Enterprise portals. On other HubSpot plans they can't be granted, and authorization stops there rather than continuing without them.

All three arrive switched off for exactly this reason. If you turned them on before connecting, reconnect with them off and the rest of the permissions will go through as normal.

Reconnecting keeps whatever you had enabled last time, so an Enterprise portal that already has the custom object permissions on will hold onto them.