POST /certify/batch

Certifies a file of French counterparties in one call: up to 200 lines keyed by SIREN or SIRET, settled with one x402 payment. Each line comes back as a complete, sourced answer with its own verdict, and the batch carries an Ed25519-signed Merkle root — so the buyer of your file can verify any single line offline, with the published verifier, without receiving the other 199 lines and without calling us.

Before any of that, read what this does not cover. A “certified file” sells on what it guarantees and breaks on what the buyer assumed it guaranteed.

What this does not certify

Every response carries this sentence in data.limits, verbatim:

This certifies, for each subject, its existence, its administrative state and its published legal events in the French Sirene and BODACC registers, as of the dates carried by each record’s provenance - and nothing else. It does NOT certify that an email address is deliverable, that the subject is registered in the French e-invoicing directory (AIFE) or reachable there, nor that a company name resolves to a SIREN: a line without an exact, well-formed key is returned ‘unresolved’, never guessed. The ‘e-invoicing-fr’ profile answers the identity and events blocks only - VAT, Peppol, group and sanctions screening are not part of it, so a verdict of ‘ok’ is an ‘ok’ on those two blocks. Each record’s timeline is capped at the 10 most recent notices (‘total’ and ‘truncated’ say so; the flags are derived from the full history, so no verdict depends on the cap). A verdict is a deterministic decision table over sourced, dated facts; it is not a credit opinion, a risk score or a recommendation to act.

Explicitly, and in order of how often it is misread:

1. No email deliverability. Not checked, not requested, not accepted as input. No official register publishes the fact. This is the single most common assumption behind the phrase “certified file”, and it is wrong here.
2. No AIFE presence or routability. The French e-invoicing directory’s API is reserved to approved platforms (Plateformes Agréées). What is certified is existence and administrative state in the Sirene register — never addressability. Peppol reachability is a different network, a different directory and a different endpoint: GET /company/peppol.
3. No name-to-SIREN resolution. There is no search by name. A line without an exact, well-formed key comes back unresolved — never guessed.
4. No phone number. Sirene publishes no contact field at all.

Three limits of scope, of the same kind:

• The profile states what was checked, and it is signed. e-invoicing-fr answers two blocks — identity (Sirene) and events (BODACC). VAT, Peppol, control chain and sanctions screening are not in it. An ok is an ok on those two blocks, and such a proof must never be presented as a complete counterparty check. For that, see GET /preflight/supplier.
• An attestation is a dated verdict, not a present truth. Each record carries the as_of of its sources and the certificate its issued_at. It does not expire on its own — it states what it was rendered against.
• No score, no file grade, no recommendation to act. The summary counts outcomes; it does not rank your file.

Vocabulary. What this produces is a signed attestation. It is not a certificate in the eIDAS sense — a regulated object with qualified timestamping. The JSON field is named certificate; the legal meaning is not implied.

The job: the French e-invoicing switchover

From 1 September 2027, small and micro enterprises in France must issue their invoices electronically. Whoever has to be ready for that date is generally sitting on a customer and supplier file accumulated over years, whose SIRENs were typed or copied by hand — and which has never been checked against the register.

The Luhn checksum does not help. It catches every single-digit substitution, so the errors it catches never survive in a file. The ones that do survive are the ones no offline validator can catch, because the result is a valid SIREN: a value copied from the wrong row, the identifier of another entity in the same group, a head office where the invoice is owed by a subsidiary, a company struck off years ago.

That is what the optional expected_name catches — by comparing the name you hold with the one the register publishes. See the real batch below, where a line filed as BNP PARIBAS FACTOR resolves to BNP PARIBAS.

Pricing

Priced per line submitted, not per line found: the gateway quotes on the input, before the service knows which subjects exist. That is the honest way round — “this SIREN is not in the register” is precisely the answer being bought, and on an aged file it is often the most useful one. One settlement covers N lines, so the fixed part amortises as the batch grows.

The cap is 200 lines; beyond it the gateway returns a 400 before issuing any challenge, so nothing is ever settled.

No price is written on this page. The gateway’s /catalog is the single source of truth for the base, the per-unit amount and any active trial. See pricing a batch for how the quote is built.

Request

POST with a JSON body. Set Content-Type: application/json.

POST /certify/batch
Content-Type: application/json

{
  "profile": "e-invoicing-fr",
  "subjects": [
    { "ref": "L-0001", "siren": "395030844", "expected_name": "SANOFI" },
    { "ref": "L-0002", "siren": "662042449", "expected_name": "BNP PARIBAS FACTOR" },
    { "ref": "L-0003", "siren": "321875205" },
    { "ref": "L-0004", "siren": "000000000" }
  ]
}

Each subject:

Give exactly one key per line, siren or siret — zero or two is a 400.

Unknown fields are refused, not ignored:

{
  "code": "INVALID_INPUT",
  "error": "invalid request body: Failed to deserialize the JSON body into the target type: subjects[0].sirene: unknown field `sirene`, expected one of `ref`, `siren`, `siret`, `expected_name`"
}

A sirene: typed for siren: and silently dropped would become a billed unresolved line. Refusing is cheaper for everybody.

ref is required, and it is attested. It is copied verbatim into the hashed scope alongside the line’s rank, so two records of one batch are never interchangeable. Order matters and is preserved: a line’s rank indexes its leaf in the Merkle tree.

200 response — UnifiedResponse

{
  "data": {
    "profile": "e-invoicing-fr",
    "summary": {
      "subjects": 4,
      "by_issue": { "certified": 3, "unresolved": 1 },
      "by_verdict": { "ok": 1, "review": 1, "stop": 1, "insufficient_coverage": 0 },
      "by_reason": {
        "expected_name_mismatch": 1,
        "recent_legal_event": 1,
        "coverage_unavailable": 1,
        "open_insolvency_announcement": 1,
        "subject_not_in_register": 1
      },
      "by_notice": {}
    },
    "records": [ ... ],
    "certificate": {
      "certificate_version": 1,
      "profile": "e-invoicing-fr",
      "payload_hash": "sha256:bhkW-doyj31nMrFWXH_Ud6AIC6fyCK58ol3VSKup3yU",
      "subject_count": 4,
      "issued_at": "2026-08-14T06:17:56.054824584Z",
      "alg": "Ed25519",
      "key_id": "invoket-2026-08",
      "signature": "hx6TDW72U5kGGe5PrB7dTfFpiFC5rMjR2LedzlIlVxrECssBrpeEYkqLSGL9OuO0GL-7sqgobx5RunmRWOP-Aw"
    },
    "proofs": {
      "batch_id": "batch_bNFUWNcbh_vy-hyw0D4HGQ",
      "available_until": "2026-08-15T06:17:56.054824584Z",
      "retention": "This index keeps only the record digests and the batch root - never the records themselves. …"
    },
    "limits": "This certifies, for each subject, its existence, its administrative state …"
  },
  "provenance": {
    "source": "insee-sirene",
    "fetched_at": "2026-08-14T06:17:56.054824584Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-07-31T00:00:00Z" }
  }
}

by_issue and by_verdict serve all their keys, even at zero; by_reason and by_notice carry only the reasons actually observed — but both objects are always served, empty ({}) when there is nothing to count.

Two reason counters, and that is deliberate. by_reason counts what weighed on a verdict (stop, review, gap); by_notice counts the notices, which changed nothing. On a file where three reasons weighed and one was a notice, a buyer reads “3 problems, 1 mention” instead of “4 reasons” — and on a file of sole traders, where notices dominate, that is the difference between a usable headline figure and a misleading one. Every reason served in records[] is counted in one or the other, never both, never neither.

The root provenance is the identity base’s. The per-record and per-block provenances govern — each block carries its own source, fetched_at and freshness, and those are inside the signed scope.

A certified record

A record is a response — { data, provenance } plus its fingerprint — in the exact shape of the matching standalone endpoints. That is what makes it extractable: your buyer receives one record, unmodified, and the verifier accepts it as is.

{
  "issue": "certified",
  "data": {
    "subject": {
      "index": 1,
      "ref": "L-0002",
      "key": "siren",
      "value": "662042449",
      "name": "BNP PARIBAS",
      "siren": "662042449",
      "expected_name": "BNP PARIBAS FACTOR",
      "expected_name_check": "mismatch"
    },
    "verdict": "review",
    "verdict_reasons": [
      { "block": "identity", "code": "expected_name_mismatch", "severity": "review", "detail": "the register publishes \"BNP PARIBAS\"" },
      { "block": "events", "code": "recent_legal_event", "severity": "review", "detail": "insolvency on 2026-04-07" },
      { "block": "events", "code": "coverage_unavailable", "severity": "gap", "detail": "undetermined_latest_notice" }
    ],
    "blocks": {
      "identity": {
        "coverage": "complete",
        "data": { "siren": "662042449", "name": "BNP PARIBAS", "status": "active", "…": "…" },
        "provenance": { "source": "insee-sirene", "fetched_at": "2026-08-14T06:17:56.054824584Z", "freshness": { "kind": "snapshot", "as_of": "2026-07-31T00:00:00Z" } }
      },
      "events": {
        "coverage": "unavailable",
        "data": { "events": [ … ], "total": 29, "truncated": true, "flags": { "has_open_insolvency_announcement": null, "is_deregistered": false }, "…": "…" },
        "provenance": { "source": "dila-bodacc", "fetched_at": "2026-08-14T06:17:56.054824584Z", "freshness": { "kind": "snapshot", "as_of": "2026-08-09T00:00:00Z" } }
      }
    }
  },
  "provenance": { "source": "insee-sirene", "…": "…" },
  "fingerprint": "sha256:UGMRE56NPxOC0Z4ZtIEecdNStxRQM-CrG0JC96FMB-4"
}

identity carries the full shape of GET /company/resolve; events the full shape of GET /company/events, timeline capped at 10.

Note has_open_insolvency_announcement: null. That is the third state: the gazette’s labels did not settle the question. It is a coverage gap, reported as coverage_unavailable, and it is deliberately not a stop — a maximal verdict on a fact we do not hold would be a fabrication.

An unresolved record

A well-formed key that no register knows. It is served, billed, and says so — verdict: null, both blocks reduced to { coverage, reason }. No data is invented.

{
  "issue": "unresolved",
  "data": {
    "subject": { "index": 3, "ref": "L-0004", "key": "siren", "value": "000000000", "name": null, "siren": null },
    "verdict": null,
    "verdict_reasons": [{ "block": "identity", "code": "subject_not_in_register", "severity": "stop" }],
    "blocks": {
      "identity": { "coverage": "not_applicable", "reason": "subject_not_in_register" },
      "events": { "coverage": "not_applicable", "reason": "no_subject_to_check" }
    }
  },
  "provenance": { "source": "insee-sirene", "…": "…" },
  "fingerprint": "sha256:phrYjXQB8W8Hurw8Jl-qMegpSK9IevMhA43mDuyTn9A"
}

verdict is null, never absent, and never a default. Running the decision table over not_applicable blocks would return ok on a SIREN that does not exist. A field of the hashed scope that disappeared would also change the fingerprint silently — so the scope is fixed and emptiness is written down.

Verdicts

Each certified line gets one verdict — ok, review, stop or insufficient_coverage — from the same decision table as GET /preflight/supplier, restricted to the two blocks in the profile. Each reason carries severity — the column below, served as a field — and the verdict is exactly the maximum severity among the reasons, so you can recompute it from the blocks instead of taking it on trust.

Three rules do the work, and the batch never blurs them:

• A mismatch is a review, never a stop. The SIREN exists and may still be the right one (trade name, renamed entity, group parent). But it is never a silent ok, because the failure mode being targeted is precisely the one that reads well.
• “Not comparable” is not “does not match”. When the register publishes no legal name — partial diffusion, a natural person — expected_name_check is not_checkable, the reason weighs nothing and the line still returns ok. That case has its own section below, because it is the one an agent misreads.
• A recent notice is not automatically a signal. Only signalling families count — court judgments, deregistrations, notices to creditors. The sale family does not, because none of its ~1.5 M labels says the direction of the operation: the indexed SIREN can be the buyer as easily as the seller. An active company publishes several a year. See SANOFI below, which returns ok while carrying a 2026 sale notice.

What the name comparison folds

expected_name_check is match, mismatch or not_checkable, and nothing else. The comparison is an equality between two normalised forms — there is no edit distance and no similarity threshold, because this field is attested and signed, and an “approximately” would be a promise you could not hold in front of a third party.

It folds typography — the part nobody types the same way twice: case, accents, repeated spaces, and all punctuation (apostrophes, hyphens, abbreviation dots). Real captures against the production store, 16 August 2026:

It does not fold words. A substituted word (& for ET), an abbreviation (CIE for COMPAGNIE), a legal form added or dropped (SAS, SA, SARL) change letters, so they stay mismatch. That is deliberate: folding them would be a business rule rather than a typographic normalisation, and one match too many costs exactly what this check is bought for.

The limit, written rather than discovered. Punctuation being elided, the comparison cannot tell a removed separator from a joined word — MAISON NEUVE and MAISONNEUVE are folded together. For that to hide the failure mode being targeted, a mistyped SIREN would have to land on a company whose published name is the one you expected, down to the word breaks.

Punctuation folding ships with the next image: the container serving production today still answers mismatch on EQUIPTEC and on COMPAGNIE DE SAINTGOBAIN. The other four rows are as served.

An ok can carry a reason

An ok is not the promise that every requested check happened. It is the promise that none of them raised a reason for reservation.

That sentence is the whole of it, and the difference is read in severity. A notice is served in verdict_reasons, counted in by_notice, and weighs nothing on the verdict. Captured against the production store on 16 August 2026 — siren=005572508, with an expected_name submitted:

{
  "issue": "certified",
  "data": {
    "subject": {
      "index": 0, "ref": "diffusion-P", "key": "siren", "value": "005572508",
      "name": null, "siren": "005572508",
      "expected_name": "QUELCONQUE", "expected_name_check": "not_checkable"
    },
    "verdict": "ok",
    "verdict_reasons": [
      { "block": "identity", "code": "expected_name_not_checkable",
        "severity": "notice",
        "detail": "the register publishes no legal name for this subject" }
    ],
    "blocks": {
      "identity": { "coverage": "complete", "data": {
        "siren": "005572508", "name": null, "status": "active",
        "diffusion_status": "partial", "…": "…" } }, "…": "…"
    }
  },
  "provenance": { "source": "insee-sirene",
                  "freshness": { "kind": "snapshot", "as_of": "2026-07-31T00:00:00Z" } },
  "fingerprint": "sha256:uoezQXn26mMpmb2SMdeWDQViku5Da3-cAu6ZFLXaMWE"
}

This unit is in partial diffusion: the register publishes no legal name for it, so the expected_name check you asked for could not take place. The verdict is not downgraded for it — a company that withholds its name from public diffusion is exercising a right (art. A123-96 of the French commercial code), and treating that as suspicious would be both wrong and discriminatory. But you must be able to see it, and severity: "notice" is what you read.

It is not marginal: on a random sample of 200 SIREN, 34 units (17%) are in partial diffusion, and a file of sole traders — the very population of the e-invoicing switchover — will carry more.

identity.coverage stays complete: the block is complete as far as the register goes, with coverage.missing listing name. “The register does not publish it” is not “we could not read it”.

severity is served on every reason in the extracts on this page; it is the one field here that ships with the next image rather than the one deployed today. Every other value in those extracts is as served.

The attestation

{
  "certificate_version": 1,
  "profile": "e-invoicing-fr",
  "payload_hash": "sha256:bhkW-doyj31nMrFWXH_Ud6AIC6fyCK58ol3VSKup3yU",
  "subject_count": 4,
  "issued_at": "2026-08-14T06:17:56.054824584Z",
  "alg": "Ed25519",
  "key_id": "invoket-2026-08",
  "signature": "hx6TDW72U5kGGe5PrB7dTfFpiFC5rMjR2LedzlIlVxrECssBrpeEYkqLSGL9OuO0GL-7sqgobx5RunmRWOP-Aw"
}

Two parties, deliberately separated:

• The service computes payload_hash — the Merkle root of the record fingerprints (JCS, RFC 8785 canonicalisation, SHA-256, domain-separated tree). It holds no secret.
• The gateway writes alg, key_id and signature (Ed25519, RFC 8032) — and nothing else. It reads one string at one fixed path and signs it; it never interprets a business block or reads a verdict.

Two consequences worth stating plainly: the root is pure computation, so anyone can reproduce it — and because the service never holds the key, a compromised key cannot forge a past verdict that was never issued.

What is inside the signed scope, per record: subject, verdict, verdict_reasons, blocks (from record.data) and provenance (from the record root). verdict is in it — the buyer of a certified verdict really is buying a certified verdict.

What is outside it: data.certificate itself, and the batch-level limits. The signature never covers the field carrying it.

A missing or malformed fingerprint, a non-JSON body or an unavailable key produces a frank 502, never an unsigned 200. And an endpoint that certifies without an active signing key refuses to start: an absent field goes unnoticed, an error does not.

The proofs block

proofs is a convenience, never a source of truth, and the response says so in its own retention sentence. It is an in-memory index holding record digests and the batch root — never the records themselves — that a restart or a burst of batches can drop before available_until. Every record carries its fingerprint, so an inclusion path is something you compute offline from the batch response you already hold.

The offline verifier

A certificate you cannot check without us is not a proof, it is an assertion. So the reference verifier is published:

verify_certificate.py — Python standard library only. No network, no dependency on Invoket, Ed25519 included (RFC 8032 implemented in the script and checked against OpenSSL in CI). Your buyer installs nothing and trusts nobody to check a proof.

# 1. fetch the public keys once (the only network call, and it is unpaid)
curl -s https://api.invoket.com/.well-known/certificate-keys > keys.json

# 2. verify a whole batch
python3 verify_certificate.py batch.json --key keys.json

# 3. verify a SINGLE record with its inclusion path
python3 verify_certificate.py record.json --key keys.json --proof proof.json

The five checks, and what each one proves

This is the distinction that carries the whole offer. Checks 1 to 4 prove a response is coherent. Only check 5 proves it came from us. Digests are pure computation, so an intermediary can fabricate a wholly coherent file — it cannot fabricate the signature.

Run without --key, the script says so on every run rather than letting you believe otherwise, and it does not go and fetch the key itself: a verifier that reaches out to the network is no longer verifiable offline.

Real output, verifying a single extracted record without --key (the script’s messages are in French; the glosses are ours):

empreinte de l'enregistrement : sha256:UGMRE56NPxOC0Z4ZtIEecdNStxRQM-CrG0JC96FMB-4 ✓
appartenance au lot (2 pas de preuve) ✓
profil « e-invoicing-fr » — la preuve ne couvre que les blocs de ce profil, jamais un contrôle complet
verdict rendu le 2026-08-14T06:17:56.054824584Z contre : insee-sirene@2026-07-31T00:00:00Z, dila-bodacc@2026-08-09T00:00:00Z
⚠️ signature présente (clé « invoket-2026-08 ») mais NON vérifiée : relancez avec `--key`
OK

Line by line: the record’s fingerprint recomputes; its inclusion path reaches the root in 2 steps; the proof covers only this profile’s blocks; the verdict was rendered on 2026-08-14 against the Sirene snapshot of 2026-07-31 and the BODACC snapshot of 2026-08-09; the signature was not checked. Re-run with --key and the last line becomes signature Ed25519 vérifiée contre la clé « invoket-2026-08 » ✓.

Exit code is 0 when everything checked out, 1 otherwise — and a failure is loud: altering one byte of a record yields ÉCHEC : … — il a été retouché.

Two caveats on the published script. Its header comment references batch-retrieval and proof-fetching routes; those are not served yet (the gateway cannot express a free relayed endpoint today), so build the inclusion path offline from the fingerprints your batch response already carries. And its messages are French-only for now — the checks, the guarantees and the exit codes are unaffected.

Errors

Every 400 above happens before any work: nothing is certified, nothing is settled.

A malformed key rejects the whole batch, listing every offending line by index and ref:

{
  "code": "INVALID_SUBJECTS",
  "error": "1/5 subjects have a malformed key: nothing was certified, nothing is billed",
  "rejected": [
    { "code": "INVALID_CHECKSUM", "index": 3, "ref": "row-4", "reason": "siren failed its checksum (Luhn): likely a typo" }
  ]
}

The gateway quotes on the subjects submitted, so there is no way to drop one line from an otherwise served batch without billing a subject that was never processed — and half a certified file would be worse than none.

Note the contrast that defines this endpoint: a malformed key kills the batch; a well-formed but absent key is a served, billed unresolved line. The first is a request we cannot answer, the second is an answer.

A real batch of four lines

The request at the top of this page, captured against production on 2026-08-14 (payload_hash sha256:bhkW-doyj31nMrFWXH_Ud6AIC6fyCK58ol3VSKup3yU, key invoket-2026-08):

• L-0001 returns ok although its timeline carries a sale notice dated 2026-05-22 — 42 notices in total. That is the rule above at work: the sale family raises nothing, because the label does not say whether this SIREN bought or sold. Reading every recent notice as a signal would turn the check into a detector of ordinary business activity.
• L-0002 carries three reasons at once: the name filed (BNP PARIBAS FACTOR) is a different legal entity from the one the SIREN designates; a signalling notice from 2026-04-07 is under a year old; and the open-insolvency flag is undetermined, which is a coverage gap. Maximum severity is review, so review is the verdict.
• L-0003 is the case the file was cleaned for: an open insolvency proceeding gazetted against SAN MARINA — stop, with the reason attached to the block and the source that published it.
• L-0004 is well-formed and unknown to the register. Served, billed, verdict: null.

Latency. A 200-line batch is served in one synchronous response: 269 ms measured on 200 heavy subjects (200 × SANOFI, 10 notices each) and 434–545 ms on 200 varied real subjects, against local snapshots with no network in the data plane. Indicative measurements on the production store, not an SLA.

See also

• GET /company/resolve — the identity block, one company at a time. Need one line, not a file?
• GET /company/events — the events block, with the full timeline (100 notices) rather than the batch’s 10.
• GET /company/peppol — e-invoicing reachability, which this batch explicitly does not certify.
• GET /preflight/supplier — the same decision table over eight blocks, one counterparty at a time.
• POST /invoice/validate and POST /invoice/generate — the document side of the French reform, where this endpoint covers the counterparty.
• Quickstart — the 402 → pay → replay loop in full.
• For agents — discovery surfaces, the live /catalog and how settlement works.