HubSpot Service Tickets
Find, read, create and update support tickets in HubSpot Service Hub: search tickets by status, owner, priority or any property, read tickets with their associated contacts and companies, and log or move tickets through pipeline stages. Curated from HubSpot's official OpenAPI specification.
Connect this API to an AI agent Browse all specs
What you can do with HubSpot Service Tickets 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/tickets/search |
searchTickets | Search tickets by status, owner, priority or any property |
| GET | /crm/v3/objects/tickets |
listTickets | List tickets page by page |
| POST | /crm/v3/objects/tickets |
createTicket | Create a ticket, optionally linked to a contact or company |
| GET | /crm/v3/objects/tickets/{ticketId} |
getTicket | Get one ticket with its properties and associated records |
| PATCH | /crm/v3/objects/tickets/{ticketId} |
updateTicket | Update a ticket's properties, e.g. move it to another stage or owner |
| POST | /crm/v3/objects/tickets/batch/read |
batchReadTickets | Get several tickets 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
- 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
tickets(read and write tickets). - Click Create app, then copy the access token (starts with
pat-).
Permissions used
| Scope | Operations |
|---|---|
| tickets | searchTickets, listTickets, getTicket, batchReadTickets, createTicket, updateTicket |
Common errors
- 401 Unauthorized: the token is wrong, rotated or missing the
Bearerprefix. Copy it again from the private app. - 403 Forbidden: the private app is missing the
ticketsscope (MISSING_SCOPES). Add it and use the updated token. - 400 Bad Request: unknown property name, invalid enum value, or a missing/invalid
hs_pipeline/hs_pipeline_stageon create. Check internal property names in Settings > Properties and stage ids in Settings > Objects > Tickets > Pipelines. - 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 (scope
tickets) as the Bearer credential. - Optionally pin
propertiesto the fields you always want back (e.g.subject,content,hs_pipeline,hs_pipeline_stage,hs_ticket_priority,hubspot_owner_id,createdate). By default HubSpot returns only a few. - Pin your pipeline and stage ids if they differ from the default Help Desk pipeline (
hs_pipeline=0; stages1New,2Waiting on contact,3Waiting on us,4Closed). Custom ids are in Settings > Objects > Tickets > Pipelines.
Triage tickets
- Find open work with
searchTickets, e.g.filterGroups[{"filters":[{"propertyName":"hs_pipeline_stage","operator":"EQ","value":"1"}]}],sorts[{"propertyName":"createdate","direction":"DESCENDING"}], and thepropertiesyou need. - Open one with
getTicket(associations=contacts,companiesto see who raised it). - Show the user the planned change and confirm, then
updateTicketwith only the fields to change, e.g.{"properties":{"hs_pipeline_stage":"3","hs_ticket_priority":"HIGH","hubspot_owner_id":"123"}}.
Log a new ticket
- Confirm subject, description and priority with the user.
createTicketwithpropertiessubject,content,hs_pipeline,hs_pipeline_stage(both required), optionalhs_ticket_priority(LOW,MEDIUM,HIGH,URGENT) andhubspot_owner_id.- To link it, add
associations:[{"to":{"id":"<contactId>"},"types":[{"associationCategory":"HUBSPOT_DEFINED","associationTypeId":16}]}](16 = ticket→contact, 339 = ticket→company).
Reading many tickets
batchReadTickets: up to 100 ids ininputs.listTickets:limit(max 100) andafterfrompaging.next.after.searchTickets:limitup to 200,afterfor the next page; max 10,000 results per query.
Good to know
- Creating or changing tickets edits customer data: confirm
createTicketandupdateTicketwith the user first. - Use internal property names; all property values are sent as strings. Datetimes are ISO 8601 or Unix milliseconds.
- Filters in one group are AND, groups are OR. 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 Service Tickets” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.