Doku API + Massenprüfung
Allgemeines
Mit Ihrer kostenlosen Registierung erhalten Sie unter "Mein Konto" Ihre Zugangsdaten, Ihre API-Customer-ID ("apicid") sowie den Api-Key ("apikey"). Diese senden Sie uns in Ihren Requests mit.
Welche Eingabefelder noch benötigt werden, hängt von den Produkten ab, die Sie auswählen. Beim "Telefonverzeichnis" ist es sinnvoll, neben den absolut notwendigen Pflichtfeldern ein paar Eingaben mehr zu senden. Siehe Tabelle unten.
Im Eingabefeld "product" senden Sie einen oder mehrere Produkt-Schlüssel mit Komma getrennt.
Produktschlüssel und Pflichtfelder
Product Key | Produkt | Anrede/ salutation | Titel/ title | Vorname/ firstname | Nachname/ lastname | Strasse/ street | Hnr/ hno | PLZ/ zip | Ort/ city | Land/ country | Telefon/ phone | EMail/ | UmsStID/ vatin |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
SC + SCX | Adress-Check DACH | X | X | X | X | X | |||||||
SC_INT * | Adress-Check World | X | O | X | X | X | |||||||
FK | Fake-Check | X | X | O | O | O | O | O | |||||
NC | Namens-Check B2C | O | O | X | X | O | |||||||
EM + EMX | E-Mail-Check | X | |||||||||||
PB | Telefonverzeichnis (Preis je Anfrage) | O | X | X | O | X | X | X | O | ||||
PBT | Telefonverzeichnis (Preis auf Trefferbasis) | O | X | X | O | X | X | X | O | ||||
VATID | Ust-IdNr-Check | X | |||||||||||
VATIDX | Ust-IdNr-Check extended | X |
* Erweiterte Eingabefelder für Product Key "SC_INT", Version 2
Product Key | Produkt | state | zip_add_on | location | house_estate | sub_building_name | organisation |
---|---|---|---|---|---|---|---|
SC_INT | Adress-Check World | USA: state ist Pflichtfeld, z.B. "TX" oder Texas | USA: 4stellige PLZ(add on) | Strassenzusatz, länderabhängig | Gebäudebe- zeichnung, länderabhängig | CA + UK: Block-Bezeichnung in großen Gebäuden | optional, länder- abhängig |
X = Pflichtfeld, O = optionales Eingabefeld zur Ergebnisoptimierung, OX = klare Empfehlung, das Feld mitzuliefern.
Die Hausnummer (hno) kann auch im Feld street enthalten sein. Wir liefern das Ergebnis immer getrennt.
Die Telefonnummer (phone) bitte in einem Feld (Vorwahl- und Rufnummer) liefern. Ohne oder mit beliebigen Trennzeichen. Mit oder ohne Ländervorwahl. Falls nötig, ermitteln wir diese anhand des Länderkennzeichens (country). Für Deutschland muss keine Ländervorwahl angegeben werden (stört aber nicht). Ansonsten bitte die Ländervorwahl im Format +49 oder 0049 mitliefern, falls vorhanden. Ansonsten hängen wird diese an.
Feld Land (country) Ländercode, bitte mit 2- oder 3-stelligem ISO-3166-Code (alpha) versehen: DE, AT, CH, ... oder DEU, AUT, CHE. Info: Wenn Sie das Land leer lassen, versuchen wir es innerhalb der DACH-Region zu ermitteln.
* Den Adress-Check World (SC_INT) gibt es in 2 Varianten. Version 1 entspricht bei Ein- und Ausgabe dem "Adress-Check Light" (SC, vor 2023-04). Version 2 ermöglicht erweiterte Ein- und Ausgabefelder, die länderabhängig benötigt werden. Außerdem wird hier bei mehrdeutigen Adressen eine Vorschlagsliste mit mehreren Responses ausgegeben (array). Aufruf URL je Version siehe unten.
Eingabefelder
'apicid' => 1000 /* API Consumer ID, siehe Mein Konto */
'apikey' => 'ffffffff-ffff-ffff-ffff-ffffffffffff' /* API Key, siehe Mein Konto */
'product' => 'SC,FK,NC,EM,PB,PC', /* hier mit Komma getrennt die gewünschten Tests senden */
'salutation' => 'Herr',
'title' => 'Prof. Dr.',
'firstname' => 'Max',
'lastname' => 'Mustermann',
'street' => 'Teststr.',
'hno' => '9',
'zip' => '12345',
'city' => 'Entenhausen',
'country' => 'DE',
'phone' => '01234/56789',
'email' => 'test@test-email.de',
'date_of_birth' => '19701231',
'vatin' => 'IT-006/347/812 34',
Ausgabefelder
/** Basic Version (ehemaliger Adress-Check light, bis März 2023)
* https://api.adresslabor.de/v1/de/check
*
* "Adress-Check light" (sc, street-check)
* "Adress-Check World v1" (sc_int, street-check international))
* max. eine Response pro Request
*/
"sc": [
{
"trafficlight": "gruen",
"resulttext": "OK, sicher gefunden",
"resultcode": "13212",
"points": 99,
"recordno": 1,
"zip": "63768",
"city": "Hösbach",
"district": "",
"street": "Kolpingstr.",
"hno": "14"
}
],
"credits": 4701.00
}
/* Upgrade-Versionen ab April 2023
* https://api.adresslabor.de/v3/de/check
* "Adress-Check DACH (Basic + Extended)" (sc, scx)
* "Adress-Check World v1" (sc_int light Version)
* max. eine Response pro Request
*/
"sc": [
{
"trafficlight": "gruen",
"resulttext": "OK, sicher gefunden",
"resultcode": "13212",
"points": 99,
"recordno": 1,
"country": "DE",
"zip": "63768",
"city": "Hösbach",
"place_affix": "",
"district": "",
"street": "Kolpingstr.",
"hno": "14",
"ziptype": "Zustell-PLZ",
"state_key": "09",
"state": "Bayern",
"municipalitykey": "09671130"
}
],
"credits": 4710.00
}
"scx": [
{
"trafficlight": "gruen",
"resulttext": "OK, sicher gefunden",
"resultcode": "13212",
"points": 99,
"recordno": 1,
"country": "DE",
"zip": "63768",
"city": "Hösbach",
"place_affix": "",
"district": "",
"street": "Kolpingstr.",
"hno": "14",
"ziptype": "Zustell-PLZ",
"state_key": "09",
"state": "Bayern",
"county": "Aschaffenburg",
"administrative_district": "Unterfranken",
"municipality": "Hösbach, Markt",
"municipalitykey": "09671130",
"location_size_class": "10.001 - 20.000",
"geo_x_coord": "9.1954",
"geo_y_coord": "49.999826",
"geo_quality": "STR",
"grand_recipient": ""
}
],
"credits": 4711.00
/** "Adress-Check World v2" (sc_int, extended response))
* https://api.adresslabor.de/v2/de/check
* Array mit Vorschlagsliste bei mehrdeutigen Treffern möglich
*/
[scint] => Array (
[0] => (
points] => 80
[resulttext] => unsicher (70-89 Pkt.) o. nur PLZ+Ort
[resulttext_details] =>
[trafficlight] => gelb
[resultcode] => 11713
[recordno] => 1
[res_deliverability] => OK
[zip_type] => Zustell-Adresse
[street] => Teststr.
[hno] => 18
[street_hno] => Teststr. 18
[zip] => 12345
[zip_add_on] =>
[city] => Entenhausen
[district] => Vorstadt
[country_iso_2] => DE
[country_full] => Deutschland
[region_code] => 09
[region] => Bayern
[state_code] =>
[state] =>
[city_long] => Entenhausen
[street_short] => Teststr.
[pobox_zip] =>
[pobox_city] =>
[pobox_no] =>
[pobox_state] =>
[special_zip] =>
[special_city] =>
[special_country] =>
[building_name] =>
[sub_build_name] =>
[organisation] =>
[location] =>
)
)
/* Die folgenden Responses kommen per Request an beide URLs:
* https://api.adresslabor.de/v3/de/check
* https://api.adresslabor.de/v1/de/check
*/
/* "Fake-Check" (fk)
*/
[fk] => (
[resulttext] => OK
[trafficlight] => gruen
)
/* "Namens-Check B2C" (nc)
*/
[nc] => (
[resulttext] => OK (keine Veränderungen)
[trafficlight] => gruen
[salutation] => Herr
[title] => Dr.
[firstname] => Max
[lastname] => Mustermann
)
/* "E-Mail-Check" (em) und "E-Mail-Check extended" (emx)
*/
[em] => (
[resulttext] => Top-Level-Domain ist ungültig
[trafficlight] => rot
)
/* "Telefonverzeichnis" (pb, pbt)
*/
[pb] => Array (
[0] => (
[points] => 3
[zip] => 12345
[city] => Entenhausen
[street] => Teststr.
[hno] => 9
[phone] => 01234/56789
[resulttext] => Telefonnr. mit abweichenden/fehlenden Daten gefunden
[trafficlight] => gelb
[recordno] => 1
[name] => Mustermax GmbH & Co.KG
[country] => DE
)
)
/* "Ust-Nr.-Check" (vatid, vatidx )
*/
[vatid] =>
(
[vatNumber] => IT00634781234
[resulttext] => OK
[trafficlight] => gruen
[address] => VIA AURELIO SAFFI 15 25121 BRESCIA BS
[name] => SO.PAR SRL
)
/* Info: verbleibende Credits jeweils
*/
[credits] => 10099
Ergebnisse Adress-Check
resulttext | trafficlight | Bedeutung |
---|---|---|
OK | gruen | Adresse korrekt, keine Änderungen |
OK, sicher gefunden | gruen | Adresse mit geringfügigen Abweichungen gefunden |
unsicher gefunden | gelb | Adresse mit größeren Abweichungen gefunden oder Hausnr. unbekannt. Oder Postfach außerhalb des bekannten Nummernbereichs. |
unsicher, PLZ und Ort OK | gelb | Nur PLZ und Ort gefunden, Packstation oder Sonderfälle in Österreich/ Schweiz, wo kleinere Orte manchmal keine Straßennamen haben. |
unsicher gefunden, Hausnr./ Postf. prüfen | gelb | PLZ, Ort und Straße gefunden, aber nicht das Gebäude (Hausnr.). Oder das Postfach liegt außerhalb des bekannten Nummernkreises. |
ungültig, PLZ und Ort OK | rot | PLZ und Ort gefunden, Straße nicht |
ungültig, mehrdeutig | rot | Falsche Adresse, es gibt mehrere, nicht eindeutige Möglichkeiten |
ungültig | rot | ungültige Adresse (oder noch nicht bekannt, Neubaugebiet) |
Bitte Eingabe prüfen | rot | Dubiose Eingabe (request), es findet keine Prüfung statt. Die Adresse sollte manuell geprüft werden. (Firmen-) Namen, E-Mail-Adressen oder sonstige unplausible Einträge in der Anfrage. |
Ergebniscode Adress-Check (5stellig)
Stelle im Code | Zahl | Bedeutung |
---|---|---|
1. Stelle = PLZ | 0 | PLZ nicht gefunden |
1 | PLZ bei request und response stimmt überein | |
2 | Erste 4 Stellen der PLZ stimmen überein | |
3 | Erste 3 Stellen der PLZ stimmen überein | |
4 | Erste 2 Stellen der PLZ stimmen überein | |
5 | Erste Stelle der PLZ stimmt überein | |
6 | Zahlendreher in PLZ | |
7 | PLZ geändert | |
8 | PLZ unvollständig eingegeben oder PLZ nicht geprüft, weil Request dubios ist. | |
9 | PLZ in request leer | |
2. Stelle = Ort | 0 | Ort nicht gefunden |
1 | Ort bei request und response stimmt überein | |
2 | Ort über Ortsteil gefunden | |
3 | Ort mit leichter Phonetik gefunden | |
4 | Ort mit Phonetik gefunden | |
7 | Ort geändert | |
8 | Ort nicht geprüft, Eingabe dubios. | |
9 | Ort in request leer | |
3. Stelle = Straße | 0 | Strasse nicht gefunden |
1 | Strasse in request und response identisch | |
2 | Strasse mit leichter Phonetik gefunden | |
3 | Strasse mit Phonetik gefunden | |
5 | Strasse war abgekürzt | |
6 | Strasse nicht geprüft/ Eingabe dubios oder Packstation | |
7 | Strasse geändert | |
8 | Strasse ist optional (Größempfänger-PLZ) | |
9 | Strasse in request leer | |
4. Stelle = Hausnummer | 0 | Hausnummer nicht gefunden oder Postfach |
1 | Hausnummer korrekt | |
2 | Hausnummernbereich ok | |
6 | Hausnummer nicht geprüft/ Eingabe dubios oder Packstation | |
8 | Hausnummer ist ein Bereich von ... bis .. | |
9 | Hausnummer war leer/ konnte nicht aus Strasse extrahiert werden. | |
5. Stelle = result | 1 | OK (points = 100) |
2 | OK, sicher gefunden (points von 90 bis 99) | |
3 | unsicher gefunden (points von 70 bis 89) | |
4 | unsicher, PLZ+Ort OK, aber keine Strasse oder Postfach/ Packstation im request | |
5 | ungültig, PLZ+ Ort OK | |
6 | ungültig, mehrdeutig | |
8 | Bitte Eingabe prüfen. Dubiose Feldinhalte im Request. | |
9 | ungültig (points < 70) |
Ergebnisse Fake-Check
resulttext | trafficlight | Bedeutung |
---|---|---|
OK | gruen | OK, kein Fake gefunden. |
Fake-Warnung (Vorname)! | gelb | Vorname dubios, in Fake-Liste mit mittlerer Negativbewertung. |
Fake-Warnung (Vorname)! | rot | Vorname dubios, in Fake-Liste mit hoher Negativbewertung. |
Fake-Warnung (Nachname)! | gelb | Nachname dubios, in Fake-Liste mit mittlerer Negativbewertung. |
Fake-Warnung (Nachname)! | rot | Nachname dubios, in Fake-Liste mit hoher Negativbewertung. |
Fake-Warnung (Namenszeile)! | gelb | Kombi aus Vor- und Nachname dubios, in Fake-Liste mit mittlerer Negativbewertung. |
Fake-Warnung (Namenszeile)! | rot | Kombi aus Vor- und Nachname dubios, in Fake-Liste mit hoher Negativbewertung. |
Hinweis für "trafficlight" gelb: Hier sind unter anderem Vor- und Nachnamen von Prominenten hinterlegt. Dabei kann es sich um "Allerweltsnamen" handeln, die im deutschsprachigem Raum häufig vorkommen. "Michael Schumacher" z.B. haben wir deshalb aus der Fake-Liste heraus genommen. Namen, die seltener vorkommen, aber oft auch weniger bekannt sind, sind noch enthalten. Entscheiden Sie selbst, wie Sie mit diesen Fake-Warnungen umgehen möchten. Wir haben keine eindeutige Empfehlung.
Ergebnisse Namens-Check (B2C)
resulttext | trafficlight | Bedeutung |
---|---|---|
OK | gruen | Alles wie Eingabe |
Korrektur durchgeführt | gelb | Abweichungen zwischen Ein- und Ausgabe: Groß-Kleinschreibweise oder Vor-und Nachnamen getauscht oder Anrede ergänzt/ korrigiert oder Titel extrahiert. |
Dubiose Eingabe | rot | Die Eingabe der Namensfelder enthält Bestandteile der Adresse, Dopplungen oder eine E-Mail Adresse. Es werden keine Änderungen vorgenommen. |
Ergebnisse E-Mail-Check und erweiterter E-Mail-Check
resulttext | trafficlight |
---|---|
OK | gruen |
E-Mail syntaktisch OK, Mailserver mag jedoch Empfänger nicht (E-Mail-Postfach-Prüfung). * | gelb |
E-Mail syntaktisch OK. E-Mail-Postfach-Prüfung nicht eindeutig. Blacklisting oder ungültiger Empfänger. * | gelb |
E-Mail syntaktisch OK. Mailserver lässt die E-Mail-Postfach-Prüfung nicht zu (Spam-Filter). * | gelb |
Mail-Server antwortet auch nach 30 Sekunden noch nicht (E-Mail-Postfach-Prüfung) | gelb |
Domain weist auf Wegwerf-Email-Adresse hin | gelb |
E-Mail OK, aber dubios | gelb |
E-Mail OK, aber auf Top Level Domain Ebene | gelb |
E-Mail OK, aber Top Level Domain ist numerisch | gelb |
E-Mail OK, aber enthält Teil in Anführungszeichen | gelb |
E-Mail OK, aber enthält Kommentar | gelb |
E-Mail OK, aber enthält fließendes Leerzeichen | gelb |
E-Mail OK, aber mit numerischer Adresse, keine Domain | gelb |
E-Mail OK, aber enthält ein :: das nur eine Nullgruppe auslässt | gelb |
E-Mail ist ungültig | rot |
E-Mail ist zu lang | rot |
E-Mail hat kein @-Zeichen | rot |
Ungültiges Zeichen im lokalen Teil | rot |
E-Mail hat keinen lokalen Teil | rot |
E-Mail hat keinen Domain-Teil | rot |
E-Mail beginnt oder endet mit einem Punkt oder hat 2 Punkte hintereinander | rot |
E-Mail beinhaltet ungültige Zeichen in einem Kommentar | rot |
E-Mail beinhaltet ein Zeichen, das escaped werden muss, aber nicht ist | rot |
Der lokale Teil der E-Mail ist zu lang | rot |
Die numerische Adresse hat ein falsches Präfix | rot |
Der Domain-Teil enhält ein leeres Element | rot |
Der Domain-Teil enhält ein Element, das zu lang ist | rot |
Der Domain-Teil enhält ein ungültiges Zeichen | rot |
Der Domain-Teil ist zu lang | rot |
Die IPv6-Adresse enthält zu viele Gruppen | rot |
Die IPv6-Adresse enthält die falsche Anzahl von Gruppen | rot |
Die IPv6-Adresse enthält eine falsche Gruppe von Zeichen | rot |
Die IPv6-Adresse enthält zuviele :: Sequenzen | rot |
Die IPv6-Adresse beginnt mit einem einzelnen Punkt | rot |
Die IPv6-Adresse endet mit einem einzelnen Punkt | rot |
Top-Level-Domain ist ungültig | rot |
Die Prüfung EMX (E-Mail-Check extended = Postfach-Check) nimmt zusätzlich Kontakt zum Mailserver auf und prüft, ob eine E-Mail zugestellt werden kann. Dies dauert einen Augenblick länger als die reine Syntax-Prüfung (EM).
* Info: Kann auch bedeuten, dass der Provider die Prüfung nicht zulässt oder Adresslabor generell blockt (Blacklisting).
Ergebnisse Telefonverzeichnis
resulttext | points | trafficlight | Bedeutung |
---|---|---|---|
OK, Person und Telefonnr. stimmen überein | 100 | gruen | Bestätigung einer Person durch Telefonverzeichnis |
OK, Haushalt oder Firma und Telefonnr. stimmen überein | 90 | gruen | Bestätigung des Haushalts oder der Firma mit übereinstimmender Telefonnummer |
Person mit abweichender Telefonnr. gefunden | 80 | gruen | Telefonnummer kann angereichert werden. |
Telefonnr. gefunden, Inverssuche von Teilnehmer verweigert | 80 | gruen | Telefonnummer ist eingetragen, der Teilnehmer hat aber der Rückwärtssuche widersprochen. Adressdaten und Name dürfen nicht zurückgemeldet werden. |
Haushalt oder Firma mit abweichender Telefonnr. gefunden | 70 | gruen | Telefonnummer (Festnetz) kann angereichert werden. Vorsicht bei Mobilnummern |
Telefonnr. mit abweichenden/fehlenden Daten gefunden | 60 | gruen | Eintrag über Reverse-Suche gefunden, aber mit abweichender oder unvollständiger Adresse |
Person in Strasse gefunden | 50 | gruen | Eindeutige Zuordnung nicht möglich |
Unsichere Treffer gefunden | 40, 30, 20, 10 | gelb | Eindeutige Zuordnung nicht möglich |
Keinen Eintrag im Telefonverzeichnis gefunden | 0 | rot | Nichts gefunden |
Ergebnisse Ust-IdNr-Check
resulttext | trafficlight | Bedeutung |
---|---|---|
OK | gruen | Ust-IdNr. syntaktisch korrekt und vom jeweiligen Land als vergeben und gültig eingestuft (nur VATIDX) |
Syntaktisch OK | gelb | Prüfziffer und Format OK |
Prüfziffer oder Format falsch | rot | Prüfziffer oder Format falsch |
Ungültig | rot | Syntaktisch ok, jedoch wurde die Ust-IdNr. vom vergebenden Land als ungültig eingestuft |
Die Prüfung "VATIDX" (Ust-IdNr.-Check extended) fragt zusätzlich beim jeweils zuständigen EU-Land an, ob die Nummer gültig und vergeben ist. In den meisten Ländern erhält man auch den zur Umsatzsteuer-ID zughörigen Firmennamen und Adresse (Ausnahmen sind z.B. Deutschland und Frankreich). Ist der jeweilige Dienst des Landes zur Zeit online nicht erreichbar, wird nur die Prüfung "VATID" ausgeführt. Das beste Ampel-Ergebnis ist in dem Fall "gelb".