# 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/changelog/extension-contact-lists-api-v1-sunset-moved-to-april-30-2026
- 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

## Machine-readable

- Advisory: https://github.com/SriVarshini09/shapi-advisories/blob/main/advisories/hubspot-contact-lists-v1-sunset.json
- OSV: https://shapi.dev/osv/hubspot-contact-lists-v1-sunset.json