Clearvo API Reference

Clearvo is a single API for all your global tax obligations — e-invoicing, tax calculations, tax number validation, and compliance monitoring across 100+ countries. One integration, one API key, every solution.

Which API are you building with?

E-Invoicing: how it works

You send one JSON payload to POST /invoices. Clearvo transforms it into the correct country format (FatturaPA, FA(3), XRechnung, etc.), submits it to the relevant authority, and returns a referenceId. You then poll GET /invoices/status or receive a webhook when the clearance status changes.

Authentication

Every request to the Clearvo API requires an API key passed in the x-api-key header. Keys are scoped to an organisation and environment (live vs. test).

x-api-key: ck_live_••••••••••••
x-idempotency-key: a3f9c2d1-e847-4b6a-9c12-d3f0e1a2b7c8
Content-Type: application/json

Quickstart

Submit your first invoice in under two minutes. This example sends an Italian B2B invoice to the SDI.

curl https://api.clearvo.io/v1/invoices \
  -X POST \
  -H "x-api-key: ck_live_••••••••••••" \
  -H "x-idempotency-key: a3f9c2d1-e847-4b6a-9c12-d3f0e1a2b7c8" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": "invoice",
    "invoiceNumber": "INV-2024-001",
    "issueDate": "2024-01-15",
    "currency": "EUR",
    "country": "IT",
    "supplier": {
      "name": "Acme SRL",
      "taxId": "01234567890",
      "taxIdCountry": "IT",
      "address": { "street": "Via Roma 1", "city": "Milano", "postalCode": "20121", "country": "IT" }
    },
    "buyer": {
      "name": "Cliente SpA",
      "taxId": "09876543210",
      "taxIdCountry": "IT",
      "address": { "street": "Via Veneto 10", "city": "Roma", "postalCode": "00187", "country": "IT" }
    },
    "lines": [
      { "description": "Software licence Q1", "quantity": 1, "unitPrice": 1000.00, "taxCode": "S" },
      { "description": "Support hours", "quantity": 8, "unitPrice": 125.00, "taxCode": "S" }
    ]
  }'

A successful response returns:

{
  "ok": true,
  "country": "IT",
  "referenceId": "IT-20240115-INV-001",
  "clearanceStatus": "PENDING",
  "terminal": false,
  "submittedAt": "2024-01-15T10:30:00Z",
  "nextPollAfter": "2024-01-15T10:35:00Z"
}

Store the referenceId — you'll use it to poll for the final clearance decision.

POST /invoices

Submit a new invoice for clearance. Clearvo validates the payload, generates the country-specific XML format, and forwards it to the relevant tax authority.

Node.js example

const response = await fetch('https://api.clearvo.io/v1/invoices', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.CLEARVO_API_KEY,
    'x-idempotency-key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    documentType: 'invoice',
    invoiceNumber: 'INV-2024-001',
    issueDate: '2024-01-15',
    currency: 'EUR',
    country: 'IT',
    supplier: {
      name: 'Acme SRL',
      taxId: '01234567890',
      taxIdCountry: 'IT',
      address: { street: 'Via Roma 1', city: 'Milano', postalCode: '20121', country: 'IT' },
    },
    buyer: {
      name: 'Cliente SpA',
      taxId: '09876543210',
      taxIdCountry: 'IT',
      address: { street: 'Via Veneto 10', city: 'Roma', postalCode: '00187', country: 'IT' },
    },
    lines: [
      { description: 'Software licence Q1', quantity: 1, unitPrice: 1000.00, taxCode: 'S' },
      { description: 'Support hours', quantity: 8, unitPrice: 125.00, taxCode: 'S' },
    ],
  }),
});

const invoice = await response.json();
console.log(invoice.referenceId); // "IT-20240115-INV-001"

Response fields

GET /invoices/status

Retrieve the current clearance status and full event history for a submitted invoice.

Query parameters

Polling loop (JavaScript)

async function waitForClearance(referenceId, country) {
  const MAX_POLLS = 48; // 4 hours at 5-min cadence
  let polls = 0;

  while (polls++ < MAX_POLLS) {
    const res = await fetch(
      `https://api.clearvo.io/v1/invoices/status?country=${country}&id=${referenceId}`,
      { headers: { 'x-api-key': process.env.CLEARVO_API_KEY } }
    );
    const data = await res.json();

    if (data.terminal) {
      return data; // ACCEPTED | REJECTED | DUPLICATE
    }

    // Honour nextPollAfter — don't hammer the API
    const wait = new Date(data.nextPollAfter) - Date.now();
    if (wait > 0) await new Promise(r => setTimeout(r, wait));
  }

  throw new Error('Max polls reached — check Italy UNDELIVERED / mcDeadline');
}

Status response fields

Clearance status values

GET /participants/lookup

Check whether a buyer is registered on the Peppol network and retrieve their AS4 endpoint. Results are served from cache when available. Pass forceRefresh=true to re-query the SML live.

Query parameters

Response

POST /invoices/{id}/deliver

Retry Peppol AS4 delivery for an invoice that is UNROUTABLE. Clearvo re-queries the SML (bypassing cache), and re-attempts delivery. On success the invoice moves to DELIVERED. On continued failure it stays UNROUTABLE and can be retried again.

Path parameter

Request body (optional)

Response

Error responses

Supported Countries

Clearvo supports 31 countries across Europe, APAC, and the Middle East. Pass the two-letter ISO code in the country field. Every listed country has a validated XML generator — no advisory-only entries.

Implementation Status

This table documents exactly what is built and live for each jurisdiction, and what remains outstanding. It is intended for technical evaluation — use it to understand what Clearvo handles end-to-end versus what requires additional setup on your side.

Built = generator + authority client + tests exist. ⚠️ Partial = generator exists; live submission needs additional credentials/config. 🔜 Planned = roadmap item; mandate not yet live or approach being finalised.

Request body

All fields are sent as a flat JSON object to POST /invoices. Fields marked Required must be present; Optional fields are silently ignored if absent.

Party object

Used for both supplier and buyer.

{
  "name": "Acme SRL",
  "taxId": "01234567890",
  "taxIdCountry": "IT",
  "address": {
    "street": "Via Roma 1",
    "city": "Milano",
    "postalCode": "20121",
    "country": "IT"
  }
}

Line items

Each entry in the lines array describes one invoiced item. Amounts are net (excluding VAT). Clearvo computes VAT amounts from the taxCode and the country's current rate table.

Tax codes

Tax codes follow the EN16931 VAT category framework. Clearvo maps each code to the correct authority-specific code in the generated XML. Always use the code that describes the legal reason for the rate, not just the rate percentage.

Payment object

Optional payment details embedded in the invoice. Included in the generated XML where the authority format supports it (FatturaPA, UBL, XRechnung).

Country-specific fields

Some countries require additional fields that have no EN16931 equivalent. These are passed as a countryData object alongside the standard payload.

Italy

Germany

Poland

Poland requires a per-entity KSeF API token registered once via POST /api/einvoicing/v1/pl/credentials (or the setup page). See the Poland guide for full details.

HTTP errors

Clearvo uses standard HTTP status codes. All error responses include a JSON body with ok: false.

Clearance errors

These are not HTTP errors — the initial POST /invoices returns 200, but a subsequent status poll may reveal that the authority rejected the invoice. Check clearanceStatus === "REJECTED" and inspect the error block.

Common authority rejection reasons by country:

Italy (SDI)

• 00001 — Invalid file structure (XML schema violation).
• 00002 — Duplicate invoice number from the same sender.
• 00102 — Supplier Partita IVA not found in Revenue Agency registry.
• 00201 — Buyer Codice Destinatario or PEC not found or inactive.

Poland (KSeF)

• InvalidNip — NIP number checksum invalid.
• DuplicateInvoice — Invoice FA number already submitted in this session.
• SchemaValidationError — FA(3) schema violation; check error.detail for XPath.

Germany (XRechnung)

Germany has no central clearance authority for B2B. Clearance is immediate on valid XML. Peppol-based rejections from the recipient's Access Point appear as REJECTED with error.source: "PEPPOL_AP".

Error object

All error responses — both HTTP errors and authority rejections — return a consistent error envelope.

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body validation failed",
    "violations": [
      { "field": "lines[0].taxCode", "message": "must be a valid EN16931 tax code" }
    ]
  }
}

{
  "clearanceStatus": "REJECTED",
  "terminal": true,
  "rejectedAt": "2024-01-15T10:47:12Z",
  "error": {
    "source": "SDI",
    "code": "00102",
    "message": "Partita IVA fornitore non trovata",
    "detail": "Supplier tax ID 01234567890 is not registered with the Italian Revenue Agency"
  }
}

{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "requestId": "req_01J9XKZ4MFBVQH7PRTD8CNWY5"
  }
}

Entities

Entities represent the legal entities in your organisation that are registered for tax compliance. Each entity has its own tax numbers, credentials, and compliance footprint. All transactional API calls (e-invoicing, tax calculations, tax number validation) are scoped to an entity.

API Keys

API keys authenticate every request to the Clearvo API. Keys are scoped to either an account (with a required X-Entity-Id header per-request) or a specific entity. You can restrict a key to specific products (einvoicing, tax, tin, entities) and access levels (read or write).

Key fields

Idempotency

Every POST /invoices request must include an x-idempotency-key header containing a UUID v4. This protects against duplicate submissions caused by network timeouts or retries.

How it works

• On the first request with a given key, Clearvo processes the invoice and caches the response.
• On any subsequent request with the same key and identical payload, the cached response is returned immediately — the invoice is not re-submitted to the authority.
• If you submit a different payload with the same key, Clearvo returns HTTP 409 Conflict. Generate a new UUID.
• Keys expire after 24 hours on Starter, 72 hours on Growth, and configurable on Enterprise.

Best practice

async function submitWithRetry(payload, idempotencyKey) {
  const MAX_RETRIES = 3;

  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
    try {
      const res = await fetch('https://api.clearvo.io/v1/invoices', {
        method: 'POST',
        headers: {
          'x-api-key': process.env.CLEARVO_API_KEY,
          'x-idempotency-key': idempotencyKey, // same key on every retry
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
      });

      if (res.status === 409) throw new Error('Key reused with different payload');
      if (res.ok) return res.json();
      if (res.status < 500) throw new Error(`Client error: ${res.status}`);
    } catch (err) {
      if (attempt === MAX_RETRIES - 1) throw err;
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
    }
  }
}

Italy — SDI lifecycle

Italy's Sistema di Interscambio (SDI) is an asynchronous clearance system. Invoices are accepted or rejected typically within minutes, but the SDI can take up to 5 days for a final decision in exceptional cases.

Status lifecycle

UNDELIVERED and mcDeadline

The UNDELIVERED status means the SDI successfully received your invoice but could not deliver it to the buyer's inbox (invalid Codice Destinatario, full mailbox, etc.). The SDI continues retrying for 10 days. This window is exposed as mcDeadline in the status response.

After the 10-day window expires:

• If the buyer eventually received it — the invoice is legally valid.
• If it was truly undeliverable — the invoice is still legally valid under Italian law (D.Lgs. 127/2015), but you should notify the buyer by other means and keep proof of the SDI notification.

Polling cadence

Poll every 5 minutes while PENDING. Clearvo returns a nextPollAfter timestamp — always honour this rather than hardcoding intervals. Polling more frequently will not speed up SDI processing and may trigger rate limiting.

Poland — KSeF

KSeF (Krajowy System e-Faktur) is Poland's national e-invoicing platform, operated by the Ministerstwo Finansów. Mandatory for large taxpayers (>PLN 200M revenue) from 1 February 2026; all other Polish VAT registrants from 1 April 2026. Format: FA(3) XML, schema namespace http://crd.gov.pl/wzor/2025/06/25/13775/.

Step 1 — Register your KSeF token (one-time setup)

KSeF requires a per-entity API token that you generate in the KSeF Taxpayer Portal. Clearvo submits invoices and polls your inbox under your company NIP using this token.

POST /api/einvoicing/v1/pl/credentials
x-api-key: csk_live_••••••••
Content-Type: application/json

{
  "nip":         "1234567890",
  "token":       "<token from ksef.mf.gov.pl>",
  "environment": "production"
}

Step 2 — Submit an invoice

Use the standard POST /api/einvoicing/v1/send endpoint. Set buyerCountry: "PL" and include NIP numbers in supplier.taxId / buyer.taxId with the PL prefix (e.g. PL1234567890).

Step 3 — Poll for KSeF number

KSeF processes invoices asynchronously — typically within 5–30 seconds. Poll GET /api/einvoicing/v1/status?country=PL&id=<submissionId> until terminal: true. On acceptance:

{
  "clearanceStatus": "ACCEPTED",
  "terminal":        true,
  "ksefNumber":     "7010830304-20260619-7269D0000000-DF",
  "upoAvailable":   true,
  "clearedAt":      "2026-06-19T10:23:45.000Z"
}

The KSeF number (ksefNumber) must appear on the invoice PDF — your buyer needs it to claim input VAT deduction. Store it permanently against the invoice record.

UPO — official Ministry receipt

After acceptance, Clearvo automatically fetches the UPO (Urzędowe Poświadczenie Odbioru) — the Ministry of Finance-signed XML receipt. upoAvailable: true in the status response confirms it has been stored. The UPO must be retained for 10 years per Polish VAT law.

Status lifecycle

Inbound — receiving invoices

KSeF maintains a buyer inbox per NIP. Clearvo polls every 5 minutes and fires an invoice.received webhook for each new invoice. Each inbound invoice includes a White List check (Biała Lista) on the supplier's registered bank accounts — the result appears in invoiceData.whiteList. Paying to an account not on the White List risks losing input VAT deduction rights (Art. 108a uVAT).

Trigger a manual poll or backfill:

POST /api/einvoicing/v1/pl/inbound/poll
x-api-key: csk_live_••••••••

Correction invoices

Use documentType: "credit_note" with an originalInvoiceRef block. Clearvo sets RodzajFaktury: KOR automatically.

{
  "documentType":    "credit_note",
  "invoiceNumber":   "FV-KOR/2026/06/00001",
  "issueDate":       "2026-06-20",
  "originalInvoiceRef": {
    "invoiceNumber": "FV/2026/06/00001",
    "issueDate":     "2026-06-19",
    "reason":        "Incorrect unit price"
  }
}

Germany — XRechnung

Germany currently has no central B2B invoice clearance authority. Clearvo generates a valid XRechnung 3.0 document (or ZUGFeRD 2.3 hybrid PDF for B2B), delivers it via Peppol where the buyer has a Peppol ID, and returns ACCEPTED immediately on successful XML validation.

No asynchronous clearance

Unlike Italy or Poland, German B2B invoices do not go through a tax authority clearance step. Clearvo validates your payload against the XRechnung 3.0 Schematron rules, generates the XML, and marks the invoice ACCEPTED as soon as the document passes validation. The terminal flag is true on the initial response — no polling required.

BuyerReference (Leitweg-ID)

For public sector (B2G) invoices, the countryData.de.buyerReference field containing the Leitweg-ID is mandatory. The Leitweg-ID is assigned by the contracting authority and identifies the recipient routing within German public administration (Xrechnung EN16931 BT-10).

For B2B invoices, buyerReference is optional but recommended when the buyer requests it for internal purchase-order matching.

Peppol delivery

If the buyer has a registered Peppol ID (e.g. 0088:4047035000007), Clearvo automatically routes the XRechnung via the Peppol network. If the buyer is not on Peppol, the invoice is made available for download from the Clearvo portal and you are notified via webhook. A rejection from the buyer's Access Point is surfaced as REJECTED with error.source: "PEPPOL_AP".

France — Factur-X and the PDP framework

France is implementing a mandatory B2B e-invoicing and e-reporting system under the réforme de la facturation électronique. The rollout is phased:

• September 2026 — Large enterprises (>250 employees or >50M€ turnover) must receive e-invoices; obligation to send follows shortly after.
• January 2027 — Mid-sized businesses.
• January 2028 — Small businesses and microenterprises.

What Clearvo generates today

Clearvo generates Factur-X EN16931 — the hybrid PDF+XML format that embeds a CII (Cross Industry Invoice) XML document inside a PDF/A-3. This is the format that French PDPs accept for domestic B2B invoices. The generated XML is structurally valid and can be validated against the EN16931 Schematron.

For B2G invoices, Chorus Pro is the existing mandatory channel. Clearvo does not currently submit to Chorus Pro — that integration is on the roadmap for 2026.

What is a PA (Plateforme Agréée)?

A PA (Plateforme Agréée) — formerly called PDP (Plateforme de Dématérialisation Partenaire) — is a DGFiP-accredited intermediary that receives invoices, validates them, forwards them to the buyer's platform, and reports transaction data to the DGFiP's Portail Public de Facturation (PPF). There are approximately 137 platforms in the process of accreditation as of June 2026.

Clearvo has applied for PA accreditation in its own right (file 31890388, submitted June 2026). The infrastructure is fully built and ready for the DGFiP's sandbox testing phase, which begins upon provisional accreditation. This means your invoices will be routed directly through Clearvo as the PA — no third-party intermediary required.

Current status — what you need to know

If you are building an integration today: submit invoices to Clearvo with country: "FR". Clearvo will generate the Factur-X XML and mark the invoice ACCEPTED. The XML is stored and available for download. When PA routing goes live (September 2026), the same API call will automatically route through the Clearvo PA — your integration does not change.

Status lifecycle (current behaviour)

Peppol countries

Clearvo supports 22 Peppol BIS Billing 3.0 countries (BE, NL, AT, HR, SK, DK, IE, NO, SE, FI, LT, LV, EE, LU, SI, IS, CH) and 5 PINT countries (AU, NZ, SG, JP, AE). Your API payload uses the same CustomerInvoiceInput schema for all — only country changes. Clearvo handles format selection, EAS scheme resolution, SMP lookup, and AS4 delivery automatically.

How Peppol delivery works

Peppol is a network of certified Access Points (APs) that exchange business documents using the AS4 messaging protocol. When you submit an invoice for a Peppol country, Clearvo:

Buyer endpoint resolution

Clearvo resolves the buyer's Peppol endpoint in this order:

1. Explicit — buyer.endpointId + buyer.endpointSchemeId in the payload. Required for NL, SK, AT, IS, NZ, AE, and CH where VAT-to-Peppol derivation is not reliable.
2. Auto-derived — Clearvo derives the Peppol identifier directly from buyer.taxId for countries where this is unambiguous: BE, DK, NO, FI, SE, HR, IE, LU, SI, EE, LV, LT, AU, SG, JP.
3. SMP cache — Resolved endpoints are cached indefinitely. Cache is refreshed automatically on delivery failure.

If no endpoint can be determined or the buyer is not registered on Peppol, the invoice transitions to UNROUTABLE (non-terminal). The UBL XML is stored. Retry delivery later via POST /v1/invoices/{id}/deliver.

Use GET /v1/participants/lookup to check whether a buyer is registered before submitting an invoice.

Country-specific EAS endpoint schemes

Countries marked Auto derive the Peppol ID from buyer.taxId — no extra fields needed. Countries marked Explicit require buyer.endpointId and buyer.endpointSchemeId in the payload.

For NL, SK, AT, IS, NZ, AE, and CH, always provide buyer.endpointId and buyer.endpointSchemeId explicitly — VAT-to-Peppol derivation is not reliable for these countries. For all other Peppol countries, Clearvo derives the endpoint automatically from buyer.taxId.

Format and validation

All BIS Billing 3.0 invoices are validated against:

• UBL 2.1 schema (structural)
• EN16931 Schematron (business rules)
• Peppol BIS 3.0 Schematron (BIS-specific rules, e.g. mandatory CustomizationID)

Belgium — Hermes/Mercurius

Belgium's public sector uses the Mercurius platform (operated by BOSA). B2G invoices for Belgian federal entities must be delivered to Mercurius via Peppol. Clearvo routes B2G invoices automatically via the Peppol network — no separate integration is required from your side.

The Belgian B2B mandate (all businesses) is effective from 2026. Buyers who are not yet on Peppol can also receive invoices via the Hermes portal.

Croatia — FINA

Croatia's e-invoicing infrastructure is managed by FINA (Financijska agencija — Croatian Financial Agency). FINA operates a Peppol Access Point. The 2026 mandate covers B2B and B2G transactions.

Greece — myDATA

myDATA (My Digital Accounting and Tax Application) is Greece's real-time digital transaction reporting system operated by AADE (Ανεξάρτητη Αρχή Δημοσίων Εσόδων — the Independent Authority for Public Revenue). All businesses must report invoices to AADE in real-time.

How it works

Unlike pre-clearance countries (Italy, Poland), Greece uses a post-issuance reporting model. You issue the invoice to your buyer normally, then separately report the transaction data to AADE via the myDATA API. The invoice is not "approved" by AADE before delivery — it is registered after the fact.

VAT category mapping

Status lifecycle

Webhooks

In the meantime, contact us to be notified when webhook support is released.