---
title: "Map IDs"
method: POST
path: "/crm/lists/2026-09/idmapping"
tags: ["Basic"]
---

# Map IDs

`POST /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`

Map legacy list IDs to their corresponding new IDs in the HubSpot system. This endpoint is useful for migrating data from older systems to the current HubSpot structure, ensuring that all list references are updated correctly.

## Request body

- string[]

## Response `200`

successful operation

- PublicBatchMigrationMapping
  - `legacyListIdsToIdsMapping` PublicMigrationMapping[], required: An array of PublicMigrationMapping objects that map legacy list IDs to their corresponding new IDs.
    - `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.
  - `missingLegacyListIds` string[], required: An array of strings representing legacy list IDs that could not be found or migrated.

## 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/post.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)