# Migrate a Unify request

Move an earlier Unify v3 request to the current request format while keeping the invoice data you supply. Test the converted request in sandbox before sending production documents.

## Change the request envelope

The endpoint remains `POST https://prod.gets.complyance.io/api/v3/unify`. Send `new-api: true` as an HTTP header to select the current format.

| Earlier request | Current request |
| - | - |
| `env` | `environment` |
| `defaults.country` or an invoice’s country | `country` on each document |
| `defaults.logicalDocumentType` or an invoice’s document type | `documentType` on each document |
| `defaults.source.name` and `defaults.source.version` | `source` as `name:version` on each document |
| `invoices[].payload` | Root `payload` for one document, or `invoices[].payload` in a batch |

For one document, put `country`, `environment`, `purpose`, `source`, `documentType` and `payload` at the request root. For a batch, put those values on **each** item in `invoices`. The current format has no shared `defaults`. Check each earlier invoice and provide its intended values explicitly; do not assume that a value from one invoice applies to another.

Keep the invoice’s mapped source data in `payload`. The [GETS field reference](https://docs.complyance.io/api-reference/gets/fields/) shows the fields used when your source sends GETS directly. The [submit and retrieve guide](https://docs.complyance.io/api-reference/unify/submit-and-retrieve/) shows the current single-document request and response.

## Update response handling

For a single invoicing request, `200` means the document passed validation; save `documentId` and follow delivery separately. A `422` response contains `errors` to correct. Read [Unify errors](https://docs.complyance.io/api-reference/unify/errors/) before changing how your client handles failures. For a batch, inspect the result for each item instead of treating the batch as one document result.

## Test the change

1. Use a sandbox API key and set `environment` to `sandbox`.
2. Send `new-api: true` with a representative invoice. Check the request in the [API playground](https://docs.complyance.io/api/?operation=submitDocument) or use the [complete quickstart example](https://docs.complyance.io/get-started/quickstart/).
3. Compare the returned document number and validation findings with the values you sent. Correct your source data or mapping when a field differs.
4. Test a credit note and any batch or invoice-specific values your integration uses.
5. When the sandbox results are correct, use your production key with `environment` set to `production`.

Source: https://docs.complyance.io/api-reference/unify/migration/