Unify V2 (Recommended)

Unify V2 is the recommended contract for converting and validating business documents with Complyance. It supports both direct single-document requests and bulk requests. For each document, it applies the source mapping configured for your workspace, converts the payload into a canonical GETS document, and validates the result.

Recommended for all new integrations. If you currently use the Unify V1 bulk envelope, you can continue using it while you migrate. See Migrate from Unify V1 for a step-by-step guide.

Why use Unify V2?

• Flexible requests — send one document directly or submit one or more documents in an invoices array.
• Explicit controls — country, environment, source, and document type are provided for every document, whether at the request root or inside each invoices[] item.
• Direct outcomes — successful documents return HTTP 200; document validation failures return HTTP 422.
• Actionable validation findings — errors can identify both the canonical GETS field and the corresponding path in your source payload.
• Optional diagnostics — request timing and mapping diagnostics with debug: true when troubleshooting.
• Minimal migration effort — your mapped source payload normally remains unchanged.

Choose the correct contract

Both contracts use the same endpoint. The new-api HTTP header selects the contract.

The selector must be sent as an HTTP header. Do not put new-api in the JSON body.

Before you begin

You need:

1. A Complyance API key for your workspace and target environment.
2. A source mapping configured for your workspace.
3. The source alias and version supplied for your integration, such as AES:1.
4. A country and document type supported by that source mapping.
5. The API base URL supplied for your environment.

Endpoint and authentication

POST /api/v3/unify
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Accept: application/json
new-api: true

Examples in this guide use:

https://prod.gets.complyance.io/api/v3/unify

Use the base URL provided by Complyance for your environment.

Your API key must match the requested environment:

An environment mismatch returns HTTP 403.

Quick start

{
  "country": "AE",
  "environment": "sandbox",
  "purpose": "mapping",
  "source": "AES:1",
  "documentType": {
    "base": "tax_invoice",
    "modifiers": []
  },
  "payload": {
    "invoice_data": {
      "document_number": "INV-AE-1001",
      "invoice_date": "2026-07-10",
      "currency_code": "AED",
      "tax_exclusive_amount": 2250,
      "total_tax_amount": 112.5,
      "total_amount": 2362.5,
      "amount_due": 2362.5
    },
    "seller_info": {
      "seller_name": "Acme LLC",
      "country_code": "AE",
      "vat_number": "100000000000003"
    },
    "buyer_info": {
      "buyer_name": "Buyer LLC",
      "buyer_country": "AE"
    },
    "line_items": [
      {
        "line_id": "1",
        "item_name": "Electronic equipment",
        "quantity": 1,
        "net_price": 2250,
        "line_total": 2250,
        "tax_category": "S",
        "tax_rate": 5,
        "line_vat": 112.5
      }
    ]
  }
}

The fields required inside payload depend on your configured source mapping and the applicable country rules. Use the mapping specification supplied for your integration; the payload above is representative.

Choose the purpose

Set purpose according to what the request should do:

The examples use mapping. Change it to invoicing when you want to send an invoice. In a bulk request, set purpose separately for each invoices[] item.

Request formats

Unify V2 supports two request formats:

• Single: put one document's controls and payload at the request root.
• Bulk: put an invoices array at the request root. Every invoices[] item is a complete document request containing its own controls and payload.

Do not combine the formats in one request. A bulk request has invoices at the root; fields such as country, environment, source, documentType, and payload belong inside each array item.

How source mapping works

Your payload can use any JSON structure supported by your configured source mapping:

{
  "invoice_data": {
    "document_number": "INV-1001"
  },
  "seller_info": {
    "seller_name": "Acme LLC"
  }
}

The source value tells Complyance which mapping to apply. For example, the mapping may convert invoice_data.document_number into the canonical GETS field header.documentId.

The source mapping must be available to your authenticated workspace and support the requested country and document type. You do not need to rename your source fields or construct a GETS document yourself.

See the Field Mapping Reference for country-specific guidance.

Processing flow

For a standard mapping or invoicing request, Complyance:

1. Authenticates the caller and checks the requested environment.
2. Resolves the source mapping for the authenticated workspace.
3. Maps the source payload to a canonical GETS document.
4. Validates the GETS document against applicable rules.
5. Generates and validates the invoice XML.
6. Returns the document result or structured validation findings.

Successful single-document response

A successfully converted and validated single request returns HTTP 200:

{
  "documentId": "6a7eab425227e2981a38f486",
  "message": "Your invoice was validated and is ready for submission.",
  "Base64XML": "PEludm9pY2U+PC9JbnZvaWNlPg=="
}

Validation and processing errors

If mapping succeeds but GETS or XML validation fails, the API returns HTTP 422 and an errors array. Request, authentication, and source-resolution errors use other HTTP statuses and a smaller response body.

See Responses and Errors for response fields, status codes, and client-handling guidance.

Single-document and bulk workflows

Use the single format when you need to process one document directly. Use the bulk format to submit one or more documents through an invoices array:

{
  "invoices": [
    {
      "country": "AE",
      "environment": "sandbox",
      "purpose": "mapping",
      "source": "AES:1",
      "documentType": {
        "base": "tax_invoice",
        "modifiers": []
      },
      "payload": {
        "invoice_data": {
          "document_number": "INV-AE-1001"
        }
      }
    }
  ]
}

Unlike the Unify V1 envelope, the Unify V2 bulk format does not use shared defaults. Repeat the effective country, environment, source, document type, and payload in every invoices[] item. See Examples for complete single and bulk request bodies.

Next steps

• Examples — request, debug, and XML-decoding examples.
• Responses and Errors — status codes and structured validation findings.
• Migrate from Unify V1 — field mapping, before-and-after requests, and rollout checklist.
• Field Mapping Reference — country-specific payload guidance.
• Unify V1 Integration Guide — retained for existing integrations.