ACTION_ID: hubspot_create_object
NAME: HubSpot: Create Object
CATEGORY: CRM
CREDITS: 0

Create 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. Choose hubspot Object you want to create.
  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_object_properties (dynamicJsonArray, optional)
  HubSpot Object Properties. Select the properties to create in the
  object. 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.
update_at (date) — Update At.
archived (boolean) — Archived.
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 the property list via Get Action Field Options before
configuring:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/hubspot_object_properties
       (body: { "context": { "hubspot_object": "contacts" } })
       → all HubSpot properties on the chosen object type.

Configure Action body:

{
  "inputs": {
    "choose_hubspot_object": "contacts",
    "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_object_properties   `[{name, value}]` — `name` is HubSpot's
                                internal property name (use the
                                `hubspot_object_properties` options call
                                to list valid names for the chosen
                                object); `value` accepts `{{ref}}` tokens
                                or literals.

4. KEY NOTES

- Always inserts. Use `hubspot_upsert_object` for create-or-update by a
  unique property (e.g. email).
- Property names are HubSpot's internal names (e.g. `firstname` not
  `first_name`, `email` lowercase) — fetch them via Get Action Field
  Options, don't guess.
- The HubSpot connection must live on the API key's user account.
  If the connection lives under a different team member, Get Action
  Field Options returns a 424 — provision the API key from the user
  who owns the connection.
- **Associating a contact with a company on create.** HubSpot exposes
  the primary contact↔company association as a native contact
  property: `associatedcompanyid` (label: "Primary Associated
  Company ID"). It appears in the `hubspot_object_properties`
  options list for `contacts` like any other writable property —
  set it under `hubspot_object_properties` with the target
  Company's HubSpot record ID as the value and the new contact is
  associated with that company on create. No separate associations
  API call is needed for the primary contact↔company link. Example:
    {
      "name": "associatedcompanyid",
      "value": "{{hubspot_lookup_object_1.id}}"
    }
  Scope of this shortcut: only the PRIMARY contact↔company
  association (HubSpot allows one primary company per contact, plus
  additional secondary associations). 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. The same shortcut
  works under `hubspot_upsert_object`.

5. WHERE IT FITS IN A WORKFLOW

Pattern: enrichment -> hubspot_create_object (contacts/companies) ->
downstream HubSpot automation.

6. WHEN TO USE

Use hubspot_create_object to create new HubSpot records.

7. WHEN NOT TO USE

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

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

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

Last updated: 2026-05-26.