Unify V2 Examples

These examples show both supported Unify V2 request formats: a direct single document and one or more self-contained documents in an invoices array. Every request must include new-api: true as an HTTP header.

The fields inside payload are source-mapping specific. Replace the example payload with the structure configured for your integration.

API key requirement

You need a valid Complyance API key for the workspace and environment you want to use. Send it as Authorization: Bearer <YOUR_API_KEY>, together with Content-Type: application/json and the new-api: true header.

Choose the purpose

The request bodies below use "purpose": "mapping" to process documents through the Integration Engine. Use "purpose": "invoicing" instead when sending documents through the invoicing workflow. For bulk requests, set the appropriate purpose in every invoices[] item.

Submit one document

Send the document controls and payload directly at the request root:

{
  "country": "AE",
  "environment": "sandbox",
  "purpose": "mapping",
  "source": "AES:1",
  "documentType": {
    "base": "tax_invoice",
    "modifiers": []
  },
  "payload": {
    "documentType": {
      "base": "tax_invoice",
      "modifiers": []
    },
    "invoice_data": {
      "document_number": "TEST-REVAMP-1hFAJZB7WAtQ1Crt9ikvqzfQcVE2Di",
      "document_id": "INV-AE-SUM-1001",
      "unique_identifier": "08db0174-13dc-4c82-ad5f-e4e98d0804e9",
      "invoice_date": "2026-07-10",
      "invoice_time": null,
      "due_date": "2026-07-25",
      "currency_code": "AED",
      "invoice_period_start_date": "2026-07-01",
      "invoice_period_end_date": "2026-07-10",
      "invoice_period_frequency": "MONTHLY",
      "tax_exclusive_amount": 2190,
      "total_tax_amount": 109.5,
      "total_amount": 2299.5,
      "total_line_taxable_amount": 2200,
      "total_allowances": 20,
      "total_charges": 10,
      "amount_due": 2299.5,
      "reference_id": "REF-123123"
    },
    "seller_info": {
      "seller_name": "Acme LLC",
      "country_code": "AE",
      "city_name": "Dubai",
      "additional_address": "Trade Centre",
      "state_province": "DXB",
      "vat_number_type": "VAT",
      "vat_number": "100000000000003",
      "peppol_id": "1942929964",
      "peppol_id_scheme": "0235",
      "registration_type": "EID",
      "registration_number": "100000000000003"
    },
    "buyer_info": {
      "buyer_name": "Buyer LLC",
      "buyer_country": "AE",
      "buyer_additional_address": "Corniche Road",
      "buyer_city": "Abu Dhabi",
      "buyer_state_province": "AUH",
      "buyer_vat_type": "VAT",
      "buyer_vat_number": "100000000000103",
      "buyer_peppol_id": "1669481660",
      "peppol_id_scheme": "0235",
      "buyer_registration_type": "EID",
      "buyer_registration_number": "100000000000103"
    },
    "line_items": [
      {
        "line_id": "1",
        "item_name": "Electronic equipment",
        "item_description": "Electronic equipment included in the summary billing period",
        "quantity": 1,
        "unit_code": "PCE",
        "line_total": 2310,
        "line_taxable_value": 2200,
        "tax_category": "S",
        "net_price": 2250,
        "gross_price": 2250,
        "price_allowance": 0,
        "base_quantity": 1,
        "tax_rate": 5,
        "line_vat": 110,
        "item_type": "GOODS",
        "classification_code": "847130",
        "classification_scheme": "HS",
        "adjustments": [
          {
            "adjustment_id": "LINE-DISCOUNT-1",
            "is_charge": false,
            "reason": "Discount",
            "reason_code": "discount",
            "amount": 100,
            "base_amount": 2000,
            "percent": 5,
            "tax_category": "S",
            "tax_rate": 5
          },
          {
            "adjustment_id": "LINE-CHARGE-1",
            "is_charge": true,
            "reason": "Advertising",
            "reason_code": "advertising",
            "amount": 50,
            "base_amount": 1000,
            "percent": 5,
            "tax_category": "S",
            "tax_rate": 5
          }
        ]
      }
    ],
    "invoice_adjustments": [
      {
        "adjustment_id": "INVOICE-DISCOUNT-1",
        "is_charge": false,
        "reason": "Invoice discount",
        "reason_code": "discount",
        "amount": 20,
        "base_amount": 2000,
        "percent": 1,
        "tax_category": "S",
        "tax_rate": 5
      },
      {
        "adjustment_id": "INVOICE-CHARGE-1",
        "is_charge": true,
        "reason": "Freight service",
        "reason_code": "freight_service",
        "amount": 10,
        "base_amount": 1000,
        "percent": 1,
        "tax_category": "S",
        "tax_rate": 5
      }
    ],
    "supporting_documents": [
      {
        "document_id": "SUPPORT-001",
        "document_type": "contract",
        "document_description": "Customer contract supporting this invoice",
        "issue_date": "2026-07-01",
        "reference_url": "https://example.com/documents/SUPPORT-001"
      },
      {
        "document_id": "SUPPORT-002",
        "document_type": "delivery_note",
        "document_description": "Delivery note supporting this invoice",
        "issue_date": "2026-07-10",
        "attachments": [
          {
            "description": "Delivery note PDF",
            "filename": "delivery-note.pdf",
            "mime_code": "application/pdf",
            "content": "JVBERi0xLjQKJUVPRgo="
          }
        ]
      }
    ],
    "delivery": {
      "address_line_1": "Corniche Road",
      "city": "Abu Dhabi",
      "country_subdivision": "AUH",
      "country": "AE"
    },
    "payment_info": {
      "payment_means_code": "IN_CASH"
    },
    "additional_data": {
      "delivery_terms": [
        {
          "incoterms": "CIF"
        }
      ]
    }
  }
}

Submit documents in bulk

For bulk processing, wrap the same self-contained document object in an invoices array. Add more complete document objects to the array when submitting additional invoices.

{
  "invoices": [
    {
      "country": "AE",
      "environment": "sandbox",
      "purpose": "mapping",
      "source": "AES:1",
      "documentType": {
        "base": "tax_invoice",
        "modifiers": []
      },
      "payload": {
        "documentType": {
          "base": "tax_invoice",
          "modifiers": []
        },
        "invoice_data": {
          "document_number": "TEST-REVAMP-1hFAJZB7WAtQ1Crt9ikvqzfQcVE2Di",
          "document_id": "INV-AE-SUM-1001",
          "unique_identifier": "08db0174-13dc-4c82-ad5f-e4e98d0804e9",
          "invoice_date": "2026-07-10",
          "invoice_time": null,
          "due_date": "2026-07-25",
          "currency_code": "AED",
          "invoice_period_start_date": "2026-07-01",
          "invoice_period_end_date": "2026-07-10",
          "invoice_period_frequency": "MONTHLY",
          "tax_exclusive_amount": 2190,
          "total_tax_amount": 109.5,
          "total_amount": 2299.5,
          "total_line_taxable_amount": 2200,
          "total_allowances": 20,
          "total_charges": 10,
          "amount_due": 2299.5,
          "reference_id": "REF-123123"
        },
        "seller_info": {
          "seller_name": "Acme LLC",
          "country_code": "AE",
          "city_name": "Dubai",
          "additional_address": "Trade Centre",
          "state_province": "DXB",
          "vat_number_type": "VAT",
          "vat_number": "100000000000003",
          "peppol_id": "1942929964",
          "peppol_id_scheme": "0235",
          "registration_type": "EID",
          "registration_number": "100000000000003"
        },
        "buyer_info": {
          "buyer_name": "Buyer LLC",
          "buyer_country": "AE",
          "buyer_additional_address": "Corniche Road",
          "buyer_city": "Abu Dhabi",
          "buyer_state_province": "AUH",
          "buyer_vat_type": "VAT",
          "buyer_vat_number": "100000000000103",
          "buyer_peppol_id": "1669481660",
          "peppol_id_scheme": "0235",
          "buyer_registration_type": "EID",
          "buyer_registration_number": "100000000000103"
        },
        "line_items": [
          {
            "line_id": "1",
            "item_name": "Electronic equipment",
            "item_description": "Electronic equipment included in the summary billing period",
            "quantity": 1,
            "unit_code": "PCE",
            "line_total": 2310,
            "line_taxable_value": 2200,
            "tax_category": "S",
            "net_price": 2250,
            "gross_price": 2250,
            "price_allowance": 0,
            "base_quantity": 1,
            "tax_rate": 5,
            "line_vat": 110,
            "item_type": "GOODS",
            "classification_code": "847130",
            "classification_scheme": "HS",
            "adjustments": [
              {
                "adjustment_id": "LINE-DISCOUNT-1",
                "is_charge": false,
                "reason": "Discount",
                "reason_code": "discount",
                "amount": 100,
                "base_amount": 2000,
                "percent": 5,
                "tax_category": "S",
                "tax_rate": 5
              },
              {
                "adjustment_id": "LINE-CHARGE-1",
                "is_charge": true,
                "reason": "Advertising",
                "reason_code": "advertising",
                "amount": 50,
                "base_amount": 1000,
                "percent": 5,
                "tax_category": "S",
                "tax_rate": 5
              }
            ]
          }
        ],
        "invoice_adjustments": [
          {
            "adjustment_id": "INVOICE-DISCOUNT-1",
            "is_charge": false,
            "reason": "Invoice discount",
            "reason_code": "discount",
            "amount": 20,
            "base_amount": 2000,
            "percent": 1,
            "tax_category": "S",
            "tax_rate": 5
          },
          {
            "adjustment_id": "INVOICE-CHARGE-1",
            "is_charge": true,
            "reason": "Freight service",
            "reason_code": "freight_service",
            "amount": 10,
            "base_amount": 1000,
            "percent": 1,
            "tax_category": "S",
            "tax_rate": 5
          }
        ],
        "supporting_documents": [
          {
            "document_id": "SUPPORT-001",
            "document_type": "contract",
            "document_description": "Customer contract supporting this invoice",
            "issue_date": "2026-07-01",
            "reference_url": "https://example.com/documents/SUPPORT-001"
          },
          {
            "document_id": "SUPPORT-002",
            "document_type": "delivery_note",
            "document_description": "Delivery note supporting this invoice",
            "issue_date": "2026-07-10",
            "attachments": [
              {
                "description": "Delivery note PDF",
                "filename": "delivery-note.pdf",
                "mime_code": "application/pdf",
                "content": "JVBERi0xLjQKJUVPRgo="
              }
            ]
          }
        ],
        "delivery": {
          "address_line_1": "Corniche Road",
          "city": "Abu Dhabi",
          "country_subdivision": "AUH",
          "country": "AE"
        },
        "payment_info": {
          "payment_means_code": "IN_CASH"
        },
        "additional_data": {
          "delivery_terms": [
            {
              "incoterms": "CIF"
            }
          ]
        }
      }
    }
  ]
}

The single and bulk examples use the same invoice fields. The bulk format adds only the invoices wrapper and does not use shared defaults. Neither standard request includes debug or uae_extensions.

Successful single-document response

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

Store documentId with the invoice record in your system. Use the HTTP status as the programmatic success indicator.

Request debug diagnostics

Add debug: true to the document object while testing or troubleshooting. For a single request, that object is the request root; for bulk, it is the relevant invoices[] item:

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

When supported, the result includes diagnostics similar to:

{
  "requestId": "01KZZCSZ8JS9WX3ZZ2M6MEVPKR",
  "timings": {
    "mappingResolutionMs": 12,
    "getsConversionMs": 7,
    "getsValidationMs": 15,
    "xmlGenerationMs": 20,
    "xmlValidationMs": 18,
    "totalMs": 95
  },
  "integrationMapping": {
    "cacheHit": true
  }
}

Timing values are in milliseconds. Diagnostic fields may evolve; do not use their exact shape or values to make document-processing decisions.

Submit a credit note

Change documentType to a value supported by your source mapping and country rules:

{
  "country": "AE",
  "environment": "sandbox",
  "purpose": "mapping",
  "source": "AES:1",
  "documentType": {
    "base": "credit_note",
    "modifiers": []
  },
  "payload": {
    "credit_note_data": {
      "document_number": "CN-AE-1001",
      "reference_invoice": "INV-AE-1001"
    }
  }
}

The payload shape above is illustrative. Use the fields defined by your source mapping.

Common request mistakes

Missing API selector

Without this header, the request is routed to Unify V1:

new-api: true

Putting the selector in the body

The following does not select the new contract:

{
  "new-api": true
}

Mixing single and bulk formats

Do not put document fields beside invoices at the request root. Choose one format:

for a single request, put country, environment, source, documentType, and payload at the root;
for a bulk request, put only the invoices wrapper at the root and repeat those fields inside every item.

The Unify V2 bulk format supports invoices, but it does not use the Unify V1 defaults, action, or options fields.