API Overview

Endereco provides a suite of master data validation services via a JSON-RPC 2.0 API.

Base URL

POST https://endereco-service.de/rpc/v1

All requests are POST to this single endpoint. The method name is in the JSON body.

Authentication

Header	Required	Description
X-Auth-Key	Yes	Your API key
Content-Type	Yes	application/json
X-Transaction-Id	No	UUID v4 for session-based billing
X-Agent	No	Client identifier, e.g. MyApp v1.0.0
X-Transaction-Referer	No	Page URL where data was entered

Request Shape

Every request follows JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "addressCheck",
  "params": {
    "country": "DE",
    "postCode": "97232",
    "cityName": "Giebelstadt",
    "street": "Lindenstraße",
    "houseNumber": "28"
  }
}

Response Shapes

Success

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "predictions": [ ... ],
    "status": ["address_correct", "..."]
  }
}

Error

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Field \"params.postCode\" must be set."
  }
}

Country Codes

ISO 3166-1 Alpha-2 codes (DE, AT, CH, US, GB, FR, IT, NL, ES, PL, …). Full list: github.com/Endereco/enderecoservice_api/blob/master/country-codes.md

Available Methods

Address Services

Method	Description
addressCheck	Full address validation
postCodeAutocomplete	Postal code autocomplete
cityNameAutocomplete	City name autocomplete
streetAutocomplete	Street autocomplete
splitStreet	Split street + house number

Contact Services

Method	Description
emailCheck	Email validation
phoneCheck	Phone number validation
nameCheck	Name and salutation validation

Financial Services

Method	Description
ibanCheck	IBAN validation + bank details
vatIdCheck	VAT ID validation

Technical Services

Method	Description
readinessCheck	API availability check
doAccounting	Finalize session for billing

CORS & Proxy

The Endereco API is server-to-server only — no CORS headers are returned for browser requests. The playground in this documentation handles this as follows:

• Development (localhost): requests go through the VitePress dev-server proxy at /rpc-proxy → https://endereco-service.de
• Production: set VITE_PROXY_URL to one of the proxy options below

EU compliance note

API keys transit the proxy on every request. For GDPR / Schrems II compliance, choose a proxy that runs exclusively on EU infrastructure. The three options below are ranked from most EU-native to least.

Option 1 — Self-hosted on EU VPS (recommended, 100% EU)

Run docs/proxy/eu-express-proxy.js on any EU VPS — Hetzner (DE), Scaleway (FR), OVHcloud (FR), or netcup (DE). Data never leaves EU infrastructure.

# On your EU VPS
git clone <repo> && cd docs/proxy
docker build -t endereco-cors-proxy .
docker run -d -p 3100:3100 --restart=unless-stopped endereco-cors-proxy

Set VITE_PROXY_URL=https://your-eu-server.example.de:3100/rpc as a GitHub secret.

The full source is in docs/proxy/eu-express-proxy.js and docs/proxy/Dockerfile.

Option 2 — Bunny.net Edge Scripting (EU-headquartered CDN)

Bunny.net is headquartered in Ljubljana, Slovenia (EU) and operates its own EU-region CDN. The Edge Scripting runtime is a Workers-compatible environment deployed on EU PoPs.

1. bunny.net → CDN → Edge Scripting → New Script
2. Paste docs/proxy/bunny-edge-script.js
3. Add route: POST /rpc → this script
4. Set VITE_PROXY_URL=https://your-pull-zone.b-cdn.net/rpc

Full source: docs/proxy/bunny-edge-script.js. See Bunny Edge Scripting docs.

Option 3 — Cloudflare Worker (US company, EU region possible)

Cloudflare is a US company (subject to CLOUD Act). For EU-only data residency, pin the Worker to EU regions using Regional Services. This is more complex to configure and requires a paid plan — not recommended for strict GDPR deployments.

The full source is in docs/proxy/worker.js.