VX Agents

API directory · Marketing & Analytics

HubSpot Segments & List Memberships

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

Build and maintain HubSpot segments (formerly lists): search them by name or type, check which segments a contact is in, add or remove members of manual and snapshot segments, copy members from one segment to another, and track a segment's size over time before a campaign goes out.

Connect this API to an AI agent Browse all specs

What you can do with HubSpot Segments & List Memberships 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/lists/2026-09/search searchSegments Search segments by name, object type or processing type
GET /crm/lists/2026-09/{listId} getSegment Get one segment by id, with its size and filters
GET /crm/lists/2026-09/object-type-id/{objectTypeId}/name/{listName} getSegmentByName Get a segment by its exact name
POST /crm/lists/2026-09 createSegment Create a manual segment (members added by API or by hand)
PUT /crm/lists/2026-09/{listId}/update-list-name renameSegment Rename a segment
GET /crm/lists/2026-09/{listId}/memberships listSegmentMembers List the record ids in a segment, page by page
GET /crm/lists/2026-09/{listId}/memberships/join-order listSegmentMembersByJoinDate List a segment's members in the order they joined
GET /crm/lists/2026-09/records/{objectTypeId}/{recordId}/memberships getRecordSegments List the segments one contact or other record belongs to
PUT /crm/lists/2026-09/{listId}/memberships/add addSegmentMembers Add records to a manual or snapshot segment
PUT /crm/lists/2026-09/{listId}/memberships/remove removeSegmentMembers Remove records from a manual or snapshot segment
PUT /crm/lists/2026-09/{listId}/memberships/add-from/{sourceListId} copySegmentMembers Add every member of another segment to this one
GET /crm/lists/2026-09/{listId}/size-and-edits-history/between getSegmentSizeHistory Get a segment's size and edit history between two dates
GET /crm/lists/2026-09/folders listSegmentFolders List segment folders and the segments in them
PUT /crm/lists/2026-09/folders/move-list moveSegmentToFolder Move a segment into a folder

Authentication

private_app_token

Bearer token — sent as Authorization: Bearer <token>

HubSpot private app access token (or an OAuth access token), sent as Authorization: Bearer <token>.

How to get a credential

  1. In HubSpot, open Development (or Settings > Integrations) > Legacy apps / Private apps.
  2. Click Create legacy app > Private, and name it (e.g. VX Agents segments).
  3. On the Scopes tab add crm.lists.read and crm.lists.write (newer accounts may show them as crm.segments.read / crm.segments.write; either pair works). Add crm.objects.contacts.read if you also look contacts up elsewhere.
  4. Create the app and copy the access token (pat-...).

Permissions used

Scope Operations
crm.lists.read (or crm.segments.read) searchSegments, getSegment, getSegmentByName, listSegmentMembers, listSegmentMembersByJoinDate, getRecordSegments, getSegmentSizeHistory, listSegmentFolders
crm.lists.write (or crm.segments.write), plus the read scope createSegment, renameSegment, addSegmentMembers, removeSegmentMembers, copySegmentMembers, moveSegmentToFolder

Common errors

Status Meaning Fix
401 Token missing, expired or revoked Copy the token again from the private app; rotate it if it was revoked.
403 Scope missing Add the list/segment scopes above and use the new token.
400 Membership change on a DYNAMIC segment, duplicate segment name, or bad objectTypeId Only MANUAL and SNAPSHOT segments accept membership edits; names must be unique; contacts are 0-1.
429 Rate limit (per 10 seconds and per day, by plan) Wait a few seconds and retry.

Store the token as a VX Agents credential (Bearer token).

Usage guide

Setup

  • Credential: a HubSpot private app token (Bearer) with the list/segment scopes.
  • Object type ids: contacts 0-1, companies 0-2, deals 0-3. Most segments hold contacts, so objectTypeId 0-1 is worth pinning.
  • Segment ids (listId) are the ILS ids shown in the segment's URL in HubSpot.

Prepare an audience for a campaign

  1. Find the segment: searchSegments with {"query": "webinar", "processingTypes": ["MANUAL", "SNAPSHOT"], "count": 20}, or getSegmentByName with objectTypeId and the exact name.
  2. getSegment shows its processingType (MANUAL, SNAPSHOT or DYNAMIC) and size; add includeFilters=true to see the filter tree of a dynamic one.
  3. Read members with listSegmentMembers (limit defaults to 100, page with after from paging.next.after), or listSegmentMembersByJoinDate to see who joined most recently. Results are record ids; read details with a HubSpot contacts tool.
  4. New audience: createSegment with {"name": "Q4 webinar follow-up", "objectTypeId": "0-1", "processingType": "MANUAL"} (names must be unique), then addSegmentMembers with a JSON array of record ids, e.g. ["101", "202"].
  5. removeSegmentMembers takes the same array; copySegmentMembers adds every member of sourceListId (up to 100,000 records per call).
  6. Tidy up: renameSegment with the listName query parameter, listSegmentFolders and moveSegmentToFolder ({"listId": "...", "newFolderId": "..."}).

Check a contact or a trend

  • getRecordSegments with objectTypeId 0-1 and the contact id lists every segment that contact is in.
  • getSegmentSizeHistory with startDate and endDate shows how the segment grew or shrank and which edits changed it.

Good to know

  • DYNAMIC segments update themselves from filters; their members cannot be added or removed by API. Filter edits, deletes and conversions are not in this spec.
  • Adding or removing members can change who gets emails and workflows: confirm the segment and the record count with the user first.
  • Dates are ISO 8601 (2026-10-01T00:00:00Z); ids are strings.

Source: HubSpot Lists (segments) API guide (https://developers.hubspot.com/docs/api-reference/latest/crm/lists/guide), checked 2026-10-25.

How to use this spec

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

Related APIs