ZEVRA › API reference · Last updated:
OpenAPI 3.1 · 11 endpoints

Kennzeichen-Check API reference

The Kennzeichen-Check API reference lists every endpoint with its parameters, response codes and fields. With Zevra this page is generated straight from the machine-readable description of the API, so it never drifts from the running API.

Try 100 checks for free →

Kennzeichen-Check · Integrate the Kennzeichen-Check · Kennzeichen-Check coverage

Base address and key

ItemValue
Base addresshttps://app.zevra24.de/api/kc/v1
Key in the headerX-WKZ-Key · Authorization: Bearer
Limit per key120 requests per minute
Sandbox keyStarts with wkz_sbx_: fixed scenarios, no authority, no charge

Price as stated in the description: Wunschkennzeichen live prüfen und reservieren. Grundgebühr 50,00 € im Monat, 0,05 € je berechneter Prüfung, 2,00 € je erfolgreicher Reservierung (netto, zuzüglich Behördengebühren). Limit: 120 Anfragen pro Minute je Schlüssel. Schlüssel mit wkz_sbx_ sind Sandbox-Schlüssel: feste Szenarien, keine Behörde, keine Berechnung.

Endpoints

With key means: header X-WKZ-Key or Authorization: Bearer. Every answer to a keyed call carries the limit headers.

POSTVerfügbarkeit aus dem domaingebundenen Widget prüfen

POST https://app.zevra24.de/api/kc/v1/widget/search

without key

Parameters

Originheader · required
–

Request body

application/x-www-form-urlencoded ·

site_keystring · required
starts with wkz_site_
codestring · required
Unterscheidungszeichen, 1 bis 3 Buchstaben
lettersstring · required
1 bis 2 Buchstaben
numbersstring · required
1 bis 4 Ziffern, ohne führende Null
plzstring
exactly 5 digits
office_idstring
at most 40 characters

Responses

CodeMeaningData model
200OKSearchResult
400Ungültige AnfrageError
401Site-Schlüssel oder Domain ungültigError
429Limit erreichtError
503Dienst nicht verfügbarError

POSTÖffentliche Zevra-Testabfrage, 10 Versuche pro Besucher und Tag

POST https://app.zevra24.de/api/kc/v1/public/search

without key

Parameters

Originheader · required
–

Request body

application/x-www-form-urlencoded ·

codestring · required
Unterscheidungszeichen, 1 bis 3 Buchstaben
lettersstring · required
1 bis 2 Buchstaben
numbersstring · required
1 bis 4 Ziffern, ohne führende Null
plzstring
exactly 5 digits
office_idstring
at most 40 characters

Responses

CodeMeaningData model
200OKSearchResult
400Ungültige AnfrageError
401Anfragequelle ungültigError
429Tageslimit erreichtError
503Dienst nicht verfügbarError

POSTBis zu 50 Kombinationen in einem Aufruf prüfen

POST https://app.zevra24.de/api/kc/v1/search/batch

with key

Request body

application/json ·

itemsarray <Plate> · required
at least 1 item · at most 50 items

Responses

CodeMeaningData model
200OKBatchResult
400Ungültige AnfrageError
401Schlüssel fehlt oder ist ungültigError
403Zugang beendet (revoked)Error
429Monatslimit erreicht oder zu viele AnfragenError
503Dienst vorübergehend nicht verfügbarError

POSTReservierung anlegen (nur mit aktivem Abonnement oder Sandbox-Schlüssel)

POST https://app.zevra24.de/api/kc/v1/reservations

with key

Parameters

Idempotency-Keyheader · required
at least 8 characters · at most 80 characters

Request body

application/json · ReservationRequest

Responses

CodeMeaningData model
200Bereits angelegt (gleicher Idempotency-Key)Reservation
202AngenommenReservation
400Ungültige AnfrageError
401Schlüssel fehlt oder ist ungültigError
403Abonnement erforderlichError
409Idempotency-Key mit anderem Inhalt verwendetError
429Monatslimit erreicht oder zu viele AnfragenError
503Dienst vorübergehend nicht verfügbarError

GETStatus einer Reservierung

GET https://app.zevra24.de/api/kc/v1/reservations/{rid}

with key

Parameters

ridpath · required
–

Responses

CodeMeaningData model
200OKReservation
401Schlüssel fehlt oder ist ungültigError
403Zugang beendet (revoked)Error
404Nicht gefundenError
429Monatslimit erreicht oder zu viele AnfragenError
503Dienst vorübergehend nicht verfügbarError

GETVerbrauch und Kosten des laufenden Zeitraums

GET https://app.zevra24.de/api/kc/v1/usage

with key

Responses

CodeMeaningData model
200OKUsage
401Schlüssel fehlt oder ist ungültigError
403Zugang beendet (revoked)Error
429Monatslimit erreicht oder zu viele AnfragenError
503Dienst vorübergehend nicht verfügbarError

GETZulassungsstellen und Zustand, optional nach Kürzel gefiltert (ohne Schlüssel)

GET https://app.zevra24.de/api/kc/v1/offices

without key

Parameters

codequery
–

Responses

CodeMeaningData model
200OKOffices

GETFeste Szenarien der Sandbox (ohne Schlüssel)

GET https://app.zevra24.de/api/kc/v1/sandbox/scenarios

without key

Responses

CodeMeaningData model
200OK–

GETDiese Beschreibung

GET https://app.zevra24.de/api/kc/v1/openapi.json

without key

Responses

CodeMeaningData model
200OK–

GETDiese Beschreibung als Postman-Sammlung (ohne Schlüssel)

GET https://app.zevra24.de/api/kc/v1/postman.json

without key

Responses

CodeMeaningData model
200OK–

Webhook

reservation.updated

Statuswechsel einer Reservierung, signiert mit HMAC-SHA256 (X-Zevra-Signature über »Zeitstempel.Inhalt«)

Parameters

X-Zevra-Eventheader · required
–
X-Zevra-Timestampheader · required
–
X-Zevra-Signatureheader · required
–

Request body

application/json ·

idstring
–
typestring
Values: reservation.updated
createdstring
–
dataReservation
–

Responses

CodeMeaningData model
200Jede 2xx-Antwort gilt als zugestellt; sonst Wiederholung nach 1, 5, 30, 120, 720 Minuten–

Limit headers

X-RateLimit-Limitinteger
Anfragen pro Minute je Schlüssel
X-RateLimit-Remaininginteger
Verbleibende Anfragen in der laufenden Minute
X-RateLimit-Resetinteger
Sekunden bis zur nächsten Minute
Retry-Afterinteger
Nur bei zu vielen Anfragen pro Minute: Sekunden bis zum nächsten Versuch

Data models

Field descriptions are taken unchanged from the OpenAPI file and are in German.

Error

errorstring · required
Values: backend · bad_request · batch_size · holder · idem_conflict · idem_key · letters · no_backend · not_found · numbers · prefix · quota_exhausted · rate_limited · revoked · subscription_required · unauthorized
messagestring · required
–
message_enstring
Dieselbe Meldung auf Englisch
quotaobject
Nur bei quota_exhausted: Stand des Kontingents

Plate

prefixstring · required
Unterscheidungszeichen, 1 bis 3 Buchstaben
lettersstring · required
1 bis 2 Buchstaben
numbersstring · required
1 bis 4 Ziffern, ohne führende Null

SearchResult

platestring | null
–
availableboolean | null
true = frei · false = vergeben · null = keine Aussage (nie als vergeben anzeigen)
reasonstring
Ohne Aussage (available = null): office_not_queryable/gate = Stelle nicht online prüfbar · check_failed/captcha_expired = Stelle antwortet gerade nicht, später erneut · unknown_prefix/unknown_office = Kürzel unbekannt · ambiguous_prefix = mehrere Stellen, plz oder office_id angeben. quota_exhausted · revoked · rate_limited · no_backend nur in /search/batch: ab diesem Eintrag wurde nicht mehr geprüft Values: checked · checked_via_twin · checked_via_warm_session · checked_via_captcha · check_failed · captcha_expired · gate · office_not_queryable · ambiguous_prefix · unknown_prefix · unknown_office · invalid · quota_exhausted · revoked · rate_limited · no_backend
sandboxboolean
–
known_officeboolean
Das Kürzel gehört zu einer bekannten Zulassungsstelle
checkableboolean
Die Zulassungsstelle ist live abfragbar
latency_msinteger
Antwortzeit der Behörde in Millisekunden
plate_invalidstring
Gesetzt, wenn die Kombination formal unzulässig ist (keine Prüfung gezählt) Values: prefix · letters · numbers · office
remaining_todayinteger
Nur /public/search: verbleibende Testabfragen heute
suggestionsarray <object>
Nur /public/search bei vergebenem Kennzeichen: freie Alternativen
suggestions_limitedboolean
Nur /public/search: die Behörde nannte weniger Alternativen als angefragt
suggestions_unavailableboolean
Nur /public/search: Alternativen konnten gerade nicht abgefragt werden

Holder

namestring · required
–
vornamestring
–
geburtsdatumstring
–
strassestring
–
plzstring · required
–
ortstring · required
–

Reservation

idstring
–
statusstring
Values: queued · processing · reserved · failed
environmentstring
Values: live · sandbox
platestring
–
customerReferencestring | null
–
reasonstring | null
–
reservationCodestring | null
Code der Behörde für die Zulassung, nur bei status=reserved
authorityFeeAdvancedCentsinteger
Von Zevra verauslagte Behördengebühr in Cent (durchlaufender Posten)
createdAtstring
–
updatedAtstring
–

BatchResult

countinteger
–
resultsarray <SearchResult>
–

ReservationRequest

prefixstring · required
Unterscheidungszeichen, 1 bis 3 Buchstaben
lettersstring · required
1 bis 2 Buchstaben
numbersstring · required
1 bis 4 Ziffern, ohne führende Null
halterHolder · required
–
customerReferencestring
at most 80 characters

Usage

environmentstring
–
statusstring
–
checksinteger
–
limitinteger
–
reservationsinteger
–
usageCentsinteger
–
authorityFeesAdvancedCentsinteger
–
periodEndstring | null
–

Offices

countinteger
–
officesarray <object>
–

Files to download

Questions about the API reference

Is this reference always up to date?
Yes. The page is generated from the same OpenAPI file the API serves at /api/kc/v1/openapi.json. A test compares both on every change.
How do I test without cost?
With a sandbox key (wkz_sbx_). It returns fixed scenarios, queries no authority and is not charged.
What happens above 120 requests per minute?
The API answers 429 with a Retry-After header. It states the seconds until the next attempt.
Which answer is charged?
Only a check with a statement from the authority (free or taken). Answers without a statement and sandbox answers cost nothing.

More about the Kennzeichen-Check

Kennzeichen-Check · Integrate the Kennzeichen-Check · Kennzeichen-Check coverage · Kennzeichen-Check for shops · Kennzeichen-Check for registration services · Kennzeichen-Check status

Registration offices with live checks, for example: Berlin · Hamburg · Frankfurt am Main · Stuttgart · Kreis Recklinghausen · Düsseldorf · Dortmund

Get a key and start

Register now → To the integration guide