Back to API Docs

API Reference

Complete reference for all Invoice Navigator API endpoints.

Base URL: https://api.invoicenavigator.eu/api
Auth: Bearer token in Authorization header
Format: JSON request/response

Quick Links

Composite Endpoint (Recommended)Granular: ValidationEvidence PacksGranular: Remediation EngineFormat ConversionCompliance DataIntelligence

Composite Endpoint (Recommended)

POST/v2/validate-and-fix
Starter+

Validate, remediate via hybrid pipeline, revalidate, and generate evidence — all in one call. Full flow tracking with HATEOAS links.

View documentation

Granular: Validation

POST/v1/validate
Starter+

Validate a single invoice XML against EN16931 and country-specific rules.

View documentation
POST/v1/validate/batch
Business+

Validate multiple invoices in a single request (up to 100).

View documentation

Evidence Packs

POST/v1/evidence-pack
Starter+

Generate a cryptographically signed Evidence Pack for a validated invoice.

POST/v1/evidence-pack/batch
Business+

Generate Evidence Packs for multiple validations in a single request.

GET/v1/evidence-packs
Starter+

List all Evidence Packs for your workspace with pagination.

GET/v1/evidence-pack/{id}
Starter+

Get Evidence Pack details including metadata and verification status.

GET/v1/evidence-pack/{id}/download
Starter+

Download the Evidence Pack PDF certificate.

GET/v1/verify/{id}
Public

Verify the authenticity of an Evidence Pack by its ID (public endpoint).

Granular: Remediation Engine

POST/v1/fixer/categorize
Starter+

Categorize validation errors by remediation type (auto, input-required, blocked).

View documentation
POST/v1/fixer/fix
Starter+

Apply controlled auto-remediation to an invoice. Returns remediated XML and change log.

View documentation
POST/v1/fixer/fix-with-input
Starter+

Apply remediations that require user-provided values (seller name, dates, etc.).

View documentation
POST/v1/fixer/evidence-pack
Starter+

Generate an Evidence Pack ZIP for a completed remediation.

View documentation
GET/v1/fixer/evidence-pack/{id}
Starter+

Retrieve Evidence Pack metadata by ID.

View documentation
GET/v1/fixer/usage
Starter+

Get current usage and quota for the billing period.

View documentation

Format Conversion

POST/v1/convert
Starter+

Convert invoices between formats (UBL, CII, XRechnung, Factur-X, Peppol BIS).

Compliance Data

GET/v1/countries
Starter+

List all EU countries with their e-invoicing status and requirements.

GET/v1/countries/{code}
Starter+

Get detailed compliance information for a specific country.

GET/v1/rules/{country}
Public

Get validation rules and CIUS requirements for a country.

GET/v1/deadlines
Public

Get upcoming compliance deadlines across all EU countries.

GET/v1/requirements
Starter+

Get trade lane requirements (what format to use for a seller/buyer combination).

GET/v1/changes
Business+

Get regulatory changes since a given date. Supports filtering by country and type.

GET/v1/rules/upcoming
Public

Get upcoming rule changes and deprecations with effective dates.

Intelligence

GET/v1/errors
Starter+

List all error codes with explanations and remediation suggestions.

GET/v1/errors/{ruleId}
Starter+

Get detailed information about a specific error code.

POST/v1/compliance-score
Business+

Calculate a compliance readiness score for a business.

GET/v1/facts/{country}
Public

Get regulatory facts and citations for a country (for AI/RAG use cases).

GET/v1/facts/search
Public

Search regulatory facts by keyword.

Authentication

All API requests (except public endpoints) require authentication via API key.

curl -X POST https://api.invoicenavigator.eu/api/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xml": "<Invoice>...</Invoice>"}'
Learn more about authentication

POST /v2/validate-and-fix

Recommended for most integrations

One call to validate, remediate, revalidate, and generate audit evidence. Runs the full hybrid pipeline with quota tracking and HATEOAS links for follow-up actions.

POST/v2/validate-and-fix

Request Body

{
  "xml": "<Invoice xmlns=\"urn:oasis:...\">..</Invoice>",
  "fileName": "INV-2026-0847.xml",
  "remediation_policy": "safe",
  "generate_evidence_pack": true
}

Parameters

  • xml (required) — Invoice XML string (UBL or CII)
  • fileName — Original filename for audit trail
  • remediation_policy — "safe" (default) or "none" (validate only, no fixes)
  • generate_evidence_pack — Generate evidence pack inline (default: false)
  • autoFix — Alias: false is equivalent to remediation_policy: "none"

Response

{
  "success": true,
  "data": {
    "validationRef": "VAL-1740744832000-8F2A3B",
    "originalValid": false,
    "fixedValid": true,
    "engine": "hybrid",
    "fixesApplied": 2,
    "fixSummary": {
      "totalIssues": 3,
      "autoFixable": 2,
      "needsInput": 1,
      "blocked": 0,
      "canAutoFixAll": false
    },
    "remainingIssues": [],
    "metadata": {
      "invoiceNumber": "INV-2026-001",
      "currency": "EUR",
      "totalAmount": "1250.00"
    },
    "flowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "evidencePackUrl": "/api/v1/evidence-pack?validationRef=VAL-1740744832000-8F2A3B",
    "_links": {
      "self": "/api/v2/validate-and-fix",
      "fixWithInput": "/api/v1/fixer/fix-with-input?flow_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "evidencePack": "/api/v1/evidence-pack?validationRef=VAL-1740744832000-8F2A3B"
    }
  },
  "_meta": {
    "validationRef": "VAL-1740744832000-8F2A3B",
    "processingTimeMs": 187
  }
}

Response Fields

  • originalValid — Whether the invoice passed validation before remediation
  • fixedValid — Whether the invoice passes after remediation (only present when fixes were attempted)
  • engine — Which remediation engine was used: "orchestrator", "safe-fixer", or "hybrid"
  • fixSummary — Breakdown of issues by fix type (auto, input-required, blocked)
  • flowId — Flow tracking ID for follow-up calls (e.g. fix-with-input)
  • _links — HATEOAS links for next actions

Request & Response Format

Request Format

All endpoints accept Content-Type: application/json. Invoice XML is sent as a string in the "xml" field of the JSON body — not as raw XML.

POST /api/v1/validate HTTP/1.1
Host: api.invoicenavigator.eu
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "xml": "<Invoice xmlns=\"urn:oasis:...\">..</Invoice>"
}

Common mistake: Do not send raw XML with Content-Type: application/xml. The API expects JSON with the XML content as a string value.

Response Envelope

All API responses use a consistent envelope structure. The success field indicates the outcome, and metadata is always available in _meta.

Success response

{
  "success": true,
  "data": { ... },
  "_meta": {
    "processingTimeMs": 187,
    "validationRef": "VAL-..."
  }
}

Error response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Check the success field to determine whether the request succeeded. Error codes are documented in the Authentication and individual endpoint sections.

Endpoint Details

Detailed request/response documentation for key endpoints.

POST/v1/evidence-pack/batchBusiness+

Generate multiple Evidence Packs as a ZIP bundle. Useful for batch compliance certification.

Request Body

{
  "validationRefs": ["VAL-1740744832000-ABC123", "VAL-1740744832000-DEF456", "VAL-1740744832000-GHI789"]
}

Response

{
  "success": true,
  "data": {
    "downloadUrl": "https://api.invoicenavigator.eu/downloads/batch_xyz.zip",
    "expiresAt": "2026-01-10T00:00:00Z",
    "count": 3
  }
}
GET/v1/evidence-pack/{id}Starter+

Retrieve Evidence Pack metadata including verification URLs and expiration dates.

Response

{
  "success": true,
  "data": {
    "evidencePackId": "EP-REF-XYZ789",
    "validationRef": "VAL-1740744832000-ABC123",
    "createdAt": "2026-01-09T12:00:00Z",
    "expiresAt": "2027-01-09T12:00:00Z",
    "downloadUrl": "https://api.invoicenavigator.eu/api/v1/evidence-pack/EP-REF-XYZ789/download",
    "verifyUrl": "https://www.invoicenavigator.eu/verify/EP-REF-XYZ789",
    "invoiceMetadata": {
      "invoiceNumber": "INV-2026-000142"
    },
    "isValid": true
  }
}
GET/v1/evidence-pack/{id}/downloadStarter+

Download the Evidence Pack as a signed PDF certificate.

Response

Content-Type: application/pdf
Content-Disposition: attachment; filename="evidence-pack-EP-REF-XYZ789.pdf"

[Binary PDF data]
GET/v1/evidence-packsStarter+

List all Evidence Packs for your workspace with pagination and date filtering.

Query Parameters

  • page - Page number (default: 1)
  • limit - Items per page (default: 20, max: 100)
  • from - Filter from date (ISO 8601)
  • to - Filter to date (ISO 8601)

Response

{
  "success": true,
  "data": {
    "evidencePacks": [
      {
        "evidencePackId": "EP-REF-XYZ789",
        "validationRef": "VAL-1740744832000-ABC123",
        "createdAt": "2026-01-09T12:00:00Z",
        "invoiceMetadata": {
          "invoiceNumber": "INV-2026-000142"
        },
        "isValid": true
      }
    ],
    "total": 156,
    "page": 1,
    "limit": 20
  }
}
GET/v1/rules/upcomingPublic

Get upcoming ruleset changes and deprecations. Useful for planning system updates.

Response

{
  "success": true,
  "data": {
    "upcoming": [
      {
        "ruleset": "xrechnung",
        "currentVersion": "3.0.2",
        "upcomingVersion": "3.0.3",
        "expectedDate": "2026-04-01",
        "breakingChanges": false,
        "changelog": "Minor bug fixes and clarifications"
      }
    ],
    "deprecations": [
      {
        "ruleset": "peppol-bis",
        "version": "3.0.15",
        "deprecationDate": "2026-03-01",
        "replacementVersion": "3.0.17"
      }
    ]
  }
}

Remediation Engine

Starter+

Controlled auto-remediation for e-invoice validation errors. The engine categorizes errors, applies safe fixes with financial field blocking, and generates cryptographic evidence at every step. Included on all paid plans.

5-Minute Integration

Use /v2/validate-and-fix for the full pipeline in one call, or follow these granular steps:

  1. 1Validate — Run invoice against 1,300+ rules
  2. 2Categorize — Classify errors as auto-fixable, input-required, or blocked
  3. 3Remediate — Apply controlled fixes with financial field blocking
  4. 4Evidence Pack — Generate cryptographic audit trail
  5. 5Monitor — Track quota and usage

Most pipeline integrations only need steps 1-3.

POST/v1/fixer/categorize

Categorize validation errors by remediation type: auto (safe to remediate automatically), input (needs user-provided data), or blocked (financial fields that cannot be changed).

Request

{
  "error_codes": ["BR-CO-10", "BR-16", "BR-S-08"]
}

Response

{
  "success": true,
  "data": {
    "categorized": {
      "auto": ["BR-CO-10"],
      "input": ["BR-16"],
      "blocked": ["BR-S-08"]
    },
    "stats": {
      "auto": 1,
      "input": 1,
      "blocked": 1
    }
  },
  "_meta": {
    "duration_ms": 45
  }
}
POST/v1/fixer/fix

Apply controlled auto-remediation to an invoice. Financial fields are blocked by default. Returns the remediated XML and a detailed change log.

Request

{
  "xml": "<Invoice xmlns=\"urn:oasis:...\">..</Invoice>",
  "error_codes": ["BR-CO-10", "BR-16"]
}

Response

{
  "success": true,
  "data": {
    "fixed_xml": "<Invoice>...</Invoice>",
    "applied_fixes": [
      {
        "error_code": "BR-CO-10",
        "success": true,
        "operation": "recalculate",
        "target_xpath": "/Invoice/TaxTotal/TaxAmount",
        "before_value": "100.00",
        "after_value": "119.00",
        "confidence": 1.0
      }
    ],
    "failed_fixes": [],
    "remaining_errors": {
      "needsInput": [
        {
          "error_code": "BR-16",
          "reason": "Seller name cannot be derived"
        }
      ],
      "blocked": [],
      "unknown": []
    },
    "is_compliant": false,
    "is_billable": true
  },
  "_meta": {
    "flow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "duration_ms": 245
  }
}
POST/v1/fixer/fix-with-input

Apply remediations that require user-provided values. Must be called with an existing flow_id from the /fix endpoint.

Request

{
  "xml": "<Invoice>...</Invoice>",
  "values": {
    "seller_name": "ACME Corporation GmbH"
  },
  "skipped": ["BR-17"],
  "error_codes": ["BR-16"],
  "flow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response

{
  "success": true,
  "data": {
    "fixed_xml": "<Invoice>...</Invoice>",
    "applied_fixes": [...],
    "failed_fixes": [],
    "remaining_errors": ["BR-17"],
    "stats": {
      "applied": 1,
      "failed": 0,
      "skipped": 1
    },
    "is_compliant": false,
    "is_billable": true
  },
  "_meta": {
    "flow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "duration_ms": 120
  }
}
POST/v1/fixer/evidence-pack

Generate an Evidence Pack for a completed remediation. Returns a ZIP containing original XML, remediated XML, change report, validation results, and cryptographic metadata.

Request

{
  "original_xml": "<Invoice>...</Invoice>",
  "fixed_xml": "<Invoice>...</Invoice>",
  "file_name": "invoice-2024-001.xml",
  "applied_fixes": [...],
  "remaining_errors": [...],
  "validation_before": {...},
  "validation_after": {...},
  "flow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response

Content-Type: application/zip
Content-Disposition: attachment; filename="evidence-pack-EP-REF-XYZ.zip"
X-Pack-ID: EP-REF-XYZ789

[ZIP containing: original_invoice.xml, fixed_invoice.xml,
 change_report.txt, metadata.json, validation_before.json,
 validation_after.json, change_events.json]
GET/v1/fixer/evidence-pack/{id}

Retrieve Evidence Pack metadata by ID.

Response

{
  "success": true,
  "data": {
    "pack_id": "EP-REF-XYZ789",
    "created_at": "2026-01-15T12:00:00Z",
    "original_filename": "invoice-2024-001.xml",
    "original_hash": "sha256:abc123...",
    "fixed_hash": "sha256:def456...",
    "detected_format": "ubl",
    "fixes_applied": 3,
    "fixes_user_input": 1,
    "fixes_skipped": 0,
    "final_status": "compliant"
  }
}
GET/v1/fixer/usage

Get your current usage and quota for the billing period.

Response

{
  "success": true,
  "data": {
    "period": {
      "start": "2026-01-01T00:00:00Z",
      "end": "2026-02-01T00:00:00Z"
    },
    "usage": {
      "flows_used": 42,
      "flows_limit": 100,
      "flows_remaining": 58,
      "percentage": 42
    },
    "subscription": {
      "tier": "pro",
      "status": "active",
      "plan_name": "Pro",
      "evidence_pack": "full"
    },
    "tier": "pro",
    "resets_at": "2026-02-01T00:00:00Z"
  }
}

Authentication

All Remediation endpoints require a Bearer token in the Authorization header:

curl -X POST https://api.invoicenavigator.eu/api/v1/fixer/fix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"xml": "...", "error_codes": ["BR-CO-10"]}'

Getting your API key: Sign up for any plan, navigate to Dashboard → API, and generate your key instantly.

Response Codes

CodeMeaning
200Success
400Invalid XML or missing required fields
401Missing or invalid API key
402Quota exceeded (upgrade plan or wait for reset)
403Feature not available for your tier
422No fixable errors found in provided error_codes
429Rate limit exceeded
500Internal server error

Rate Limits

PlanMonthly invoicesOverage
Free Trial100 total (lifetime)Upgrade required
Starter1,000€50 per 1,000
Pro5,000€50 per 1,000
Scale25,000€50 per 1,000

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in all API responses. Free trial quota does not reset — it is a lifetime total of 100 invoices.

Ready to integrate?

Start with 100 free invoices — full engine access, no credit card required. Production plans from €249/mo.

Get API Access