Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect HubSpot to Fondoo

Live5 min readUpdated

This connection lets Fondoo and your AI agent work with contacts in your HubSpot CRM. The agent can read your contact list, add new contacts and update existing ones, so your CRM stays in step with what happens in your business.

What Fondoo can do with it

The connector id is hubspot. It uses the HubSpot CRM Contacts API (v3) and has three capabilities:

  • contacts.list (read): reads contacts with GET /crm/v3/objects/contacts. Optional inputs: limit (HubSpot allows up to 100 per page) and after (the paging cursor HubSpot returns).
  • contacts.create (write): creates a contact with POST /crm/v3/objects/contacts. The input data is sent as the request body, for example { "data": { "properties": { "email": "ana@your-domain", "firstname": "Ana" } } }.
  • contacts.update (write): updates one contact with PATCH /crm/v3/objects/contacts/{id}. Input: id (the HubSpot record ID) and data, for example { "id": "12345", "data": { "properties": { "phone": "+1 555 0100" } } }.

There is no delete action. Agents without the owner scope need contacts:read to read and contacts:write to create or update. Writes go through Fondoo's shared executor, so scopes, dry runs (dryRun: true), audit and events apply.

Consent: a contact created or imported through this connector does not mean that person agreed to marketing email. Fondoo keeps consent and suppressions in its own email pipeline; do not treat HubSpot contacts as opted in.

Before you start

  • A HubSpot account. Free accounts can use the API; call limits depend on your subscription (see the limits section).
  • A super admin, or a user with HubSpot's Developer tools access permission, to create the key.
  • Your Fondoo site id, if you want the connection tied to one site.

HubSpot is changing how tokens are made. HubSpot is turning off creation of new legacy private apps: from September 28, 2026 for accounts created on or after that date, and from October 26, 2026 for older accounts. Existing legacy private apps keep working. HubSpot's recommended replacement is a service key. See the HubSpot changelog. Fondoo only needs a token sent as Authorization: Bearer, so either a service key or an existing legacy private app token works.

Step by step: get your credentials

Option A: service key (recommended for new setups)

Steps from HubSpot's service keys guide:

  1. In HubSpot, go to Development → Keys → Service keys. (HubSpot's announcement also describes this as Settings → Integrations → Service Keys. The menu may differ for your account.)
  2. Click Create service key.
  3. Enter a name, for example Fondoo contacts.
  4. Click Add new scope. Search for and tick:
    • crm.objects.contacts.read, so Fondoo can list contacts and run the connection test.
    • crm.objects.contacts.write, so Fondoo can create and update contacts. Leave it out if you only want reads. Click Update.
  5. Click Create and confirm.
  6. Open the key's details page, click Show, then Copy.
  7. This value goes in the apiKey field. It is the only field.

Option B: existing legacy private app

If you already have a legacy private app with the two contact scopes:

  1. Go to Development → Legacy apps and click the app's name.
  2. Open the Auth tab, click Show token, then Copy.
  3. Paste it into apiKey.

To add scopes to an existing app, use its Scopes tab. See legacy private apps.

Connect it in Fondoo

In the dashboard

  1. Go to Connections in the sidebar and click Connect a tool.
  2. In Find a tool, type HubSpot.
  3. On the HubSpot card, click Use a key. When "Enter your key securely" appears, click Open secure key entry.
  4. On the "Connect hubspot" page, paste the token into apiKey and click Save connection securely. The page works once and expires after 15 minutes.
  5. The connection appears under Connected with a masked key. Click Check connection.

By asking your agent

Example prompt: "Connect our HubSpot CRM. Send me a secure link for the token."

The agent calls:

add_connection_key({ provider: "hubspot", siteId: "YOUR-SITE-ID" })

It returns a one-use securePasteUrl (15 minutes). Passing the token in fields also works but Fondoo warns it may remain in chat logs. connect_service({ provider: "hubspot", siteId }) returns the same setup steps and never accepts a token.

REST equivalent:

curl -X POST https://api.getfondoo.com/v1/ops/add_connection_key \
  -H "Authorization: Bearer $FONDOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"hubspot","siteId":"YOUR-SITE-ID"}'

Test that it works

  1. Click Check connection, or ask the agent to run test_connection({ connectionId }). Fondoo reads one contact (GET /crm/v3/objects/contacts?limit=1). A pass shows connected and "Cheap read succeeded; untested permissions remain unknown, not granted." All three capabilities show as unknown. A passing test proves read access only, not write.
  2. Ask the agent: "List 5 HubSpot contacts." It runs connector_action({ connectionId, action: "contacts.list", input: { limit: 5 } }).
  3. To check write access, ask the agent to preview a create with dryRun: true, then run it for a test contact and delete that contact in HubSpot afterwards.

Troubleshooting

  • "Connection test failed; check credentials and provider permissions." The token is wrong, rotated or missing crm.objects.contacts.read. Copy it again or add the scope, then rotate in Fondoo.
  • Reads work but create or update is refused. The key lacks crm.objects.contacts.write. Add the scope in HubSpot (Edit on a service key, or the Scopes tab of a legacy app). For legacy apps the token value stays the same when scopes change; if a service key shows a new value, rotate it in Fondoo.
  • You cannot find "Create legacy app". Legacy private app creation is being switched off (see above). Use a service key.
  • "Provider request failed (409)" on create. HubSpot uses email as the unique contact key; a contact with that email probably exists. List it and use contacts.update instead.
  • "Provider request failed (400)". A property name or value is invalid. Use HubSpot internal property names such as email, firstname, lastname, inside properties.
  • Rate limit errors. Wait and retry; see below.

Limits, data and security

  • HubSpot limits for privately distributed apps (service keys follow the same limits): Free and Starter 100 requests per 10 seconds and 250,000 per day; Professional 190 per 10 seconds and 625,000 per day; Enterprise 190 per 10 seconds and 1,000,000 per day. See usage guidelines.
  • Fondoo limit: a local budget of 60 requests per minute per connection. HubSpot's limits and Retry-After stay authoritative.
  • What Fondoo stores: the token, encrypted in Fondoo's connector vault. list_connections shows only a masked value.
  • Rotate: HubSpot suggests rotating every six months. In HubSpot click Rotate on the key (choose "Rotate and expire later" for a 7-day overlap), then run rotate_connection_key({ connectionId }) in Fondoo and paste the new value on the secure page. You can set rotateAfter on add_connection_key to get a reminder.
  • Disconnect: delete_connection({ connectionId }) (agents need owner approval). It does not revoke the token at HubSpot, so also delete the service key or the legacy app in HubSpot.