# Migrate Distinct Id

POST /api/v2/projects/{projectId}/crm/contacts/migrate-distinct-id

Re-keys a contact from one distinct ID to another, carrying their properties and history across. The usual case is promoting a soft identity to a real one: someone first seen by email gets a `soft_`-prefixed ID, and when they later sign in you migrate that to your own user ID so the two do not persist as separate contacts. Rewriting the analytics history is expensive, so this is not a bulk operation.

## Request

- projectId: string, path, required — ID of the project that owns the contact.
- newDistinctId: string, required — The distinct ID to move the contact to, typically your own user ID.
- oldDistinctId: string, required — The contact's current distinct ID, often a generated `soft_` one.

## Response

- 200: Successful response
  - createdAt: string, required
  - distinctId: string, required
  - id: string, required
  - projectId: string, required
  - toDelete: boolean, required
  - updatedAt: string, required
  - email: string
- 400: Invalid input data
- 401: Authorization not provided
- 403: Insufficient access
- 500: Internal server error