ACTION_ID: hubspot_upsert_object
NAME: Hubspot: Upsert Object
CATEGORY: sheets
CREDITS: 0

Create or update an object in Hubspot.

================================================================================
PREREQUISITE — USER ACTION REQUIRED
================================================================================

This action only works if the user has connected their HubSpot account
in Floqer. The connection cannot be made via the API or by an AI agent.

The user must do this themselves before this action will run:
  1. Sign in to Floqer at https://app.floqer.com
  2. Open the Connections page from the sidebar
  3. Click HubSpot and complete the OAuth flow

If the user has not connected HubSpot, this action will fail with a
connection / authentication error. Before configuring or running this
action, confirm with the user that the HubSpot connection exists.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

choose_hubspot_object (dropdown, required)
  Choose Hubspot Object. Values:
    - { value: "contacts", label: "Contact" } (default)
    - { value: "companies", label: "Company" }
    - { value: "deals", label: "Deal" }
    - { value: "leads", label: "Lead" }

hubspot_unique_property (hubspot_properties_dropdown, required)
  Hubspot Unique Property. Select unique hubspot property to use to
  create or update records. Values from hubspot_properties.

hubspot_object_properties (jsonArray, optional)
  Hubspot Object Properties. Select the properties to add or update.
  Values from hubspot_properties.

================================================================================
2. OUTPUTS
================================================================================

(no response fields — follow with `hubspot_lookup_object` if downstream steps need the new HubSpot ID.)

================================================================================
3. HOW TO CONFIGURE
================================================================================

Resolve property options for both `hubspot_unique_property` and
`hubspot_object_properties` via Get Action Field Options:

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

Both calls return the same property set for the chosen object — pick
one for the upsert key, list the rest under the property mappings.

Configure Action body:

{
  "inputs": {
    "choose_hubspot_object": "contacts",
    "hubspot_unique_property": "email",
    "hubspot_object_properties": [
      { "name": "email",     "value": "{{input.email}}" },
      { "name": "firstname", "value": "{{input.first_name}}" },
      { "name": "lastname",  "value": "{{input.last_name}}" },
      { "name": "company",   "value": "{{input.company_name}}" }
    ]
  }
}

Field-by-field:
  - choose_hubspot_object       Object type — `contacts`, `companies`,
                                `deals`, or `leads`.
  - hubspot_unique_property     The HubSpot property used as the
                                match key for the upsert (e.g. `email`,
                                `domain`, `hs_object_id`). Must also
                                appear under `hubspot_object_properties`
                                with the value to match against.
  - hubspot_object_properties   `[{name, value}]` — properties to write
                                on create OR update. Include the unique
                                property here too.

================================================================================
4. KEY NOTES
================================================================================

- This action emits no output fields. If downstream steps need the
  HubSpot ID, follow with `hubspot_lookup_object` keyed on the same
  unique property.
- The unique property must also be present in
  `hubspot_object_properties` with a value — that's how the action
  knows what to match against.
- Property names are HubSpot's internal names — fetch via Get Action
  Field Options.
- The HubSpot connection must live on the API key's user account.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern: enrichment -> hubspot_upsert_object (key=email or domain) ->
downstream HubSpot automation.

================================================================================
6. WHEN TO USE
================================================================================

Use hubspot_upsert_object for idempotent sync into HubSpot.

================================================================================
7. WHEN NOT TO USE
================================================================================

Need to always create
  -> hubspot_create_object
     (https://floqer.com/docs/action-detail/hubspot_create_object.txt)

Need to look up records
  -> hubspot_lookup_object
     (https://floqer.com/docs/action-detail/hubspot_lookup_object.txt)

Need to update by HubSpot ID
  -> hubspot_update_object
     (https://floqer.com/docs/action-detail/hubspot_update_object.txt)

================================================================================

This file is maintained manually. Last updated: 2026-04-28.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt