Read and write HubSpot CRM contacts, deals, and companies via the v3 objects API.

Provided free and as is, without warranty of any kind — including merchantability, fitness for a particular purpose, and the accuracy or completeness of any result. See the licence. You are responsible for checking what this produces before relying on it.

HubSpot

Read and write HubSpot CRM records — contacts, deals, and companies — through the HubSpot CRM v3 objects API.

Base URL: https://api.hubapi.com
Auth: Authorization: Bearer <private app access token>
Grounded in: https://developers.hubspot.com/docs/api/overview

Operations

operation	HTTP	endpoint	params
`list_contacts`	GET	`/crm/v3/objects/contacts`	`limit`
`get_contact`	GET	`/crm/v3/objects/contacts/{id}`	`contactId`
`create_contact`	POST	`/crm/v3/objects/contacts`	`email`, `firstname`, `lastname` (≥1)
`search_contacts`	POST	`/crm/v3/objects/contacts/search`	`query` or `email`, `limit`
`list_deals`	GET	`/crm/v3/objects/deals`	`limit`
`list_companies`	GET	`/crm/v3/objects/companies`	`limit`

create_contact sends {"properties": {...}}. search_contacts sends a free-text query when provided, otherwise an EQ filter on the email property.

The tool never throws on a non-2xx HTTP response: it returns the HTTP status and the raw response result body so the caller can inspect HubSpot's error payload. Response bodies are capped at 5 MB. Standard-library Python only — no requests.

Getting the apiKey

In HubSpot, go to Settings → Integrations → Private Apps.
Click Create a private app, name it, and on the Scopes tab grant the CRM scopes you need (e.g. crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.deals.read, crm.objects.companies.read).
Create the app and copy the access token — that string is the apiKey input. It is sent as Authorization: Bearer <token>.

Outputs

result — the raw HubSpot JSON response body (as a string).
status — the HTTP status code as a string (e.g. "200", "201", "404").

Examples

Search a contact by email

operation     = search_contacts
apiKey        = pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
email         = [email protected]

Returns the matching contact records (status = 200).

Create a contact

operation     = create_contact
apiKey        = pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
email         = [email protected]
firstname     = New
lastname      = Lead

Creates the contact and returns the new object with its id (status = 201).

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.

error
result
status

Input Properties

Every property this tool accepts, from its own tool.iml.

Property	Type	Required	Default	Description
`apiKey`	string	yes	—	HubSpot private app access token. Create one at HubSpot > Settings > Integrations > Private Apps, then copy the access token (sent as 'Authorization: Bearer ').
`operation`	string	yes	—	One of: list_contacts, get_contact, create_contact, search_contacts, list_deals, list_companies
`contactId`	string	no	—	Contact object id — required for get_contact.
`email`	string	no	—	Email address — used as the search value for search_contacts and (with firstname/lastname) as a property for create_contact.
`firstname`	string	no	—	First name — optional property for create_contact.
`lastname`	string	no	—	Last name — optional property for create_contact.
`query`	string	no	—	Free-text search string for search_contacts (matched against default searchable properties). If empty, 'email' is used as an EQ filter.
`limit`	string	no	`10`	Max records to return for list_* and search_contacts (1-100).