The hubspot_lookup formula lets you pull one or more field values from a specific HubSpot record, like a deal, contact, or company.
It works just like VLOOKUP, but for your HubSpot data — straight into your spreadsheet.
Field List Syntax (fields_list)
Demo
Syntax
=hubspot_lookup(object_type, lookup_field, lookup_value, fields_list)
Arguments
|
Argument |
Required |
Description |
| object_type | YES | The HubSpot object type: "deals", "contacts", or "companies". |
| lookup_field | YES | The field you want to match by, e.g., "Email" or "Deal Name". |
| lookup_value | YES |
The value to match against, e.g., "alice@example.com" or "Big Deal Inc". For multiple lookups, provide the entire range as an input, i.e., A3:A100, where these cells contain the Email or Deal Name values, respectively. |
| fields | YES | A comma-separated list of fields to return, or a cell range like A1:A3. |
Field List Syntax (fields_list)
The fields parameter defines which fields to return for each matching record.
You can:
- List fields directly: "Deal Name, Amount, Close Date".
- Reference a cell range: B1:H1.
- You can also include association fields: "Owner Email (Associated Owner)", "First Name (Associated Contact)".
Examples
Here are some examples of how you can use the hubspot_lookup formula in your spreadsheet:
Fetch Deal Amount and Close Date by Deal Name.
=hubspot_lookup("deals", "Deal Name", "Website Redesign", "Amount, Close Date")
Lookup a contact by email and get the first and last name.
=hubspot_lookup("contacts", "Email", A3:A25, "First Name, Last Name")
ℹ️ Note: If you intend to run a lookup across multiple records, it would be easier for you to reference them in a single formula like A3:A25 in this example, which points to individual emails to be looked up.
Pull the company name and industry from the website domain.
=hubspot_lookup("companies", "Domain", "acme.com", "Name, Industry")
Use a header range for flexible field selection.
=hubspot_lookup("deals", "Deal Name", A2, B1:E1)
Best Practices & Tips:
Instead of dragging down a single lookup across multiple rows, consider merging it all into a single formula. That will help you save on API limits with HubSpot:
=hubspot_lookup("contacts", "Email", A3:A25, "First Name, Last Name")
Common Errors
| Error Message | Cause |
| Internal error executing the custom function | This error occurs in Google Sheets when a formula takes longer than 30 seconds to execute. Consider executing the formula again. |
| HubSpot connection requires reauth | Open the sidebar and reauthorize HubSpot for the formula to continue to work. |
| Invalid object type | Only "deals", "contacts", and "companies" are supported. |
| Invalid field name | One or more fields do not match HubSpot field names. |
| Filter syntax error | The filter_string is misformatted. |