VX Agents

OpenAPI Marketplace · CRM & Sales

HubSpot CRM Companies

v1.0.0 · 6 endpoints · 0 connections · shared by vx.ai

Find, read, create and update companies in HubSpot CRM: search by domain, name, industry or any property, read companies with their associated contacts and deals, and keep account records up to date. Curated from HubSpot's official OpenAPI specification.

Connect this API to an AI agent Browse all specs

What you can do with HubSpot CRM Companies via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
POST /crm/v3/objects/companies/search searchCompanies Search companies by domain, name or any property
GET /crm/v3/objects/companies listCompanies List companies page by page
POST /crm/v3/objects/companies createCompany Create a company
GET /crm/v3/objects/companies/{companyId} getCompany Get one company with its properties and associated records
PATCH /crm/v3/objects/companies/{companyId} updateCompany Update a company's properties
POST /crm/v3/objects/companies/batch/read batchReadCompanies Get several companies by id at once

Authentication

PrivateAppToken

Bearer token — sent as Authorization: Bearer <token>

HubSpot private app access token sent as Authorization: Bearer <token>.

How to get a credential

  1. In HubSpot, open Settings > Integrations > Private Apps (Super Admin required).
  2. Click Create a private app and name it (e.g. VX Agents).
  3. On the Scopes tab, add crm.objects.companies.read and crm.objects.companies.write.
  4. Click Create app, then copy the access token (starts with pat-).

Permissions used

Scope Operations
crm.objects.companies.read searchCompanies, listCompanies, getCompany, batchReadCompanies
crm.objects.companies.write createCompany, updateCompany

Common errors

  • 401 Unauthorized: the token is wrong, rotated or missing the Bearer prefix. Copy it again from the private app.
  • 403 Forbidden: the private app is missing a scope above (MISSING_SCOPES). Add it and use the updated token.
  • 400 Bad Request: unknown property name or invalid value (e.g. enum option such as industry). Check internal property names in Settings > Properties.
  • 429 Too Many Requests: rate limit hit (per 10 seconds and daily); wait and retry.

Store the token as a VX Agents credential (Bearer token); never paste it into chat.

Usage guide

Setup

  • Add a HubSpot private app token (scopes crm.objects.companies.read and crm.objects.companies.write) as the Bearer credential.
  • Optionally pin properties to the fields you always want back (e.g. name,domain,industry,city,country,phone,numberofemployees,lifecyclestage,hubspot_owner_id). By default HubSpot returns only a few.

Find or update a company

  1. Look the company up first with searchCompanies: by website, filterGroups [{"filters":[{"propertyName":"domain","operator":"EQ","value":"acme.com"}]}] (bare domain, no https:// or www.); by name, a free-text query or CONTAINS_TOKEN on name.
  2. Read details with getCompany (add associations=contacts,deals to see linked records).
  3. If found, show the user the changes and confirm, then updateCompany with the company id and only the properties to change.
  4. If not found, confirm and call createCompany with properties (name and domain recommended). HubSpot does not block duplicates by name, so always search by domain first.

Reading many companies

  • batchReadCompanies: up to 100 ids in inputs.
  • listCompanies: pages with limit (max 100) and after (from paging.next.after).
  • searchCompanies: limit up to 200, after for the next page; max 10,000 results per query.

Good to know

  • Creating or changing companies edits customer data: confirm createCompany and updateCompany with the user first.
  • Use internal property names (numberofemployees, not "Number of employees"); see Settings > Properties. All property values are sent as strings; enum fields such as industry need the internal option value (e.g. COMPUTER_SOFTWARE).
  • Dates/datetimes are ISO 8601 or Unix milliseconds; date-only properties need midnight UTC.
  • Search filter operators: EQ, NEQ, LT, LTE, GT, GTE, CONTAINS_TOKEN, HAS_PROPERTY, NOT_HAS_PROPERTY, IN, BETWEEN. Filters in one group are AND, groups are OR.
  • Search results can lag a few seconds behind writes.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “HubSpot CRM Companies” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs

  • Attio CRM — Lets an agent find, read, create and update Attio records (people, companies, deals and custom objects), work with list…
  • HubSpot CRM Deals — Track the sales pipeline in HubSpot CRM: search deals by stage, owner, amount or close date, read deals with their asso…
  • HubSpot CRM Contacts — Find, read, create and update contacts in HubSpot CRM: search by email, name or any property, read contacts with their …