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

Create 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 (static dropdown, required)
  Choose HubSpot Object. Choose hubspot Object you want to create.
  Values:
    - { value: "contacts", label: "Contact" } (default)
    - { value: "companies", label: "Company" }
  (Deals and Leads are not exposed via the API at the moment.)

hubspot_object_properties (dynamicJsonArray, optional)
  HubSpot Object Properties. Select the properties to create in the
  object. Values from hubspot_properties.

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

id (string) — ID. Placeholder: "431231243".
properties (json) — Properties.
created_at (date) — Created At.
update_at (date) — Update At.
archived (boolean) — Archived.

================================================================================
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
  -> hubspot_upsert_object
     (https://floqer.com/docs/action-detail/hubspot_upsert_object.txt)

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

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

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

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