Contact Lists API v1 retired on 2026-04-30; endpoints return 404
- Provider
- HubSpot
- Endpoint
* /contacts/v1/lists/**- Effective
- 2026-04-30
- Severity
- critical
- Change
- version-sunset
- Status
- verified
What changed
HubSpot sunset the v1 Contact Lists API on 2026-04-30 (moved from 2025-09-30). Since then the /contacts/v1/lists endpoints for creating, updating, deleting and reading lists and list contacts return HTTP 404. The replacement is the Lists API (2026-03 or v3), which uses a new listId instead of the v1 legacyListId.
What to do
Map each stored legacyListId to the new listId with GET /crm/lists/2026-03/idmapping?legacyListId=... (or POST /crm/lists/2026-03/idmapping for up to 10,000 ids; ids in missingLegacyListIds no longer exist), then move reads to GET /crm/lists/2026-03/{listId} and /crm/lists/2026-03/{listId}/memberships, and membership writes to PUT /crm/lists/2026-03/{listId}/memberships/add, /remove or /add-and-remove. The legacy GET /v1/lists/{legacyListId}/sizeAndEditsHistory/between endpoint was retired too and is not covered by this path pattern.
Sources
- Provider notice (2025-09-12)
- https://developers.hubspot.com/docs/api-reference/legacy/crm/lists/v1-list-api-migration-guide
- https://developers.hubspot.com/docs/api-reference/latest/deprecated-apis
Check your code
npx shapi-cli scan .shapi scan lists the call sites this change affects; shapi fix repairs them test-first when the advisory has an automatic fix. All advisories · Markdown · OSV · JSON