Unify V2 Bulk Examples

These examples document the Unify V2 bulk request format and its per-item response envelope. Put every document in the root invoices array and 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 body below uses "purpose": "mapping" to process documents through the Integration Engine. Use "purpose": "invoicing" instead when sending documents through the invoicing workflow. Set the appropriate purpose in every invoices[] item.

Submit documents in bulk

For bulk processing, put each complete, self-contained document object in the invoices array. Add more document objects to the array when submitting additional invoices. Save the JSON body below as bulk-unify-request.json, then send it with:

curl --location 'https://prod.gets.complyance.io/api/v3/unify' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'new-api: true' \
  --data @bulk-unify-request.json

{
  "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 bulk request repeats the complete document controls and payload in every invoices[] item. It does not use shared defaults.

Bulk response envelope

Bulk requests return a summary for the complete batch and one result for each submitted item. Use results[].index to correlate a result with its zero-based position in the request's invoices array. Check results[].success for every item; receiving the batch envelope does not mean every item succeeded.

Successful bulk response

Each successful item has success: true and a result object. The result fields depend on the item's purpose. An invoicing item returns the persisted document ID and generated XML, while a mapping item returns the saved mapping payload ID:

{
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  },
  "results": [
    {
      "index": 0,
      "success": true,
      "result": {
        "documentId": "invoice-1",
        "message": "Your invoice was validated and is ready for submission.",
        "Base64XML": "PEludm9pY2UgLz4="
      }
    },
    {
      "index": 1,
      "success": true,
      "result": {
        "payloadId": "payload-2",
        "message": "Payload saved for mapping."
      }
    }
  ]
}

Store result.documentId for successful invoicing items. Use result.payloadId to identify successful mapping items.

Failed bulk item

If no integration mapping matches an item's source, country, and documentType, the response has this structure:

{
  "summary": {
    "total": 1,
    "succeeded": 0,
    "failed": 1
  },
  "results": [
    {
      "index": 0,
      "success": false,
      "error": {
        "code": "failed_precondition",
        "message": "No integration mapping matches the requested source, country, and document type"
      }
    }
  ]
}

Field	Description
`summary.total`	Number of items submitted in `invoices`.
`summary.succeeded`	Number of items processed successfully.
`summary.failed`	Number of items that failed.
`results`	Per-item outcomes for the batch.
`results[].index`	Zero-based position of the corresponding item in the request's `invoices` array.
`results[].success`	Whether that item was processed successfully.
`results[].result`	Successful item output. Its fields depend on the item's `purpose`.
`results[].error.code`	Machine-readable failure code for an unsuccessful item.
`results[].error.message`	Human-readable failure details. Do not compare this text to make workflow decisions.

In this example, verify that the integration mapping is configured for the exact source alias and version, country, and document type before resubmitting.

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
}

Putting document fields at the request root

For bulk requests, the root object contains only invoices. Put country, environment, purpose, source, documentType, and payload inside every invoices[] item. Do not place document fields beside the invoices array.

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