ACTION_ID: hubspot_lookup_object
NAME: Hubspot: Lookup Record
CATEGORY: CRM
CREDITS: 0

Lookup record(s) in Hubspot, e.g. Contacts, Companies, Calls,
Meetings or Users.

PREREQUISITE: HubSpot account connection — the user must create it in the Floqer UI
(Connections page); an agent cannot. Without it the action fails the row with
a connection / authentication error. Confirm it exists before configuring.

1. INPUTS

hubspot_object (static dropdown, required)
  Hubspot Object. Default: Contacts. Values:
    - { value: "contacts", label: "Contact" } (default)
    - { value: "companies", label: "Company" }
    - { value: "calls", label: "Call" }
    - { value: "meetings", label: "Meeting" }
    - { value: "users", label: "User" }

operator (dropdown, optional)
  Operator. Default: OR. Values:
    - { value: "or", label: "OR" } (default)
    - { value: "and", label: "AND" }

limit (number, optional)
  Limit. Default: 10.

add_properties_and_their_values (dynamicJsonArray, optional)
  Add Properties and their Values. Select Properties from the object
  and add filter Values. Values from hubspot_properties.

output_columns (multiDropdown, optional)
  Output Columns. Select which HubSpot properties come back as
  columns on each record. Values from hubspot_properties, resolved
  live for the chosen object. Leave empty to return every property on
  the object.

2. OUTPUTS

records (sectionList) — Records found in the lookup. Columns are not
fixed: they are the HubSpot properties selected in `output_columns`,
each returned under its own HubSpot property name. Resolve the
available properties for the chosen object via Get Action Field
Options (see HOW TO CONFIGURE).

custom_fields (json) — Every property returned that was not named in
`output_columns`. Present on each record.

total_records (number) — Total Records. The total number of records
found.

3. HOW TO CONFIGURE

Resolve the property list for the chosen object via Get Action
Field Options:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/add_properties_and_their_values
       (body: { "context": { "hubspot_object": "contacts" } })
  POST .../options/output_columns
       (body: { "context": { "hubspot_object": "contacts" } })

Both resolvers return the same live property list for the chosen
object, so the same names are valid in filters and in output columns.

Configure Action body:

{
  "inputs": {
    "hubspot_object": "contacts",
    "operator": "or",
    "limit": 10,
    "add_properties_and_their_values": [
      { "name": "email",  "value": "{{input.email}}" },
      { "name": "domain", "value": "{{input.domain}}" }
    ],
    "output_columns": ["firstname", "lastname", "email", "hs_object_id"]
  }
}

Field-by-field:
  - hubspot_object                  Object type — `contacts`,
                                    `companies`, `calls`, `meetings`
                                    or `users`.
  - operator                        `or` (any criterion matches; default)
                                    or `and` (all criteria match).
  - limit                           Max records returned. Default 10.
  - add_properties_and_their_values `[{name, value}]` filter criteria.
                                    Property names are HubSpot internal
                                    names — fetch via Get Action Field
                                    Options.
  - output_columns                  `[name]` properties to return as
                                    columns. Empty returns every
                                    property on the object.

4. KEY NOTES

- Looking up `users` requires the `crm.objects.users.read` scope,
  which is Super-Admin gated in HubSpot. To find Deals or Leads by
  external value, use `http_api_call` to call HubSpot's Search API
  directly.
- The `records` output is a `structured_array`. The 3-segment shape
  `{{<this_action_instance_id>.records.<column>}}` is valid in
  column-mapping contexts only — `push_data_to_sheet`'s
  `choose_columns_to_send_to`, `run_if` over a list, and similar
  fan-out fields. It does NOT work inside a
  `formula` formula; those refs substitute
  as empty strings at JS-evaluation time. To consume `records` in
  JS, use the responseId pattern:
  https://floqer.com/docs/use-case-detail/extract_data_from_crm.txt
  §5.4.
- Output columns are chosen per node, not fixed by the action. Pick
  them in `output_columns`; only those properties are requested from
  HubSpot, which keeps the response small. Anything returned that you
  did not name lands in `custom_fields`.
- The HubSpot connection must live on the API key's user account.

5. WHERE IT FITS IN A WORKFLOW

Pattern: hubspot_lookup_object -> workflow_if_else (records found) ->
hubspot_update_object or downstream branching.

6. WHEN TO USE

Use hubspot_lookup_object to read existing HubSpot Contacts,
Companies, Calls, Meetings or Users by filter properties.

7. WHEN NOT TO USE

Need create-or-update by unique property
  -> action-detail/hubspot_upsert_object.txt

Need to always create
  -> action-detail/hubspot_create_object.txt

Need to update by HubSpot ID
  -> action-detail/hubspot_update_object.txt

Last updated: 2026-05-25.