Connect HubSpot

Solutioneer uses the Composio hubspot toolkit to read CRM records during discovery. HubSpot is the only CRM with auto-ingest support in v1 — for other CRMs, use a CSV export or pasted records.

Prerequisites

• A Composio API key in .env.
• A HubSpot account with access to the records you want Solutioneer to read (contacts, companies, deals).

What gets connected

The hubspot toolkit bundles read-only CRM access under one OAuth connection. After connecting, Solutioneer can call these specific tool slugs:

• HUBSPOT_READ_APAGE_OF_OBJECTS_BY_TYPE — paginate objects by type (contacts, companies, deals).
• HUBSPOT_READ_CRM_OBJECT_BY_ID — fetch a single CRM object by ID.
• HUBSPOT_READ_BATCH_OF_CRM_OBJECTS_BY_ID_OR_PROPERTY_VALUES — batch read across IDs or property filters.
• HUBSPOT_READ_CONTACT — fetch a contact record.
• HUBSPOT_READ_CONTACTS — list contacts.

All five are read-only. Solutioneer does not write to HubSpot in v1.

How to connect

The normal flow runs inside Codex during an ingestion request:

1. Ask Solutioneer to pull from HubSpot. For example: “Ingest the Acme Health deal from HubSpot into a fact sheet.”
2. Codex verifies that COMPOSIO_API_KEY is present.
3. Codex checks whether the hubspot toolkit is connected.
4. If it is not, Codex offers Connect now / Skip.
5. Connect now opens the Composio hosted login page in a browser tab.
6. You complete the HubSpot OAuth flow.
7. Codex polls the connected account until it becomes ACTIVE.
8. Once active, Codex reads the requested records.

If browser tooling is unavailable (for example, in a sandboxed environment), Codex provides the login link in chat and waits for you to finish the flow.

Connect from the Composio dashboard

If you prefer to connect ahead of time:

1. Open the Composio dashboard.
2. Go to Connections (or Toolkits, depending on the current layout).
3. Find the hubspot toolkit.
4. Click Connect and complete the HubSpot OAuth flow.
5. Confirm the connection shows as Active.

Next time Codex checks for a hubspot connection, it will find it already active.

Which skills read from HubSpot

• Discovery Context Ingester — the primary consumer. Records are normalized into the fact sheet with composio://hubspot/... provenance markers.

Downstream skills (discovery-question-generator, architecture-fit-mapper, integration-fit-gap-analyzer, security-review-prep, poc-handoff-orchestrator) do not call HubSpot directly. They read the fact sheet instead.

Confirmation rules

Ingestion is triggered explicitly. Codex will not pull from HubSpot unless you name HubSpot as a source or ask for CRM context directly. Once the toolkit is connected, subsequent ingestion runs do not re-prompt for consent.

Troubleshooting

• Connection stuck in pending. The most common cause is an incomplete OAuth flow. Re-open the link and finish sign-in. Codex polls for up to five minutes before timing out.
• Wrong portal. Each HubSpot OAuth flow is tied to the portal you sign in with. If you need a different portal, disconnect the toolkit in the Composio dashboard and reconnect with the right account.
• Missing records. HubSpot access is scoped to whatever the authenticated user can see. Ask a portal admin to widen the user’s access if records are expected but not returned.

See Troubleshooting for more.