# Map legacy ids to UUIDs

Maps legacy integer sequential ids to their UUID values for the
practice identified by `X-Practice-Id`.
The request must include:
- `resource` — one of `patient`, `practitioner`, `appointment`, or `invoice`
- `ids` — between 1 and 100 inclusive legacy integer ids

The response contains a mapping only for ids that match a record. Requested
ids with no match are omitted.

Endpoint: POST /identifier_mappings
Version: 2026-01-01
Security: oauth2

## Security:

  - `oauth2` (unknown)
    oauth2 scopes: identifier_mapping:read

## Header parameters:

  - `X-Practice-Id` (string, required)
    UUID of the **practice** in whose context the request is executed. The API
uses this to resolve data the caller is permitted to access for that practice.

## Request body:

  - `application/json` (unknown)
    Legacy identifiers to map.

## Request fields (application/json):

  - `resource` (string, required)
    The NexGen resource type to map identifiers for. Supported values are `patient`, `practitioner`, `appointment`, and `invoice`.
    Enum: "patient", "practitioner", "appointment", "invoice"

  - `ids` (array, required)
    Legacy integer sequential ids to map. Between 1 and 100 ids must be supplied. Each value must be a numeric sequential id for the requested resource.

## Request examples:

  - `Map patient legacy ids` (unknown)

  - `Map appointment legacy ids` (unknown)

  - `Map invoice legacy ids` (unknown)

  - `Map practitioner legacy ids` (unknown)

## Response 200:

  - `200` (unknown)
    Mapped identifiers.

## Response 200 fields (application/json):

  - `data` (array, required)
    Mappings for requested ids that matched a record. Ids with no match are omitted.

  - `data.id` (integer, required)
    The legacy integer sequential id for the matched resource.
    Example: 42

  - `data.uuid` (string, required)
    The UUID for the resource within the practice.
    Example: 4EE0FA3E-12F4-4942-9347-1702EB89EBCC

## Response 400:

  - `400` (unknown)
    Malformed Request ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 400 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 401:

  - `401` (unknown)
    Unauthorized - Provide proof of identity ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 401 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 4XX:

  - `4XX` (unknown)
    User Error ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 4XX fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 5XX:

  - `5XX` (unknown)
    Server Error ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 5XX fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 400 examples:

  - `Malformed or invalid request` (unknown)
    RFC 7807 problem details when validation fails (e.g. missing required field).

## Response 401 examples:

  - `Missing or invalid credentials` (unknown)
    RFC 7807 problem details when the caller is not authenticated.

## Response 4XX examples:

  - `Generic client error response` (unknown)
    RFC 7807 problem details for a generic client error (e.g. conflict, unsupported media type).

## Response 5XX examples:

  - `Unexpected server error` (unknown)
    RFC 7807 problem details for an internal failure.