Validation Runs Guide

Use VAT validation runs when you need to validate one or more records and compare company master data such as name, street, postal code, and city.

Synchronous Or Asynchronous

Both create endpoints start the same validation workflow and return the same response shape. The difference is how long the first HTTP request waits.

Use	Endpoint	Best for
Synchronous validation	POST /api/v1/integration/vat/validations	Small batches where the client can keep the HTTP request open until validation finishes.
Asynchronous validation	POST /api/v1/integration/vat/validations/async	Larger batches, automated imports, client timeouts, retry-safe jobs, and PDF-producing workflows.

For most production integrations, prefer the asynchronous endpoint. It avoids long-running HTTP requests and gives the client a clear polling flow.

Processing time depends on external authorities

Each VAT ID validation is performed in real time via the respective responsible authorities of the EU member states. Response times may therefore vary significantly depending on the member state, the availability of external systems, and the current system load.

Based on our experience, the typical processing time outside peak periods is approximately 3-5 seconds per VAT ID. When validating multiple VAT IDs, the total processing time may add up accordingly. For example, validating 20 VAT IDs may take approximately 1 to 3 minutes, depending on the response times of the external systems.

Asynchronous Flow

When the asynchronous endpoint accepts a run that is still processing, it returns:

• HTTP 202 Accepted
• status: "Running"
• operationId
• Retry-After
• Cache-Control: no-store
• Location pointing to the operation status endpoint

Store the operationId, then poll:

GET /api/v1/integration/vat/validations/{operationId}

Wait at least the number of seconds from Retry-After before polling again.

If your system stores the idempotency key more naturally than the operation ID, you can also retrieve the run with:

GET /api/v1/integration/vat/validations/by-idempotency-key/{idempotencyKey}

Request Records

Each record supports these first-class VAT fields:

• vatId
• companyName
• street
• zip
• city

Additional JSON properties are accepted as custom fields. Use them for your own row or document identifiers because a VAT ID is not always unique enough to map a result back to a source record.

{
  "records": [
    {
      "vatId": "DE284700631",
      "companyName": "Optimus Software GmbH",
      "street": "Tal 44",
      "zip": "80331",
      "city": "München",
      "sourceSystemReferenceId": "ERP-SUPPLIER-77821"
    }
  ],
  "options": {
    "checkType": "Qualified",
    "sendNotificationEmail": false,
    "createSnapshot": true,
    "retryDuration": "OneHour",
    "include": [
      "addressStreetName",
      "addressHouseNumber"
    ],
    "pdf": {
      "create": true,
      "sign": false,
      "sendByEmail": false,
      "returnAsBase64": false,
      "returnAsUrl": true
    }
  }
}

checkType is Standard or Qualified. retryDuration supports None, OneHour, TwoHours, FourHours, EightHours, and TwentyFourHours.

Use options.include when completed records should contain additional resolved VAT data. Supported values are addressStreetName and addressHouseNumber. They can help when your system stores street name and house number in separate fields while the normal validation field remains street.

Run Statuses

Status	Meaning
Running	The validation run is still processing. Poll again after Retry-After.
Completed	Validation finished and records contains per-record results.
Failed	The run failed before producing usable record results. Read error.

records is available only after the operation is Completed. For Running operations, records is omitted. For Failed operations, records can be omitted if the workflow failed before result data was produced.

Interpreting Record Results

Use each record's status for the VAT ID outcome:

Status	Meaning
Valid	The VAT ID resolved as valid.
Invalid	The VAT ID resolved as invalid.
Unavailable	The provider result was temporarily unavailable. Retry handling may be appropriate.

Use flags for extra context such as invalid syntax, fully verified data, invalid company/address fields, qualified verification, missing required data, or a non-eligible country.

Use companyName, street, zip, and city to compare submitted master data with the authoritative result:

Field property	Meaning
value	Original value submitted by the client.
matchStatus	Match, NoMatch, NotQueried, or NotReturned.
correctionValue	Authoritative or corrected value when available.

Use customFields to map the result back to your source system.

If options.include requested additional fields and the data could be resolved, each completed record can also contain included:

{
  "vatId": "DE284700631",
  "status": "Valid",
  "street": {
    "value": "Tal 44",
    "matchStatus": "Match"
  },
  "included": {
    "addressStreetName": "Tal",
    "addressHouseNumber": "44"
  }
}

PDF Results

Set options.pdf.create to true when you need a PDF report.

PDF delivery options are independent:

Option	Result
returnAsBase64: true	Embeds the base64 PDF in pdfDocument.base64.
returnAsUrl: true	Includes a download URL in pdfDocument.url.
sendByEmail: true	Sends the PDF through the validation workflow.
sign: true	Signs the generated PDF.

PDF delivery options require pdf.create: true. PDF signing also requires pdf.create: true.

When using URL delivery, download the file after the run is completed:

GET /api/v1/integration/vat/validations/{operationId}/pdf

If the run is still processing, the PDF endpoint returns 409 Conflict. If no PDF exists for the operation, it returns 404 Not Found.

Result Retention

The response includes expiresAt. Treat that timestamp as the latest point at which the operation data may still be retrievable.

Persist the fields you need in your own system after receiving a completed result, especially if you need long-term audit, ERP synchronization, or PDF archive data.

Recommended Production Pattern

For transaction-style checks with short client timeouts:

1. Generate and store an idempotency key.
2. Call POST /api/v1/integration/vat/validations/async.
3. Store operationId.
4. Poll GET /api/v1/integration/vat/validations/{operationId} using Retry-After.
5. On Completed, read records and persist the result per source row.
6. If PDF URL delivery was requested, store or download pdfDocument.url.

For small internal jobs where blocking is acceptable:

1. Generate and store an idempotency key.
2. Call POST /api/v1/integration/vat/validations.
3. Read records directly from the response when status is Completed.
4. If the request fails or times out, re-read by idempotency key.