Doku API + Massenprüfung

Allgemeines

Mit Ihrer kostenlosen Anmeldung erhalten Sie unter "Mein Konto" Ihre persönlichen Schlüssel, die API-Customer-ID ("apicid") und Ihren Api-Key ("apikey"). Diese senden Sie uns in Ihren requests immer als Eingabefelder mit.

Welche Eingabefelder noch benötigt werden, hängt von den Tests ab, die Sie durchführen wollen. Bei manchen Tests, wie z.B. beim "Telefonverzeichnis", ist es sinnvoll, neben den absolut notwendigen Pflichtfeldern ein paar Eingaben mehr zu senden. Siehe Tabelle unten.

Wenn wir nur die Adresse haben, finden wir vielleicht die passende Telefonnummer dazu. Haben wir Adresse und Telefonnummer, können wir auch über die Reverse-Suche eine (abweichende) Adresse zu Ihrem Datensatz finden.

Zur Auswahl der Tests (Produkte) im Eingabefeld "product" ein oder mehrere der folgenden Produkt-Schlüssel, mit Komma getrennt, senden. Groß-/Kleinschreibweise spielt dabei keine Rolle.

 

X = Pflichtfeld, O = optionales Eingabefeld zur Ergebnisoptimierung, OX = dringende 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) bitte mit 2stelligem ISO-Code versehen (DE, AT, CH, ...).

Feld Geburtsdatum (date_of_birth) bitte im Format TT.MM.JJJJ liefern.

* Den Adress-Check Pro (SC_INT) gibt es in 2 Varianten. Version 1 entspricht bei Ein- und Ausgabe dem Adress-Check light (SC). 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

/* Ergebnisblock "Adress-Check light" (sc, street-check) */
/* Aufruf mit URL https://api.adresslabor.de/v1/de/check */
/* anlog für "Adress-Check Pro v1" (sc_int, street-check international)) */
/* max. eine Response pro Request */

[sc] => Array (
     [0] => (
        [trafficlight] => gruen
        [resulttext] => OK
        [resultcode] => 11111
        [points] => 100
        [recordno] => 1
        [zip] => 12345
        [city] => Entenhausen
        [district] =>
        [street] => Teststr.
        [hno] => 9

    )
)

/* "Adress-Check Pro v2" (sc_int, street-check international, erweiterte Ausgabe)) */
/* Aufruf mit URL https://api.adresslabor.de/v2/de/check */
/* Array mit Vorschlagsliste bei mehrdeutigen Adressen 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] =>

    )
)

/* Ergebnisblock "Fake-Check" (fk, fake-check) */

[fk] => (
   [resulttext] => OK
   [trafficlight] => gruen
)

/* Ergebnisblock "Namens-Check B2C" (nc, name-check) */

[nc] => (
    [resulttext] => OK (keine Veränderungen)
    [trafficlight] => gruen
    [salutation] => Herr
    [title] => Dr.
    [firstname] => Max
    [lastname] => Mustermann

)

/* Ergebnisblock "E-Mail-Check" (em, email-check) 
   und "erweiterter E-Mail-Check" (emx)             */

[em] => (
    [resulttext] => Top-Level-Domain ist ungültig
    [trafficlight] => rot
)

/* Ergebnisblock "Telefonverzeichnis" (pb, phonebook) */

[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
      )
)

/* Ergebnisblock "Telefon-Check" (pc, phone-check) */

[pc] => (
    [resulttext] => Rufnummer nicht gültig
    [trafficlight] => rot
)

/* Ergebnisblock "Ust-Nr.-Check" (vatid) 
   und "erweiterter Ust-Nr.-Check" (vatidx)             */
   
 [vatid] => 
        (
            [vatNumber] => IT00634781234
            [resulttext] => OK
            [trafficlight] => gruen
            [address] => VIA AURELIO SAFFI 15 25121 BRESCIA BS
            [name] => SO.PAR SRL
        )


/* verbleibende, verfügbare Credits */

[credits] => 10099

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.

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 Standardprüfung "EM".

* Info: Kann auch bedeuten, dass der Provider die Prüfung nicht zulässt oder Adresslabor generell blockt (Blacklisting).

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".