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: Auto-Fix EngineFormat ConversionCompliance DataIntelligence

Composite Endpoint (Recommended)

POST/v2/validate-and-fix
All Plans

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

View documentation

Granular: Validation

POST/v1/validate
All Plans

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

View documentation
POST/v1/validate/batch
All Plans

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

View documentation

Evidence Packs

POST/v1/evidence-pack
All Plans

Generate a cryptographically signed Evidence Pack for a validated invoice.

POST/v1/evidence-pack/batch
All Plans

Generate Evidence Packs for multiple validations in a single request.

GET/v1/evidence-packs
All Plans

List all Evidence Packs for your workspace with pagination.

GET/v1/evidence-pack/{id}
All Plans

Get Evidence Pack details including metadata and verification status.

GET/v1/evidence-pack/{id}/download
All Plans

Download the Evidence Pack PDF certificate.

GET/v1/verify/{id}
Public

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

Granular: Auto-Fix Engine

POST/v1/fixer/categorize
All Plans

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

View documentation
POST/v1/fixer/fix
All Plans

Apply controlled auto-fix to an invoice. Returns fixed XML and change log.

View documentation
POST/v1/fixer/fix-with-input
All Plans

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

View documentation
POST/v1/fixer/evidence-pack
All Plans

Generate an Evidence Pack ZIP for a completed fix.

View documentation
GET/v1/fixer/evidence-pack/{id}
All Plans

Retrieve Evidence Pack metadata by ID.

View documentation
GET/v1/fixer/usage
All Plans

Get current usage and quota for the billing period.

View documentation

Format Conversion

POST/v1/convert
All Plans

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

Compliance Data

GET/v1/countries
All Plans

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

GET/v1/countries/{code}
All Plans

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
All Plans

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

GET/v1/changes
All Plans

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
All Plans

List all error codes with explanations and fix suggestions.

GET/v1/errors/{ruleId}
All Plans

Get detailed information about a specific error code.

POST/v1/compliance-score
All Plans

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, auto-fix, 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 auto-fix
  • fixedValid — Whether the invoice passes after auto-fix (only present when fixes were attempted)
  • engine — Which 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}All Plans

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}/downloadAll Plans

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-packsAll Plans

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"
      }
    ]
  }
}

Auto-Fix Engine

All Plans

Controlled auto-fix for e-invoice validation errors. The engine categorizes errors, applies fixes with financial field blocking, and generates cryptographic evidence at every step. Available on all 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. 3Auto-Fix — 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 fix type: auto (safe to fix 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-fix to an invoice. Financial fields are blocked by default. Returns the fixed 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 fixes 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 fix. Returns a ZIP containing original XML, fixed 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

Endpoint Access by Plan

All endpoints are available on both Free and Pro. The difference is volume and data retention.

EndpointFreePro
POST /v1/validate✓✓
POST /v2/validate-and-fix✓✓
POST /v1/fixer/fix✓✓
POST /v1/fixer/fix-with-input✓✓
POST /v1/convert✓✓
GET /v1/countries✓✓
GET /v1/requirements✓✓
POST /v1/evidence-pack✓✓
POST /v1/validate/batch✓✓
POST /v1/compliance-score✓✓
GET /v1/changes✓✓

Public endpoints (rules, deadlines, facts, verify, errors) are available without authentication.

Rate Limits & Quotas

PlanRequests/hourMonthly quotaOverage
Free60500/monthHard cap
Pro1,00010,000/month€10 per 1,000
Test mode (sk_test_)100No quota consumed—

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in all API responses.

Ready to integrate?

Start with 500 free invoices/month — full engine access, no credit card required. Pro from €99/mo.

Get API Access