---
title: "Retrieve ID Mapping"
method: GET
path: "/crm/lists/2026-09/idmapping"
tags: ["Basic"]
---

# Retrieve ID Mapping

`GET /crm/lists/2026-09/idmapping`

## Request

- Base URL: `https://api.hubapi.com`
- URL: `https://api.hubapi.com/crm/lists/2026-09/idmapping`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.hubspot.com/oauth/authorize`
    - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.segments.read`
  - OAuth 2
    - Authorization code: `https://app.hubspot.com/oauth/authorize`
    - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.lists.read`

Retrieve the mapping of legacy list IDs to their current IDs in the HubSpot system. This endpoint is useful for migrating or updating systems that rely on legacy list identifiers.

## Query parameters

- `legacyListId` string

## Response `200`

successful operation

- PublicMigrationMapping
  - `legacyListId` string, required: The legacy list ID from the previous system. This is a string that represents the list ID in the legacy system.
  - `listId` string, required: The new list ID in the HubSpot system. This is a string that uniquely identifies the list in the current system.

## Other responses

- `default`: An error occurred.

## Changes

- **2026-10-10** (2026-09) `e1dd745172d1`: 2 info
  - the security scope `crm.segments.read` was added to the endpoint's security scheme `oauth2`
  - the security scope `crm.lists.read` was removed from the endpoint's security scheme `oauth2`
- **2026-09-07** (2026-09) `6d0e6dc36ca0`: 2 info
  - the security scope `crm.segments.read` was added to the endpoint's security scheme `oauth2`
  - the security scope `crm.lists.read` was removed from the endpoint's security scheme `oauth2`

[Operation history](https://skmtc.dev/hubspot/apis/crm-lists/changes/crm/lists/2026-09/idmapping/get.md)

---

[API](https://skmtc.dev/hubspot/apis/crm-lists.md) - [All operations](https://skmtc.dev/hubspot/apis/crm-lists/llms.txt) - [OpenAPI document](https://skmtc.dev/hubspot/apis/crm-lists/revisions/e1dd745172d1?raw)