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

Create or update an object in Hubspot.

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

choose_hubspot_object (static dropdown, required)
  Choose Hubspot Object. Values:
    - { value: "contacts", label: "Contact" } (default)
    - { value: "companies", label: "Company" }
    - { value: "deals", label: "Deal" }
    - { value: "leads", label: "Lead" }
    - { value: "calls", label: "Call" }
    - { value: "meetings", label: "Meeting" }
  Calls and Meetings require the `hs_timestamp` property. Both are
  invisible on a record's timeline until associated — set
  associate_to / associate_to_record_id below.

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.

associate_to (static dropdown, optional)
  Associate To. Optionally associate the record with an existing
  HubSpot record. Uses HubSpot's default (unlabelled) association, so
  no association type id is needed.
  Values:
    - { value: "contacts", label: "Contact" }
    - { value: "companies", label: "Company" }
    - { value: "deals", label: "Deal" }
    - { value: "tickets", label: "Ticket" }

associate_to_record_id (string, optional)
  Associate To Record ID. The unique identifier of the record to
  associate with, e.g. 44542243321. Both associate_to and
  associate_to_record_id must be set for an association to be made;
  either one alone is ignored.

2. OUTPUTS

id (string) — ID. Placeholder: "431231243".
properties (json) — Properties.
created_at (date) — Created At.
updated_at (date) — Updated At.
archived (boolean) — Archived.
action_type (string) — Action Type. "created" or "updated".
association_error (string) — Association Error. Empty on success. The
  record is still written when an association fails, so treat a
  non-empty value as a partial success, not a failed write.

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` or `companies`.
  - 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.
- **Associating a contact with a company.** HubSpot exposes the
  primary contact↔company association as a native contact
  property: `associatedcompanyid` (label: "Primary Associated
  Company ID"). It shows up under `hubspot_object_properties` like
  any other writable field — set it with the target Company's
  HubSpot record ID as the value and the contact is associated
  with that company on the upsert (whether the contact is being
  created or updated). No separate associations API call is
  needed for the primary contact↔company link. Example:
    {
      "name": "associatedcompanyid",
      "value": "{{hubspot_lookup_object_1.id}}"
    }
  Scope: only the PRIMARY contact↔company association. For
  non-primary or non-contact↔company links (e.g. contact↔deal,
  secondary companies, custom association labels) this property
  doesn't apply — those still need HubSpot's associations API,
  which is not currently exposed as a Floqer action. Same shortcut
  works under `hubspot_create_object`.

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
  -> action-detail/hubspot_create_object.txt

Need to look up records
  -> action-detail/hubspot_lookup_object.txt

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

Last updated: 2026-05-26.