Hubspot CRM Port

Purpose

This is the Harbor reference integration for the HubSpot CRM API.

Use it when:

• building HubSpot actions in Harbor
• extending the Dock / Hub HubSpot entry
• teaching Codex or OpenClaw how to map a CRM API into Harbor Ports and Harbor Actions without turning Harbor into a generic CRM object proxy

Harbor Port worksheet

Product

• Product: HubSpot CRM API
• Publisher slug: hubspot
• Publisher name: HubSpot
• Category: CRM
• Tags: hubspot, crm, contacts, sales, customer-ops

Safe Harbor Port metadata

• Kind: http_api
• Label: HubSpot CRM API
• Description: HubSpot CRM API connection managed locally through Harbor.
• Base URL: https://api.hubapi.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

HubSpot fits Harbor well because:

• every starter action stays on one fixed origin
• contact routes are explicit and reviewable
• search and create operations map cleanly to bounded JSON request bodies
• single-contact lookup uses a stable path plus typed query values
• Harbor never needs to expose raw auth or arbitrary object forwarding

Good Harbor HubSpot starter actions:

• explicit POST search for contacts
• fixed GET read for a single contact
• explicit POST create for contacts
• requestBodyMode: "json" for search and create
• requestBodyMode: "none" for single-record lookup
• resultMode: "json_summary" for all starter actions

Avoid for now:

• broad multi-object coverage across the whole HubSpot CRM
• giant property-management or association surfaces
• generic forwarding across every HubSpot object endpoint
• large write coverage before operator review

Starter HubSpot actions

Automatic read actions

• search-contacts -> POST /crm/v3/objects/contacts/search
• get-contact -> GET /crm/v3/objects/contacts/{contactId}

Approval-friendly write actions

• create-contact -> POST /crm/v3/objects/contacts

Why these actions

These routes fit Harbor's current safe model well because they:

• cover the common operator loop of finding a contact, inspecting that contact, and creating a new contact
• keep the route surface small and explicit
• use Harbor's Action Model for typed path and query values where needed
• map cleanly to HubSpot's bearer-token auth model
• give Harbor an immediately useful CRM integration without taking on the whole HubSpot object surface yet

Action Model notes

At execution time, callers should supply values by location:

• input.body for search-contacts
• input.path and optionally input.query for get-contact
• input.body for create-contact

Example contact search request:

{
  "body": {
    "query": "alice",
    "limit": 10,
    "properties": [
      "firstname",
      "lastname",
      "email",
      "phone"
    ]
  }
}

Example contact lookup request:

{
  "path": {
    "contactId": "alice@example.com"
  },
  "query": {
    "idProperty": "email",
    "properties": "firstname,lastname,email,phone"
  }
}

Example contact creation request:

{
  "body": {
    "properties": {
      "email": "alice@example.com",
      "firstname": "Alice",
      "lastname": "Example",
      "phone": "555-0100"
    }
  }
}

For create-contact, keep the JSON body bounded to the fields you actually intend to use, such as:

• properties.email
• properties.firstname
• properties.lastname
• properties.phone
• properties.company
• associations

Suggested operator workflow

1. Import the HubSpot Dock entry from Dock / Hub.
2. Configure the local HubSpot bearer token in Harbor Node.
3. Use search-contacts to locate the right record first.
4. Use get-contact to confirm the contact details you care about.
5. Keep create-contact on require_approval unless there is a clear local policy reason not to.

Suggested agent workflow

1. Inspect the existing HubSpot Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed HubSpot routes only when they remain bounded and reviewable.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored HubSpot token
• widen HubSpot into a generic object proxy
• hide contact route names behind vague labels
• add broad mutation coverage without review

Current update strategy

For now, HubSpot updates are manual:

• update the Dock / Hub HubSpot integration document in apps/hub/catalog/integrations/hubspot/hubspot-crm-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Scope notes

This starter set intentionally stays focused on contacts.

That means:

• contact search uses a bounded JSON body
• single-contact lookup stays on one fixed path template
• contact creation is the only seeded write action
• companies, deals, tickets, and deeper association flows should be added later only when they remain fixed and reviewable

Official reference starting points

• HubSpot contacts guide: https://developers.hubspot.com/docs/api-reference/crm-contacts-v3/guide
• Search for contacts: https://developers.hubspot.com/docs/api-reference/crm-contacts-v3/search/post-crm-v3-objects-contacts-search
• Retrieve a contact: https://developers.hubspot.com/docs/api-reference/crm-contacts-v3/basic/get-crm-v3-objects-contacts-contactId
• Create a contact: https://developers.hubspot.com/docs/api-reference/crm-contacts-v3/basic/post-crm-v3-objects-contacts