Halterverifizierung starten

Bei Personen werden Halterdaten und hochgeladene Nachweise verglichen. Bei Unternehmen werden Firmenname und Registerdaten mit der vorhandenen Unternehmensprüfung Ihres Dashboard-Kontos abgeglichen. Erforderlich ist holders:verify.

Beschreibung

Startet die Verifizierung des Halters im aktuellen Datenstand.

Parameter

holder_idpathPflicht

Öffentliche Halter-ID.

Beispiel: hld_test_1a2b3c4d5e6f708192a3b4c5

Idempotency-KeyheaderPflicht

Eindeutig für diesen Prüfversuch.

Beispiel: verify-customer-1842-revision-1

Request-Body

Der Body wird als application/json übertragen. Verwenden Sie ausschließlich die dokumentierten Feldnamen.

Request-Felder

Feld	Typ	Angabe	Beschreibung
`document_variant`	enum	Optional	`id_card` oder `meldebescheinigung`; Standard `id_card`. Nur für Personen.

{
  "document_variant": "id_card"
}

SchemaquelleOpenAPI 3.1 herunterladen

Responses

201

Prüfversuch angelegt; required_document_slots beschreibt den nächsten Multipart-Upload. Läuft für dieselbe Revision bereits ein Prüfversuch, wird dieser zurückgegeben statt ein neuer angelegt.

422

Halterdaten oder Zustimmung sind nicht prüfbar.

Response-Body

Content-Type: application/json. Die erfolgreiche Antwort enthält die nachfolgend beschriebenen Felder.

Response-Felder

Feld	Typ	Angabe	Beschreibung
`id`	string	Immer	Öffentliche Verifizierungs-ID.
`object`	string	Immer	Konstanter Wert `holder_verification`.
`environment`	enum	Immer	`test` oder `live`.
`livemode`	boolean	Immer	`true` für Live-Ressourcen.
`holder_id`	string	Immer	Geprüfter Halter.
`holder_revision`	integer	Immer	Versionsnummer der Halterdaten, auf die sich die Prüfung bezieht.
`method`	enum	Immer	`simulation`, `identity_document` oder `company_register`.
`document_variant`	enum	Immer	Verwendete Nachweisvariante.
`status`	enum	Immer	`requires_documents`, `processing`, `verified` oder `failed`.
`required_document_slots`	array	Immer	Noch benötigte Multipart-Felder.
`comparison`	object	Optional	Ergebnis des Datenabgleichs.
`failure`	object	Optional	Maschinenlesbarer Code und Meldung bei fehlgeschlagener Prüfung.
`submitted_at`	date-time	Optional	Zeitpunkt der vollständigen Nachweisübertragung.
`verified_at`	date-time	Optional	Zeitpunkt der erfolgreichen Prüfung.
`expires_at`	date-time	Optional	Ablaufzeitpunkt des Prüfversuchs.
`created_at, updated_at`	date-time	Immer	Erstellungs- und Änderungszeitpunkt.

{
  "id": "hvr_test_2b3c4d5e6f708192a3b4c5d6",
  "object": "holder_verification",
  "environment": "test",
  "livemode": false,
  "holder_id": "hld_test_1a2b3c4d5e6f708192a3b4c5",
  "holder_revision": 1,
  "method": "simulation",
  "document_variant": "id_card",
  "status": "requires_documents",
  "required_document_slots": [
    "front",
    "back"
  ],
  "created_at": "2026-08-26T10:18:00+02:00",
  "updated_at": "2026-08-26T10:18:00+02:00"
}

Halterverifizierung und QES

Unternehmen und Vertretung

Für Personen wählen Sie optional document_variant: id_card oder meldebescheinigung. Ein Ausweis benötigt die Slots front und back, eine Meldebescheinigung den Slot document.

Für Unternehmen wird keine Registerdatei hochgeladen. Die API verwendet die vorhandene Dashboard-/Yousign-Unternehmensprüfung. Fehlt die Prüfung oder stimmen Firmenname und Registerdaten nicht überein, liefert der Versuch status: failed und company_verification_required. Die QES-Identifizierung des späteren Signers bleibt davon getrennt.

{ "id": "hvr_test_2b3c4d5e6f708192a3b4c5d6", "object": "holder_verification", "environment": "test", "livemode": false, "holder_id": "hld_test_1a2b3c4d5e6f708192a3b4c5", "holder_revision": 1, "method": "simulation", "document_variant": "id_card", "status": "requires_documents", "required_document_slots": [ "front", "back" ], "created_at": "2026-08-26T10:18:00+02:00", "updated_at": "2026-08-26T10:18:00+02:00" }