Documentation Rest API + Mass check
General
With your free registration you will receive your access data, your API customer ID ("apicid") and the api key ("apikey") under "My account". You send us these in your requests.
Which input fields are still required depends on the products you select. In the case of the "telephone directory" it makes sense to send a few more entries in addition to the absolutely necessary mandatory fields. See the table below.
In the input field "product" you send one or more product keys separated by commas.
Product keys and mandatory fields
| Product Key | Product | salutation | title | firstname | lastname | street | hno | zip | city | country (ISO Codes*) | phone | vatin | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SC + SCX | Address Check DACH | X | X | X | X | X | |||||||
| SC_INT * | Address Check World | X | O | X | X | X | |||||||
| FK | Fake Check | X | X | O | O | O | O | O | |||||
| NC | Name Check B2C | O | O | X | X | O | |||||||
| EM + EMX | Email Check/ Email Check extended | X | |||||||||||
| PB | Telephone directory (price per request) | O | X | X | O | X | X | X | O | ||||
| PBT | Telephone directory (price on hit basis) | O | X | X | O | X | X | X | O | ||||
| VATID | VAT number check | X | |||||||||||
| VATIDX | VAT number check extended | X |
* Extended input fields for Product Key "SC_INT", Version 2
| Product Key | Produkt | state | zip_add_on | location | house_estate | sub_building_name | organisation |
|---|---|---|---|---|---|---|---|
| SC_INT | Adsress-Check World | USA: state is mandatory field, e.g. "TX" or Texas | USA: 4stellar zip (add on) | Road additive, country dependent | Building designation, country-dependent | CA + UK: Block designation in large buildings | optional, country- dependent |
X = mandatory field, O = optional input field for result optimization, OX = clear recommendation to include the field.
The house number (hno) can also be included in the street field. We always deliver the result separately.
Please supply the phone number (phone) in one field (area code and phone number). Without or with any separator. With or without country code. If necessary, we will determine the country code. For Germany there is no need to specify a country code (but don't bother). Otherwise please include the country code in the format +49 or 0049, if available. Otherwise we append it.
Field Country code: please provide with 2- or 3-digit ISO-3166 code (alpha): DE, AT, CH, ... or DEU, AUT, CHE. Info: If you leave the country blank, we will try to determine it within the DACH region.
* The Address-Check World (SC_INT) is available in 2 versions. Version 1 corresponds to the address check light (SC, befor 2023-04) for input and output. Version 2 allows extended input and output fields, which are needed depending on the country. In addition, a suggestion list with several responses is output here for ambiguous addresses (array). Call URL per version see below.
'apicid' => 1000 /* API Consumer ID, see My account */
'apikey' => 'ffffffff-ffff-ffff-ffff-ffffffffffff' /* API Key, see My account */
'product' => 'SC,FK,NC,EM,PB,PC', /* Here you can send the desired tests, separated by commas. */
'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',
/** Basic version (former address check light)
* https://api.adresslabor.de/v1/de/check
*
* "Adress-Check light" (sc, street-check)
* "Adress-Check World v1" (sc_int, street-check international))
* max. one response for address-checks and all other checks
*/
"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 versions from 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. one response per 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
/** "Address-Check World v2" (sc_int, extended response))
* https://api.adresslabor.de/v2/de/check
* Array with suggestion list possible for ambiguous addresses
*/
[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] =>
)
)
/* The following responses come per request to both URLs:
* https://api.adresslabor.de/v3/de/check
* https://api.adresslabor.de/v1/de/check
*/
/* "Fake-Check" (fk)
*/
[fk] => (
[resulttext] => OK
[trafficlight] => gruen
)
/* "Name-Check B2C" (nc)
*/
[nc] => (
[resulttext] => OK (keine Veränderungen)
[trafficlight] => gruen
[salutation] => Herr
[title] => Dr.
[firstname] => Max
[lastname] => Mustermann
)
/* "EMail-Check" (em) and "EMail-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
)
)
/* "VATID-Check" (vatid, vatidx )
*/
[vatid] =>
(
[vatNumber] => IT00634781234
[resulttext] => OK
[trafficlight] => gruen
[address] => VIA AURELIO SAFFI 15 25121 BRESCIA BS
[name] => SO.PAR SRL
)
/* Info: remaining credits each at the end
*/
[credits] => 3900
Address check results
| Resulttext origin german translated | Trafficlight translated | Meaning |
|---|---|---|
| OK | gruen green | Address correct, no changes |
| OK, sicher gefunden OK, found safe hit | gruen green | Address found with slight changes |
| Unsicher gefunden unsafe hit | gelb yellow | Address(es) found with major changes or house no. unknown. |
| unsicher gefunden, Hausnr./ Postf. prüfen unsafe hit, check housenumber or P.O. box | gelb | Address found (zip code, city & street), but not the building (houseno.) or the P.O. box is outside the known sequence. |
| Unsicher, PLZ und Ort OK unsure, zip code and city OK | gelb yellow | Only zip code and city found, packing station or special cases in Austria/ Switzerland, |
Ungültig, PLZ und Ort OK | rot | Zip code and city found, but not the street. |
| Ungültig, mehrdeutig invalid, ambiguous | rot red | Wrong address, there are several ambiguous possibilities |
| Ungültig invalid | rot red | Invalid address (or not yet known, new construction area) |
| Bitte Eingabe prüfen Please check input | rot red | Dubious input (request), no check takes place. The request should be checked manually. Email addresses, (company) names or other content may have been included. |
Result code address check (5 digits)
| Place in code | Number | Meaning |
|---|---|---|
| 1. digit = zip code | 0 | ZIP code not found |
| 1 | Zip code for request and response matches | |
| 2 | First 4 digits of the postal code match | |
| 3 | First 3 digits of the postal code match | |
| 4 | First 2 digits of the postal code match | |
| 5 | First digit of the postal code matches | |
| 6 | Numerical error in postal code | |
| 7 | Zip code changed | |
| 8 | Zip code entered incompletely or zip code not checked because request is dubious. | |
| 9 | No zip code in request | |
| 2nd digit = city | 0 | Location not found |
| 1 | Location of request and response matches | |
| 2 | Location found via district | |
| 3 | Location found with slight phonetics | |
| 4 | Location found with phonetics | |
| 7 | Location changed | |
| 8 | Location not checked, input dubious. | |
| 9 | No location in request | |
| 3rd digit = street | 0 | Street not found |
| 1 | Street in request und response identical | |
| 2 | Street with light phonetics found | |
| 3 | Street with phonetics found | |
| 5 | Street was abbreviated | |
| 6 | Street not checked/ input dubious or german "Packstation" | |
| 7 | Street changed | |
| 8 | Street is optional (large recipient postcode) | |
| 9 | No street in request | |
| 4th digit = house number | 0 | House number not found or PO Box |
| 1 | House number correct | |
| 2 | House number range ok | |
| 6 | House number not checked/ entry dubious or german "Packstation" | |
| 8 | House number is a range from ... to ... | |
| 9 | House number was blank/ could not be extracted from street. | |
| 5th digit = result | 1 | OK (points = 100) |
| 2 | OK, found safe (points from 90 to 99) | |
| 3 | found unsafe (points from 70 to 89) | |
| 4 | unsure, postcode+location OK, but no street or PO box/packing station in request | |
| 5 | invalid, postcode+ city OK | |
| 6 | invalid, ambiguous | |
| 8 | Please check input. Dubious field contents in the request. | |
| 9 | invalid (points < 70) |
Results Fake Check
| Resulttext | Trafficlight | Meaning |
|---|---|---|
| OK | gruen | OK, no fake found. (gruen = green) |
| Fake-Warnung (Vorname)! | gelb | First name dubious, in fake list with medium negative rating. (gelb = yellow) |
| Fake-Warnung (Vorname)! | rot | First name dubious, in fake list with high negative rating. (rot = red) |
| Fake-Warnung (Nachname)! | gelb | Surname dubious, in fake list with medium negative rating. (gelb = yellow) |
| Fake-Warnung (Nachname)! | rot | Surname dubious, in fake list with high negative rating. (rot = red) |
| Fake-Warnung (Namenszeile)! | gelb | Combination of first and last name dubious, in fake list with medium negative rating. (gelb = yellow) |
| Fake-Warnung (Namenszeile)! | rot | Combination of first and last name dubious, in fake list with high negative rating. (rot = red) |
Note for "trafficlight" gelb (yellow): Among other things, first and last names of celebrities are stored here. These may be "common names" that occur frequently in German-speaking countries. We have therefore removed "Michael Schumacher" from the fake list. Names that occur less frequently, but are often less well-known, are still included. Decide for yourself how you want to deal with these fake warnings. We do not have a clear recommendation.
Name Check Results (B2C)
| Resulttext | Trafficlight | Meaning |
|---|---|---|
| OK | gruen | OK. Everything as input |
| Korrektur durchgeführt | gelb | Correction made. Discrepancies between input and output: Capitalisation or first and last names swapped or salutation added/corrected or title extracted. |
| Dubiose Eingabe | rot | Dubious input. The entry of the name fields contains components of the address, duplicates or an e-mail address. No changes are made. |
Results of e-mail check and extended e-mail check
| Resulttext | Trafficlight |
|---|---|
| OK | gruen (green) |
E-Mail syntaktisch OK, Mailserver mag jedoch Empfänger nicht (E-Mail-Postfach-Prüfung). * E-mail syntactically OK, but mail server does not like recipient (e-mail box check).* | gelb (yellow) |
E-Mail syntaktisch OK. E-Mail-Postfach-Prüfung nicht eindeutig. Blacklisting oder ungültiger Empfänger. * E-mail syntactically OK. E-mail box check not clear. Blacklisting or invalid recipient. * | gelb (yellow) |
E-Mail syntaktisch OK. Mailserver lässt die E-Mail-Postfach-Prüfung nicht zu (Spam-Filter). * E-mail syntactically OK. Mail server does not allow the e-mail box check (spam filter). * | gelb (yellow) |
Mail-Server antwortet auch nach 30 Sekunden noch nicht (E-Mail-Postfach-Prüfung). Mail server still not responding after 30 seconds (e-mail box check). | gelb (yellow) |
Domain weist auf Wegwerf-Email-Adresse hin. Domain indicates disposable email address. | gelb (yellow) |
| E-Mail OK, aber dubios. E-mail OK, but dubious. | gelb (yellow) |
| E-Mail OK, aber auf Top Level Domain Ebene. Email OK, but at top level domain level. | gelb (yellow) |
| E-Mail OK, aber Top Level Domain ist numerisch. Email OK, but Top Level Domain is numeric. | gelb (yellow) |
| E-Mail OK, aber enthält Teil in Anführungszeichen. Email OK, but contains part in inverted commas. | gelb (yellow) |
| E-Mail OK, aber enthält Kommentar. E-mail OK, but contains comment. | gelb (yellow) |
| E-Mail OK, aber enthält fließendes Leerzeichen. Email OK, but contains floating space. | gelb (yellow) |
| E-Mail OK, aber mit numerischer Adresse, keine Domain. E-mail OK, but with numeric address, no domain. | gelb (yellow) |
| E-Mail OK, aber enthält ein :: das nur eine Nullgruppe auslässt. E-mail OK, but contains a :: that omits only one zero group. | gelb (yellow) |
| E-Mail ist ungültig. E-mail is invalid. | rot (red) |
| E-Mail ist zu lang. E-mail is too long. | rot (red) |
| E-Mail hat kein @-Zeichen. E-mail has no @ sign. | rot (red) |
| Ungültiges Zeichen im lokalen Teil. Invalid character in the local part. | rot (red) |
| E-Mail hat keinen lokalen Teil. E-mail has no local part. | rot (red) |
| E-Mail hat keinen Domain-Teil. E-mail has no domain part. | rot (red) |
| E-Mail beginnt oder endet mit einem Punkt oder hat 2 Punkte hintereinander. E-mail begins or ends with a dot or has 2 dots in a row. | rot (red) |
| E-Mail beinhaltet ungültige Zeichen in einem Kommentar. Email contains invalid characters in a comment. | rot (red) |
| E-Mail beinhaltet ein Zeichen, das escaped werden muss, aber nicht ist. Email contains a character that must be escaped but is not. | rot (red) |
| Der lokale Teil der E-Mail ist zu lang. The local part of the email is too long. | rot (red) |
| Die numerische Adresse hat ein falsches Präfix. The numeric address has an incorrect prefix. | rot (red) |
| Der Domain-Teil enhält ein leeres Element. The domain part contains an empty element. | rot (red) |
| Der Domain-Teil enhält ein Element, das zu lang ist. The domain part contains an element that is too long. | rot (red) |
| Der Domain-Teil enhält ein ungültiges Zeichen. The domain part contains an invalid character. | rot (red) |
| Der Domain-Teil ist zu lang. The domain part is too long. | rot (red) |
| Die IPv6-Adresse enthält zu viele Gruppen. The IPv6 address contains too many groups. | rot (red) |
| Die IPv6-Adresse enthält die falsche Anzahl von Gruppen. The IPv6 address contains the wrong number of groups. | rot (red) |
| Die IPv6-Adresse enthält eine falsche Gruppe von Zeichen. The IPv6 address contains an incorrect group of characters. | rot (red) |
| Die IPv6-Adresse enthält zuviele :: Sequenzen. The IPv6 address contains too many :: sequences. | rot (red) |
| Die IPv6-Adresse beginnt mit einem einzelnen Punkt. The IPv6 address begins with a single dot. | rot (red) |
| Die IPv6-Adresse endet mit einem einzelnen Punkt. The IPv6 address ends with a single dot. | rot (red) |
| Top-Level-Domain ist ungültig. Top-level domain is invalid. | rot (red) |
The check EMX (e-mail check extended = mailbox check) additionally contacts the mail server and checks whether an e-mail can be delivered. This takes a moment longer than the pure syntax check (EM).
* Info: Can also mean that the provider does not allow the check or blocks address labs in general (blacklisting).
Results telephone directory
| Resulttext | Points | Trafficlight | Meaning |
|---|---|---|---|
| OK, Person und Telefonnr. stimmen überein | 100 | gruen (green) | Confirmation of a person by telephone directory |
| OK, Haushalt oder Firma und Telefonnr. stimmen überein | 90 | gruen (green) | Confirmation of the household or company with matching telephone number |
| Person mit abweichender Telefonnr. gefunden | 80 | gruen (green) | Telephone number can be enriched. |
| Telefonnr. gefunden, Inverssuche von Teilnehmer verweigert | 80 | gruen (green) | Telephone number is entered, but the participant has objected to the reverse search. Address data and name must not be reported back. |
| Haushalt oder Firma mit abweichender Telefonnr. gefunden | 70 | gruen (green) | Telephone number (landline) can be enriched. Caution with mobile numbers |
| Telefonnr. mit abweichenden/fehlenden Daten gefunden | 60 | gruen (green) | Entry found via reverse search, but with deviating or incomplete address |
| Person in Strasse gefunden | 50 | gruen (green) | Clear assignment not possible |
| Unsichere Treffer gefunden | 40, 30, 20, 10 | gelb (yellow) | Clear assignment not possible |
| Keinen Eintrag im Telefonverzeichnis gefunden | 0 | rot (red) | Nothing found |
Results check VAT-No.
| Resulttext | trafficlight | Bedeutung |
|---|---|---|
| OK | gruen | VAT No. syntactically correct and classified as assigned and valid by the respective country (only VATIDX) |
| Syntaktisch OK | gelb | Check digit and format OK |
| Prüfziffer oder Format falsch | rot | Wrong check digit or format |
| Ungültig | rot | Syntactically ok, but the VAT number was classified as invalid by the issuing country. |
The "VATIDX" check (VAT-No. check extended) also asks the relevant EU country whether the number is valid and assigned. In most countries you also receive the company name and address associated with the VAT ID (exceptions are e.g. Germany and France). If the respective service of the country is currently not available online, only the "VATID" check is carried out. The best traffic light result in this case is "yellow".