OpenAPI Marketplace · CRM & Sales

HubSpot CRM Contacts

Name: HubSpot CRM Contacts
Author: vx.ai

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

Find, read, create and update contacts in HubSpot CRM: search by email, name or any property, read contacts with their associations, and upsert contacts in batches by email. Curated from HubSpot's official OpenAPI specification.

Connect this API to an AI agent Browse all specs

What you can do with HubSpot CRM Contacts 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.

Method	Path	Operation	Description
POST	`/crm/v3/objects/contacts/search`	searchContacts	Search contacts by email, name or any property
GET	`/crm/v3/objects/contacts`	listContacts	List contacts page by page
POST	`/crm/v3/objects/contacts`	createContact	Create a contact
GET	`/crm/v3/objects/contacts/{contactId}`	getContact	Get one contact by id or email
PATCH	`/crm/v3/objects/contacts/{contactId}`	updateContact	Update a contact's properties
POST	`/crm/v3/objects/contacts/batch/read`	batchReadContacts	Get several contacts by id or email at once
POST	`/crm/v3/objects/contacts/batch/upsert`	batchUpsertContacts	Create or update several contacts matched by email

Authentication

PrivateAppToken

Bearer token — sent as Authorization: Bearer <token>

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

How to get a credential

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

Permissions used

Scope	Operations
crm.objects.contacts.read	searchContacts, listContacts, getContact, batchReadContacts
crm.objects.contacts.write	createContact, updateContact, batchUpsertContacts

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). Check internal property names in Settings > Properties.
409 Conflict: a contact with that email already exists; update it instead.
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.contacts.read and crm.objects.contacts.write) as the Bearer credential.
Optionally pin properties to the fields you always want back (e.g. email,firstname,lastname,phone,company,lifecyclestage,hubspot_owner_id). By default HubSpot returns only a few.

Find or update a contact

Look the person up first. By email: getContact with contactId = the email and idProperty=email. By anything else: searchContacts with filterGroups, e.g. [{"filters":[{"propertyName":"lastname","operator":"EQ","value":"Nguyen"}]}], or a free-text query.
If found, show the user the changes and confirm, then call updateContact with the contact id and properties (only the fields to change).
If not found, confirm and call createContact with properties (email strongly recommended). A 409 means the email already exists: update that contact instead.
For lists of people (imports, sync), confirm the batch, then batchUpsertContacts with inputs of {"id": "<email>", "idProperty": "email", "properties": {...}} (max 100 per call).

Reading many contacts

batchReadContacts: up to 100 ids (or emails with idProperty=email) in inputs.
listContacts: pages with limit (max 100) and after (from paging.next.after).
searchContacts: limit up to 200, after for the next page; max 10,000 results per query.

Good to know

Creating or changing contacts edits customer data: confirm createContact, updateContact and batchUpsertContacts with the user first.
Use internal property names (firstname, not "First name"); see Settings > Properties. All property values are sent as strings.
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 (keep to a few groups).
Search results can lag a few seconds behind writes.

How to use this spec

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