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 (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" }

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`, `companies`,
                                `deals`, or `leads`.
  - 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.

================================================================================
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-04-28.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt