CII Validation PDF Report API Reference
Technical reference for the PDF report variant of CII validation. It runs the exact same checks as POST /v1/validate/cii, with the same profile detection and rule sets, but returns a printable PDF compliance report instead of a JSON body. The pass/fail verdict is returned in the X-Invoice-Valid response header, and the report downloads as a PDF named after your upload. One credit per call, the same as JSON validation.
https://api.invoicexml.com/v1/validate/cii/report
Code Example
curl -X POST https://api.invoicexml.com/v1/validate/cii/report \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "[email protected]" \ -D - \ -o invoice-report.pdf
-o saves the returned PDF to disk and -D - prints the response headers so you can read X-Invoice-Valid. The invoice profile and version are detected automatically from the uploaded file, exactly as on the JSON endpoint.
Request
| Parameter | Type | Description |
|---|---|---|
| file * | binary | The invoice file to validate. Accepted format: standalone CII XML document. PDFs are not accepted here; upload hybrid files to POST /v1/validate/facturx/report or /v1/validate/zugferd/report. |
Content-Type: multipart/form-data
That is the whole request. The syntax and the conformance profile (Peppol BIS, XRechnung, NLCIUS, PINT,
or the Factur-X/ZUGFeRD profile ladder) are detected automatically from the document's specification
identifier (BT-24), the matching rule set is applied, and the response reports what was validated against
in data.profile and data.customizationId.
Headers
| Header | Value |
|---|---|
| Authorization * | Bearer YOUR_API_KEY |
| Content-Type | multipart/form-data |
Response
200 PDF report
The response body is the PDF document itself, served as an attachment named invoice-report.pdf (derived from your upload's filename). The compliance verdict is returned in the X-Invoice-Valid response header as true or false, so you can branch on the outcome without opening the PDF. A completed validation always returns HTTP 200 and a PDF whether the invoice passed or failed; read X-Invoice-Valid to tell the two apart.
Content-Type: application/pdf Content-Disposition: attachment; filename="invoice-report.pdf" X-Invoice-Valid: true
Handling the PDF response
Read the verdict from the X-Invoice-Valid header and stream the body to a file. Do not parse the body as JSON on a 200 response, it is binary PDF.
C#
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");
using var form = new MultipartFormDataContent();
form.Add(new StreamContent(File.OpenRead("invoice.xml")), "file", "invoice.xml");
var response = await client.PostAsync("https://api.invoicexml.com/v1/validate/cii/report", form);
response.EnsureSuccessStatusCode();
var valid = response.Headers.TryGetValues("X-Invoice-Valid", out var values)
&& values.FirstOrDefault() == "true";
await using var pdf = File.Create("invoice-report.pdf");
await response.Content.CopyToAsync(pdf);
Console.WriteLine(valid ? "Invoice is compliant." : "Validation failed, see the PDF report.");
Node.js
const fs = require('fs');
const FormData = require('form-data');
const form = new FormData();
form.append('file', fs.createReadStream('invoice.xml'));
const response = await fetch('https://api.invoicexml.com/v1/validate/cii/report', {
method: 'POST',
headers: { 'Authorization': 'Bearer YOUR_API_KEY', ...form.getHeaders() },
body: form,
});
const valid = response.headers.get('x-invoice-valid') === 'true';
fs.writeFileSync('invoice-report.pdf', Buffer.from(await response.arrayBuffer()));
console.log(valid ? 'Invoice is compliant.' : 'Validation failed, see the PDF report.');
Error Reference
A completed validation always returns HTTP 200 with the PDF body. Transport-level problems never return a PDF: they come back as the standard RFC 7807 JSON problem response, the same shape and status codes as the JSON validation endpoint. Check the response status, or the Content-Type, before treating the body as a PDF.
| Status | Meaning | Action |
|---|---|---|
| 200 | Validation completed. The body is the PDF report. | Read X-Invoice-Valid for the pass/fail verdict. |
| 401 | Missing or invalid API key. | Check the Authorization header. |
| 422 | File is not a valid PDF or XML document. | Ensure you are uploading a supported file format. |
Need the findings as JSON?
The /v1/validate/cii endpoint runs the identical validation and returns every finding as structured JSON, with rule ids, layers, friendly messages, and field paths.
Frequently Asked Questions
How is POST /v1/validate/cii/report different from POST /v1/validate/cii?
The validation is identical: the same CII rule sets, the same profile detection, and the same one credit per call. Only the response differs. The /report endpoint returns a printable PDF compliance report (Content-Type application/pdf), while the base endpoint returns the findings as JSON. Use /report when you need a document to archive, print, or forward to a reviewer; use the JSON endpoint when your code needs to read individual findings.
How do I read the pass/fail result without opening the PDF?
The verdict is in the X-Invoice-Valid response header, set to true or false. A completed validation always returns HTTP 200 with a PDF body whether the invoice passed or failed, so branch on the header rather than the status code.
What is the PDF file named?
The report is served as an attachment (Content-Disposition: attachment) named after your upload, with a -report suffix and the .pdf extension. Uploading invoice.pdf or invoice.xml yields invoice-report.pdf.
What happens when the upload is invalid or missing?
Transport-level failures (a missing file, an unsupported file type, or malformed XML) do not produce a PDF. They return the same RFC 7807 JSON problem response and status code as the JSON endpoint, for example 401 for a missing or invalid API key or 422 for an unreadable upload. Check the response status or Content-Type before treating the body as a PDF.