Skip to main content

Documentation Rest API + Mass check


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 KeyProductsalutationtitlefirstnamelastnamestreethnozipcitycountry (ISO Codes*)phoneemailvatin
SC + SCXAddress Check DACH    XXXXX   
SC_INT *Address Check World    XOXXX   
FKFake Check  XXOOOOO   
NCName Check B2COOXX    O   
EM + EMXEmail Check/ Email Check extended           X 
PBTelephone directory (price per request)  OXXOXXXO  
PBTTelephone directory (price on hit basis)  OXXOXXXO  
VATIDVAT number check           X
VATIDXVAT number check extended           X

* Extended input fields for Product Key "SC_INT", Version 2

Product KeyProduktstatezip_add_onlocationhouse_estatesub_building_nameorganisation
SC_INTAdsress-Check WorldUSA: state is mandatory field,
e.g. "TX" or Texas
USA: 4stellar zip (add on)Road additive, country dependentBuilding designation, country-dependentCA + UK: Block designation
in large

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.

Input fields

'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' => '',
'date_of_birth' => '19701231',
'vatin' => 'IT-006/347/812 34',

Output fields

/** Basic version (former address check light)
 *	"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

 *		"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))
 *  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:
/*	"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
Address correct, no changes
OK, sicher gefunden
OK, found safe hit
Address found with slight changes
Unsicher gefunden
unsafe hit 
Address(es) found with major changes or house no. unknown.
unsicher gefunden, Hausnr./ Postf. prüfen
unsafe hit, check housenumber or P.O. box 


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

Only zip code and city found, packing station or special cases in Austria/ Switzerland,
where smaller places sometimes don´t have street names.

Ungültig, PLZ und Ort OK
invalid, zip code and city OK


Zip code and city found, but not the street.
Ungültig, mehrdeutig
invalid, ambiguous
Wrong address, there are several ambiguous possibilities
Invalid address (or not yet known, new construction area)
Bitte Eingabe prüfen
Please check input
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 codeNumberMeaning
1. digit = zip code0ZIP code not found
 1Zip code for request and response matches
 2First 4 digits of the postal code match
 3First 3 digits of the postal code match
 4First 2 digits of the postal code match
 5First digit of the postal code matches
 6Numerical error in postal code
 7Zip code changed
 8Zip code entered incompletely or zip code not checked because request is dubious.
 9No zip code in request
2nd digit = city0Location not found
 1Location of request and response matches
 2Location found via district
 3Location found with slight phonetics
 4Location found with phonetics
 7Location changed
 8Location not checked, input dubious.

No location in request

3rd digit = street0Street not found
 1Street in request und response identical
 2Street with light phonetics found
 3Street with phonetics found
 5Street was abbreviated
 6Street not checked/ input dubious or german "Packstation"
 7Street changed
 8Street is optional (large recipient postcode)
 9No street in request
4th digit = house number0House number not found or PO Box
 1House number correct
 2House number range ok
 6House number not checked/ entry dubious or german "Packstation"
 8House number is a range from ... to ...
 9House number was blank/ could not be extracted from street.
5th digit = result1OK (points = 100)
 2OK, found safe (points from 90 to 99)
 3found unsafe (points from 70 to 89)
 4unsure, postcode+location OK, but no street or PO box/packing station in request
 5invalid, postcode+ city OK
 6invalid, ambiguous
 8Please check input. Dubious field contents in the request.
 9invalid (points < 70)

Results Fake Check

OKgruenOK, no fake found. (gruen = green)
Fake-Warnung (Vorname)!gelbFirst name dubious, in fake list with medium negative rating. (gelb = yellow)
Fake-Warnung (Vorname)!rotFirst name dubious, in fake list with high negative rating. (rot = red)
Fake-Warnung (Nachname)!gelbSurname dubious, in fake list with medium negative rating. (gelb = yellow)
Fake-Warnung (Nachname)!rotSurname dubious, in fake list with high negative rating. (rot = red)
Fake-Warnung (Namenszeile)!gelbCombination of first and last name dubious, in fake list with medium negative rating. (gelb = yellow)
Fake-Warnung (Namenszeile)!rotCombination 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)

OKgruenOK. Everything as input
Korrektur durchgeführtgelbCorrection made. Discrepancies between input and output:
Capitalisation or first and last names swapped or salutation added/corrected or title extracted.
Dubiose EingaberotDubious 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

OKgruen (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

OK, Person und Telefonnr. stimmen überein100gruen (green)Confirmation of a person by telephone directory
OK, Haushalt oder Firma und Telefonnr. stimmen überein90gruen (green)Confirmation of the household or company with matching telephone number
Person mit abweichender Telefonnr. gefunden80gruen (green)Telephone number can be enriched.
Telefonnr. gefunden, Inverssuche von Teilnehmer verweigert80gruen (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. gefunden70gruen (green)Telephone number (landline) can be enriched. Caution with mobile numbers
Telefonnr. mit abweichenden/fehlenden Daten gefunden60gruen (green)Entry found via reverse search, but with deviating or incomplete address
Person in Strasse gefunden50gruen (green)Clear assignment not possible
Unsichere Treffer gefunden40, 30, 20, 10gelb (yellow)Clear assignment not possible
Keinen Eintrag im Telefonverzeichnis gefunden0rot (red)Nothing found

Results check VAT-No.

OKgruenVAT No. syntactically correct and classified as assigned and valid by the respective country (only VATIDX)
Syntaktisch OKgelbCheck digit and format OK
Prüfziffer oder Format falschrotWrong check digit or format
UngültigrotSyntactically 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".

Example codes