Peppol Check API documentation
Free JSON API to verify Peppol registrations. No authentication, no API key. Machine-readable spec: openapi.json · agent guidance: llms.txt.
Basics
Base URL https://peppol-check.org. All responses are JSON (UTF-8). Errors are structured: {"ok":false,"error":"...","errorCode":"...","hint":"..."}. Rate limit: 60 requests per minute per IP; every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, and an exceeded limit returns 429 with Retry-After. Identify your client via User-Agent. For large lists, use the bulk endpoint instead of looping single checks.
GET/api/v1/check
Check one company by participant ID(s) or by name. For Belgian companies, pass both schemes as candidates: 0208:<enterprise number> and 9925:be<number>.
curl "https://peppol-check.org/api/v1/check?pids=0208:0403170701,9925:be0403170701"
# by company name
curl "https://peppol-check.org/api/v1/check?q=Electrabel"
Response fields per match: pid, name, country, regDate, docLabels (receivable document types), smp (SMP provider via live SML/DNS lookup). The top-level source tells you whether the answer came from the local snapshot (local) or the live Peppol Directory (live).
POST/api/v1/bulk
Verify up to 500 companies per request against the local dataset (6.5M+ participants).
curl -X POST "https://peppol-check.org/api/v1/bulk" \
-H "Content-Type: application/json" \
-d '{"rows":[{"i":0,"pids":["0208:0403170701"]},{"i":1,"pids":["0106:42020812"]}]}'
GET/api/v1/meta
Returns the build date and size of the local dataset, so you can report data freshness.
curl "https://peppol-check.org/api/v1/meta"
Error codes
| errorCode | HTTP | Meaning |
|---|---|---|
empty_query | 400 | No valid pids and no q given. |
rows_missing / too_many_rows | 400 | Bulk body malformed or over 500 rows. |
method_not_allowed | 405 | Bulk requires POST. |
rate_limited | 429 | Over 60 req/min; respect Retry-After. |
dataset_missing | 503 | Local dataset unavailable; use /api/check. |
Versioning & deprecation policy
The API is versioned in the URL path; the current version is /api/v1/. The unversioned paths (/api/check, /api/bulk, /api/meta) are permanent aliases of v1. Breaking changes only ever appear under a new version prefix. When a version is deprecated, it keeps working for at least six months, responses carry Deprecation and Sunset headers, and the timeline is announced on this page. Unknown paths under /api/ return a structured JSON 404, never HTML.
Interpretation notes
The Peppol Directory is an opt-in register. Treat an empty result as "not published", not "not connected". Belgian participants usually appear under both scheme 0208 (enterprise number) and 9925 (VAT); they are the same entity. Data is for lookup purposes; do not redistribute it as a database (see terms).