HubSpot¶

Audience: Everyone · Tags: hubspot, crm, connector, oauth

Create a contact in HubSpot from a flow. connectorKey is hubspot, action type create_contact, authType is oauth, category crm.

Early access. This connector's code makes real calls to the HubSpot CRM API — there's no separate sandbox or mock HubSpot behind it. It's been validated end-to-end in SnapLink's automated tests using fake/injected HTTP responses (so tests don't need a live HubSpot account), and the install → configure → certify → activate lifecycle, the action's request shape, and error handling all work as documented below. It just hasn't been exercised against a real HubSpot account yet — that additionally requires your administrator to register a real HubSpot OAuth app with SnapLink. Until that's done, the connector installs and activates normally, but a live call returns error code auth.

Fields¶

Field	Required	Type	Notes
`properties`	Yes	object	HubSpot contact properties, keyed by HubSpot's internal property names, e.g. `{"email": "ada@example.com"}`.

Output: id — the created contact's HubSpot id.

The properties you write are sent exactly as written each time — SnapLink doesn't insert data from the incoming webhook into them.

Install and activate (marketplace walkthrough)¶

# 1. Install into your workspace
curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/installed" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_abc123","connectorKey":"hubspot"}'
# → 201 { "data": { "state": "installed", ... } }

# 2. Configure
curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/installed/transition" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_abc123","connectorKey":"hubspot","action":"configure"}'

# 3. Certify (runs a health check; must pass to advance)
curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/installed/transition" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_abc123","connectorKey":"hubspot","action":"certify"}'

# 4. Activate
curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/marketplace/installed/transition" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_abc123","connectorKey":"hubspot","action":"activate"}'

To actually create contacts, your admin also connects a real HubSpot access token — via SnapLink's HubSpot OAuth flow once a HubSpot app is registered, or via the lower-level /connections API with credentialType: "oauth_access" for direct wiring.

Worked example¶

Flow: webhook trigger → HubSpot: Create Contact

{
  "trigger": { "key": "t", "connectorKey": "webhook", "triggerType": "webhook" },
  "actions": [
    {
      "key": "a1",
      "connectorKey": "hubspot",
      "actionType": "create_contact",
      "input": { "properties": { "email": "ada@example.com" } }
    }
  ]
}

1. Create the flow and draft:

curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flows/flow_abc123/drafts" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"definition": { "trigger": {"key":"t","connectorKey":"webhook","triggerType":"webhook"}, "actions": [{"key":"a1","connectorKey":"hubspot","actionType":"create_contact","input":{"properties":{"email":"ada@example.com"}}}] }}'

2. Promote it to activate (the flow won't validate until HubSpot is active in the workspace, per the lifecycle above):

curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/drafts/draft_xyz/promote" \
  -H "Authorization: Bearer $TOKEN"

3. Trigger it (see webhook.md):

curl -X POST "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/webhooks/flow_abc123/<secret>" \
  -H "Content-Type: application/json" -d '{}'

{ "ok": true, "data": { "runId": "run_01HF...", "status": "queued" } }

4. Check the run in Execution History. If a real HubSpot access token is connected, the contact is created; otherwise the step fails with auth.

Limitations¶

Contacts only today — companies, deals, and tickets are Planned.
HubSpot rate limits apply; SnapLink maps throttling to rate_limit.
properties uses HubSpot's internal property names (e.g. firstname, not "First Name") — check your HubSpot account's property settings if a value isn't landing where you expect.

If something goes wrong¶

Symptom	Cause	Fix
Run fails `auth`	No real HubSpot app registered yet, or the token was revoked	Ask your admin to complete HubSpot OAuth setup, or reconnect (Authentication errors)
`bad_request`	Invalid property name or value	Check HubSpot's internal property names
`rate_limit`	Too many requests too fast	Add backoff — see Rate limiting

See Connector failed for the general failure-diagnosis path.