Enjyn KYC – API Dokumentation

Enjyn KYC ist eine deutsche Identitätsverifizierungslösung, die Ausweisprüfung, Liveness-Check und biometrische Gesichtserkennung in einer einfachen REST API vereint. Diese Dokumentation erklärt alle Funktionen, Endpunkte und Best Practices für die Integration.

💡 Tipp: Mit Enjyn KYC können Sie bis zu 100 Verifizierungen pro Monat kostenlos durchführen. Perfekt zum Testen und für kleinere Projekte.

Übersicht

Enjyn KYC bietet eine mehrstufige Identitätsprüfung:

• Dokumentenprüfung: Automatische OCR-Erkennung von Personalausweisen und Reisepässen aus 33 Ländern (Deutschland voll unterstützt, weitere in Beta)
• Datenabgleich: Vergleich der erkannten Daten mit den erwarteten Personendaten
• Liveness-Check: Video-basierte Lebenderkennung zum Schutz vor Fotos und Deepfakes
• Gesichtserkennung: Biometrischer Abgleich zwischen Ausweisfoto und Live-Video

Basis-URL

https://api.verify.enjyn.de

Authentifizierung

Für den Zugriff gibt es zwei Wege. Welchen Sie wählen, hängt davon ab, wo Ihr Aufruf ausgeführt wird:

Verfahren	Geeignet für	Umsetzung
API-Key	Server-zu-Server-Aufrufe	Header X-Api-Key: ihr-api-key
Domain-Freischaltung	Reine Browser-Integrationen	Ohne Key – Ihre Domain wird freigeschaltet

X-Api-Key: ihr-api-key

Anfragen ohne gültigen Key von einer nicht freigeschalteten Domain werden mit 403 Forbidden abgelehnt.

Schnellstart

So integrieren Sie Enjyn KYC in 3 Schritten:

1. Session erstellen: Senden Sie die zu prüfenden Personendaten an die API
2. Nutzer verifizieren: Leiten Sie den Nutzer zum Verifizierungslink weiter
3. Ergebnis abrufen: Fragen Sie das Verifizierungsergebnis über /api/v1/get-result/{session_id} ab

Beispiel: Session erstellen

// JavaScript / Node.js – serverseitig ausführen, der Key darf nicht in den Browser
const response = await fetch('https://api.verify.enjyn.de/api/v1/verify', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': process.env.KYC_API_KEY
    },
    body: JSON.stringify({
        vorname: 'Max',
        nachname: 'Mustermann',
        geburtsdatum: '01.01.1990',
        country: 'DE',                               // optional: Land vorgeben
        adresse: 'Musterstraße 12, 10115 Berlin',    // optional: Adresse mitprüfen
        return_url: 'https://ihre-seite.de/callback'
    })
});

const data = await response.json();
console.log(data.verify_url); // Link für den Nutzer

Beispiel: Ergebnis abrufen

// Ergebnis mit Session-ID abrufen (mit Key, damit face_confidence enthalten ist)
const result = await fetch('https://api.verify.enjyn.de/api/v1/get-result/' + sessionId, {
    headers: { 'X-Api-Key': process.env.KYC_API_KEY }
});
const data = await result.json();

if (data.status === 'verified') {
    console.log('Verifizierung erfolgreich!');
} else if (data.status === 'failed') {
    console.log('Verifizierung fehlgeschlagen');
}

API Endpunkte

POST /api/v1/verify

Erstellt eine neue Verifizierungs-Session.

Request Body

Parameter	Typ	Pflicht	Beschreibung
vorname	String	Ja	Vorname wie auf dem Ausweis
nachname	String	Ja	Nachname wie auf dem Ausweis
geburtsdatum	String	Ja	Geburtsdatum im Format TT.MM.JJJJ
country	String	Nein	ISO-Code des Ausstellungslandes (z. B. DE, AT, US). Ist das Land vorgegeben, entfällt die Länderauswahl im Ablauf und die Oberflächensprache wird passend gesetzt (Deutsch für DE/AT/CH, sonst Englisch). Ohne Angabe wählt der Nutzer selbst.
adresse	String	Nein	Aktiviert die Adressverifizierung: Die übergebene Anschrift wird mit der Adresse auf dem Dokument abgeglichen; bei Abweichung schlägt die Verifizierung fehl. Nur in 11 Ländern möglich (siehe Länderliste). Der Reisepass ist dann nicht wählbar, da er keine Anschrift enthält. Maximal 255 Zeichen.
return_url	String	Nein	Ziel des Abschluss-Buttons. Es wird nicht automatisch weitergeleitet – der Nutzer sieht das Ergebnis und klickt selbst. status und session_id werden als Parameter angehängt.

ℹ️ Hinweis: Namen in kyrillischer oder griechischer Schrift können übergeben werden.

Fehlerfälle beim Erstellen (HTTP 400)

Ursache	Antwort
Pflichtfeld fehlt	Vorname, Nachname und Geburtsdatum sind erforderlich
Unbekanntes Länderkürzel	Nicht unterstütztes Land. Erwartet wird ein ISO-Code wie DE, AT oder US.
Adresse übergeben, aber das Land trägt keine auf dem Ausweis	Für dieses Land ist keine Adressverifizierung möglich. Die Antwort enthält zusätzlich das Feld supported_countries mit den zulässigen Kürzeln.
Adresse länger als 255 Zeichen	Die Adresse ist zu lang. Erlaubt sind bis zu 255 Zeichen.

Response (Erfolg)

{
    "success": true,
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "abc123xyz...",
    "verify_url": "https://api.verify.enjyn.de/verify/abc123xyz...",
    "qr_url": "https://api.verify.enjyn.de/api/v1/qr-code/abc123xyz..."
}

Response Felder

Feld	Beschreibung
session_id	Eindeutige ID der Session (zum späteren Abrufen des Ergebnisses)
token	Einmaliger Token für die Verifizierungs-URL
verify_url	Link, den der Nutzer öffnen muss
qr_url	URL zu einem QR-Code-Bild (PNG) für mobile Nutzung

---

GET /api/v1/get-result/{session_id}

Ruft das Ergebnis einer Verifizierung ab.

Response (Erfolg)

{
    "success": true,
    "status": "verified",
    "vorname": "Max",
    "nachname": "Mustermann",
    "geburtsdatum": "01.01.1990",
    "face_confidence": 87.5,
    "verified_at": "2025-12-28T14:30:00Z",
    "created_at": "2025-12-28T14:25:00Z",
    "data_available": true
}

ℹ️ Hinweis zu face_confidence: Der Übereinstimmungswert des Gesichtsabgleichs wird nur zurückgegeben, wenn die Anfrage den X-Api-Key Ihres Kontos trägt. Ohne Key steht dort null – so gelangt der Wert nicht in den Browser des Nutzers.

Status-Werte

Status	Bedeutung
pending	Session erstellt, Verifizierung noch nicht gestartet
processing	Verifizierung läuft gerade
verified	Verifizierung erfolgreich abgeschlossen
failed	Verifizierung fehlgeschlagen
expired	Session abgelaufen (nach 1 Stunde)

⚠️ Achtung: Personendaten (Vorname, Nachname, Geburtsdatum) werden nach 10 Minuten anonymisiert. Der Status bleibt bis zu 30 Tage abrufbar.

---

GET /api/v1/check-status/{token}

Prüft den aktuellen Status einer laufenden Verifizierung (z.B. für Polling).

Response

{
    "success": true,
    "status": "processing",
    "has_front_image": true,
    "has_back_image": true,
    "has_liveness": false,
    "face_confidence": null,
    "verified_at": null
}

---

GET /api/v1/qr-code/{token}

Generiert einen QR-Code als PNG-Bild für die Verifizierungs-URL.

Response

Gibt ein PNG-Bild zurück (Content-Type: image/png).

<img src="https://api.verify.enjyn.de/api/v1/qr-code/abc123xyz..." alt="QR-Code">

Callback / Redirect

Wenn Sie eine return_url angeben, erscheint nach Abschluss ein Button zurück zu Ihrer Seite. Eine automatische Weiterleitung findet nicht statt – der Nutzer sieht zunächst sein Ergebnis und klickt selbst. Die aufgerufene URL erhält Query-Parameter mit dem Ergebnis:

Erfolgreiche Verifizierung

https://ihre-seite.de/callback?status=success&session_id=550e8400-e29b-41d4-a716-446655440000

Fehlgeschlagene Verifizierung

https://ihre-seite.de/callback?status=failed&session_id=550e8400-e29b-41d4-a716-446655440000

Abgelaufene Session

https://ihre-seite.de/callback?status=expired&session_id=550e8400-e29b-41d4-a716-446655440000

Verifizierungsprozess

So läuft die Verifizierung aus Sicht des Nutzers ab:

1. Link öffnen: Der Nutzer öffnet den Verifizierungslink auf seinem Smartphone
2. Land und Dokument wählen: Der Nutzer wählt das Ausstellungsland und die Dokumentart
3. Ausweis erfassen: Beim Personalausweis Vorder- und Rückseite, beim Reisepass die Datenseite
4. Lebenderkennung: Kurze Videoaufnahme zur Bestätigung, dass eine reale Person anwesend ist
5. Abschluss: Automatische Prüfung und Weiterleitung

Unterstützte Dokumente

• Personalausweise und Reisepässe aus 33 Ländern: alle 27 EU-Staaten, Schweiz, Norwegen, Island, Liechtenstein sowie Singapur und die USA
• Deutschland voll unterstützt, alle weiteren Länder aktuell in der Beta-Phase
• Personalausweis: Vorder- und Rückseite · Reisepass: Datenseite mit Lichtbild
• Abgelaufene Dokumente werden automatisch erkannt und abgewiesen
• Bei aktiver Adressverifizierung ist der Reisepass nicht wählbar, da er keine Anschrift enthält

ℹ️ Hinweis zur Beta: Bei Ländern in der Beta-Phase können Anfragen eher abgelehnt werden. Zu einer fälschlich bestätigten Verifizierung führt das nicht.

Länderliste

Gültige Werte für den Parameter country (ISO 3166-1 alpha-2). Die Spalte Adresse zeigt, wo eine Adressverifizierung möglich ist – nur dort trägt das nationale Ausweisdokument eine aufgedruckte Meldeadresse.

Kürzel	Land	Adresse
DE	Deutschland	ja
AT	Österreich (Beta)	–
BE	Belgien (Beta)	–
BG	Bulgarien (Beta)	ja
CY	Zypern (Beta)	–
CZ	Tschechien (Beta)	ja
DK	Dänemark (Beta)	–
EE	Estland (Beta)	–
ES	Spanien (Beta)	ja
FI	Finnland (Beta)	–
FR	Frankreich (Beta)	–
GR	Griechenland (Beta)	–
HR	Kroatien (Beta)	ja
HU	Ungarn (Beta)	–
IE	Irland (Beta)	–
IS	Island (Beta)	–
IT	Italien (Beta)	ja
LI	Liechtenstein (Beta)	–
LT	Litauen (Beta)	–
LU	Luxemburg (Beta)	–
LV	Lettland (Beta)	–
MT	Malta (Beta)	ja
NL	Niederlande (Beta)	–
NO	Norwegen (Beta)	–
PL	Polen (Beta)	–
PT	Portugal (Beta)	–
RO	Rumänien (Beta)	–
SE	Schweden (Beta)	–
SG	Singapur (Beta)	ja
SI	Slowenien (Beta)	ja
SK	Slowakei (Beta)	ja
CH	Schweiz (Beta)	–
US	USA (Beta)	ja

Ungültige Kürzel werden mit HTTP 400 abgelehnt.

Prüfstufen

Jede Verifizierung durchläuft vier aufeinander aufbauende Stufen. Nur wenn alle Stufen bestanden werden, gilt die Prüfung als erfolgreich.

Dokumentenerfassung

Die Angaben werden automatisch aus dem Ausweisdokument ausgelesen. Zusätzlich wird geprüft, ob es sich um ein unterstütztes und gültiges Dokument handelt.

Datenabgleich

Die ausgelesenen Angaben werden mit den Daten verglichen, die Sie beim Erstellen der Session übermittelt haben.

Lebenderkennung

Mehrstufige Prüfung, ob die Aufnahme von einer real anwesenden Person stammt. Vorlagen, Aufzeichnungen und Wiedergaben werden abgewiesen.

Biometrischer Abgleich

Vergleich zwischen dem Lichtbild im Ausweisdokument und der Person in der Videoaufnahme.

ℹ️ Hinweis: Aus Sicherheitsgründen veröffentlichen wir keine Details zu Schwellenwerten, Erkennungsmerkmalen oder Abwehrmechanismen. Diese Angaben würden Missbrauchsversuche erleichtern. Bei berechtigtem Interesse informieren wir Sie im Rahmen einer Integration gezielt.

Fehlerbehandlung

Die API gibt im Fehlerfall strukturierte JSON-Responses zurück:

{
    "success": false,
    "error": "Fehlerbeschreibung",
    "code": "ERROR_CODE"
}

HTTP Status Codes

Code	Bedeutung
200	Erfolg
400	Ungültige Anfrage (fehlende Parameter)
403	Zugriff verweigert (Domain nicht autorisiert)
404	Session nicht gefunden
410	Session abgelaufen
429	Monatliches Limit erreicht
500	Interner Serverfehler

Fehler-Codes

Code	Beschreibung	Lösung
DOMAIN_NOT_WHITELISTED	Ihre Domain ist nicht freigeschaltet	Kontaktieren Sie uns zur Freischaltung
MONTHLY_LIMIT_REACHED	Monatliches Kontingent aufgebraucht	Upgrade auf höheres Kontingent
SESSION_EXPIRED	Die Session ist abgelaufen (1h Limit)	Neue Session erstellen
INVALID_DOCUMENT	Dokument konnte nicht erkannt werden	Nutzer soll besseres Foto machen
DATA_MISMATCH	Daten stimmen nicht überein	Eingabedaten prüfen
LIVENESS_FAILED	Liveness-Check nicht bestanden	Nutzer soll Video wiederholen
FACE_MISMATCH	Gesicht stimmt nicht mit Ausweis überein	Möglicherweise Betrugsversuch

Sicherheit & Datenschutz

Enjyn KYC wurde von Grund auf für maximalen Datenschutz entwickelt. Alle Daten werden auf deutschen Servern verarbeitet und unterliegen der DSGVO.

Datenlöschung

Datentyp	Löschung nach
Ausweisbilder (Vorder-/Rückseite)	10 Minuten
Liveness-Video	10 Minuten
Biometrische Daten	10 Minuten
Personendaten (Name, Geburtsdatum)	10 Minuten
Session-Metadaten (ID, Status)	30 Tage

Sicherheitsmaßnahmen

• Verschlüsselte Übertragung und Speicherung: Alle Daten sind auf dem Transportweg und während der kurzen Verarbeitungsdauer verschlüsselt
• Kein Mitarbeiterzugriff: Sensible Daten werden ausschließlich automatisiert verarbeitet
• Deutsche Server: Alle Daten verbleiben auf Servern in Deutschland
• DSGVO-konform: Vollständige Einhaltung der Datenschutz-Grundverordnung
• SSL/TLS: Alle API-Verbindungen sind TLS-verschlüsselt

Warum wir das gebaut haben

💡 Hintergrund: Enjyn KYC ist ursprünglich für ein eigenes Projekt entstanden. Uns war wichtig, dass die Löschung sensibler Daten nachvollziehbar und kurzfristig erfolgt und dass Verarbeitung sowie Speicherung in Deutschland stattfinden. Genau darauf ist der Dienst ausgelegt: feste 10-Minuten-Löschung, keine dauerhafte Speicherung von Ausweisbildern oder biometrischen Daten.

Preise

Plan	Preis	Details
Kostenlos	0€	Bis 100 Verifizierungen pro Monat
Standard	25€ / 250 Verifizierungen
Custom Branding	280€ / Monat	Eigenes Logo, Farben, Texte (Min. 3 Monate)

Einordnung

Etablierte KYC-Anbieter rechnen üblicherweise pro Verifizierung ab und vergeben ihre Konditionen auf Anfrage; ein kostenloses Dauerkontingent ist dort unüblich. Enjyn KYC verfolgt einen anderen Ansatz:

• 100 Verifizierungen pro Monat dauerhaft kostenlos – ohne Vertragslaufzeit
• Rund 0,10 € pro Verifizierung im Standard-Paket (25 € für 250 Verifizierungen)
• Transparente Listenpreise statt Angebot auf Anfrage

Code-Beispiele

PHP

<?php
// Session erstellen
$data = [
    'vorname' => 'Max',
    'nachname' => 'Mustermann',
    'geburtsdatum' => '01.01.1990',
    'country' => 'DE',                    // optional
    'return_url' => 'https://ihre-seite.de/callback'
];

$ch = curl_init('https://api.verify.enjyn.de/api/v1/verify');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Api-Key: ' . getenv('KYC_API_KEY')
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Nutzer weiterleiten
header('Location: ' . $response['verify_url']);
?>

Python

import os
import requests

# Session erstellen
kopf = {'X-Api-Key': os.environ['KYC_API_KEY']}

response = requests.post('https://api.verify.enjyn.de/api/v1/verify', headers=kopf, json={
    'vorname': 'Max',
    'nachname': 'Mustermann',
    'geburtsdatum': '01.01.1990',
    'country': 'DE',                    # optional
    'return_url': 'https://ihre-seite.de/callback'
})

data = response.json()
print(f"Verifizierungs-Link: {data['verify_url']}")

# Später: Ergebnis abrufen
result = requests.get(f"https://api.verify.enjyn.de/api/v1/get-result/{data['session_id']}", headers=kopf)
print(f"Status: {result.json()['status']}")

cURL

# Session erstellen
curl -X POST https://api.verify.enjyn.de/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $KYC_API_KEY" \
  -d '{
    "vorname": "Max",
    "nachname": "Mustermann",
    "geburtsdatum": "01.01.1990",
    "country": "DE",
    "return_url": "https://ihre-seite.de/callback"
  }'

# Ergebnis abrufen
curl https://api.verify.enjyn.de/api/v1/get-result/SESSION_ID \
  -H "X-Api-Key: $KYC_API_KEY"

Häufige Fragen (FAQ)

Wie lange ist eine Session gültig?

Eine Session ist 1 Stunde nach Erstellung gültig. Danach wechselt der Status zu expired.

Kann ich das Design anpassen?

Ja, mit dem Custom Branding Paket (280€/Monat) können Sie Logo, Farben und Texte anpassen.

Welche Länder werden unterstützt?

Ausweisdokumente aus 33 Ländern: alle 27 EU-Staaten sowie die Schweiz, Norwegen, Island, Liechtenstein, Singapur und die USA. Deutschland ist vollständig unterstützt, die übrigen Länder befinden sich in der Beta-Phase.

Woran erkenne ich, ob eine Prüfung fehlgeschlagen ist?

Das Ergebnis rufen Sie über /api/v1/get-result/{session_id} ab. Der Status ist entweder verified oder failed. Aus Sicherheitsgründen wird nicht aufgeschlüsselt, welche einzelne Prüfstufe nicht bestanden wurde.

Was passiert bei schlechter Bildqualität?

Der Nutzer erhält direkt im Verifizierungsdialog einen Hinweis und kann die Aufnahme wiederholen. Ihre Integration muss dafür nichts vorsehen.

Kann ich die Integration testen, ohne Kontingent zu verbrauchen?

Das kostenlose Kontingent von 100 Verifizierungen pro Monat ist für Integrationstests gedacht. Eine separate Sandbox gibt es derzeit nicht. Sprechen Sie uns an, wenn Sie für eine größere Integration zusätzliche Testläufe benötigen.

In welcher Sprache wird der Verifizierungsdialog angezeigt?

Die Oberfläche stellt sich automatisch ein: Deutsch für den DACH-Raum, Englisch für alle übrigen Länder. Der Nutzer kann jederzeit manuell umschalten.

Wie kann ich mein Kontingent erhöhen?

Kontaktieren Sie uns unter support@enjyn.de für ein Upgrade.

Werden die Daten für KI-Training verwendet?

Nein. Alle Daten werden ausschließlich für die Verifizierung verwendet und danach gelöscht. Es findet kein Training statt.

Kunden-Dashboard

Als freigeschalteter Kunde erhalten Sie Zugang zum Kunden-Dashboard unter:

https://api.verify.enjyn.de/tenant/

Im Dashboard können Sie:

• Ihre aktuelle Nutzung und das verbleibende Kontingent einsehen
• Alle durchgeführten Verifizierungen (ohne persönliche Daten) sehen
• Die Erfolgsrate Ihrer Verifizierungen überwachen

ℹ️ Info: Die Zugangsdaten für das Dashboard erhalten Sie bei der Domain-Freischaltung per E-Mail.

Support & Kontakt

Bei Fragen oder Problemen erreichen Sie uns unter:

• 📧 E-Mail: support@enjyn.de
• 🌐 Kontaktformular: enjyn.de/kontakt
• 📄 Live-Demo: enjyn.de/kyc