Prozess erstellenPOST

Starten Sie einen Prozess und erhalten Sie den Human Token und die Intelligence der Person.

Markdown

POST /v1/processes

Startet einen Prozess mit einem der Flows und antwortet mit id, state und dem Ergebnis in data: dem Human Token und der Intelligence der Person, data.ndocs.

Vor dem Aufruf

• Human Plugin läuft und GET /health/ready antwortet mit 200.
• Ihr Access Key ist für den von Ihnen verwendeten Flow aktiviert.
• Wenn Sie ein Dokument senden, steht dessen type im Attributkatalog.

Flows

Das Feld flow legt fest, was der Prozess tut. Human Plugin führt diese Flows in zwei Integrationsmodellen aus:

• API Only: Ihr Back-end sendet das Selfie in imageBase64, und das Create antwortet mit dem Ergebnis.
• Human Token Journey: Die Person nimmt das Selfie in der Capture Journey auf und kehrt zu Ihrer callbackUri zurück. Das Create antwortet mit einem token und einem link, und Sie lesen das Ergebnis mit Prozess abrufen.

Flow	Description	Possible result	Integration components required	Example
api+humantoken	Empfängt ein Selfie über Ihr Back-end und erzeugt den Human Token, einen eindeutigen Gesichtsbezeichner. Die Antwort ist endgültig: keine Erfassung, kein zweiter Aufruf.	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	Erfasst ein Selfie in der Capture Journey mit einer Lebenderkennung und erzeugt den Human Token. Das Create liefert den `token` und den `link`; lesen Sie das Ergebnis, wenn die Erfassung endet.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
humantoken+revalidation	Erfasst ein Selfie und vergleicht das Gesicht mit dem erwarteten Human Token. Liefert, ob es sich um dieselbe Person handelt oder nicht, zum Beispiel vor einer sensiblen Aktion.	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

clientId, correlationId und credential sind in jedem Flow gleich.

Request

{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}

Gemeinsame Felder

Feld	Erforderlich	Limit (Bytes)	Hinweise
flow	Ja	64	Einer der Flows
clientId	Ja	128	Ihre ID für den Client. Die Intelligence zählt verschiedene Werte
correlationId	Ja	128	Ihre Referenz für diesen Prozess. Eindeutig: Eine, die ein anderer Prozess bereits hat, wird unabhängig von dessen Zustand mit 409 abgelehnt
credential	Ja, darf aber leer sein		Der Schlüssel muss vorhanden sein. Siehe unten
credential.type	Mit einem Dokument		Ein Code des Attributkatalogs, exakt und unter Beachtung der Groß- und Kleinschreibung
credential.value	Mit einem Dokument	64	Die Dokumentnummer

flow, clientId und correlationId müssen Strings sein, ohne Steuerzeichen und ohne führende oder nachgestellte Leerzeichen. Ungültige Werte werden abgelehnt, nie umgeschrieben.

Das Feld credential

• Mit einem Dokument: ein Objekt mit genau type und value, beide Strings, gemeinsam gesendet.
• Ohne Dokument: null oder {}. Der Prozess zählt in der Intelligence trotzdem als Transaktion und als Client.
• Weggelassen oder ein Objekt mit leeren Strings: wird mit 400 MISSING_CREDENTIAL_TYPE abgelehnt. So wird ein falsch geschriebener Schlüssel erkannt, bevor etwas verarbeitet wird.
• Jeder andere Schlüssel in credential wird abgelehnt.

Flow-Felder

Was jeder Flow zu den gemeinsamen Feldern hinzufügt:

Feld	Flow	Erforderlich	Wert
imageBase64	api+humantoken	Ja	Das Selfie in Base64. PNG, JPEG oder WebP, bis 800 KB
callbackUri	humantoken, humantoken+revalidation	Ja	Wohin die Person zurückkehrt, wenn die Erfassung endet: eine Seite von Ihnen oder das URL-Schema Ihrer App
references	humantoken+revalidation	Ja	Ein Element mit dem erwarteten Human Token, wie im Beispiel oben

Human Plugin speichert diese Felder nicht, und ein falsch geschriebenes optionales Feld wird möglicherweise ohne Fehler ignoriert.

Verwenden Sie bei api+humantoken ein frontales, gut beleuchtetes Selfie mit einem einzelnen Gesicht. Ein Wert, der kein Bild ist, wird abgelehnt, und der Prozess wird als fehlgeschlagen gespeichert: siehe Flow-Ablehnungen.

Bei humantoken+revalidation enthält das Ergebnis humanTokenMatch statt humanToken:

• "true": Es ist dieselbe Person. Der Prozess zählt für diese Person, und ndocs beschreibt sie.
• Alles andere oder eine Erfassung ohne Liveness: Es ist nicht bestätigt. Der Prozess zählt für niemanden, und es gibt kein ndocs.

In beiden Fällen wird PROCESS_STATE_FINISHED geantwortet: Lesen Sie humanTokenMatch. Siehe Prozess abrufen.

Einige Namen sind von Human Plugin reserviert und werden mit 400 INVALID_REQUEST abgelehnt, etwa clientReference. Dasselbe gilt für eine andere Schreibweise der eigenen Felder von Human Plugin, wie client_id, correlation_id oder Flow: Gelesen werden nur flow, clientId, correlationId und credential, exakt so geschrieben.

Body-Regeln

• Ein JSON-Objekt, höchstens 2 MiB (etwa ausreichend für ein Selfie in Base64). Ein größerer Body wird mit 400 REQUEST_TOO_LARGE abgelehnt.
• Nach dem JSON-Objekt darf nichts folgen.

Response

201 Created, mit Location: /v1/processes/<id>.

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

• id ist die UUID von Human Plugin. Jede akzeptierte Anfrage erzeugt eine neue.
• state ist der lokale Status. Siehe Lebenszyklus.
• humantoken und humantoken+revalidation antworten mit PROCESS_STATE_CREATED und einem token sowie einem link. Diese werden einmal zurückgegeben und nie gespeichert: Bewahren Sie sie auf. Siehe Human Token Journey und die Capture-Anleitung für Ihre Plattform.
• data.ndocs ist die Intelligence der Person. Sie kann fehlen: siehe Intelligence.

Das Ergebnis in data

Ein abgeschlossener Prozess hat diese Felder in data. Die Journey-Flows liefern sie, wenn Sie den Prozess nach der Erfassung lesen.

Feld	Wann	Wert
humanToken	api+humantoken, humantoken	Wer die Person ist: value ist der Human Token, und status ist validated, wenn er erzeugt wurde
humanTokenMatch	humantoken+revalidation	"true", wenn es dieselbe Person ist wie der Human Token in references
liveness	Flows, die eine Lebenderkennung durchführen, etwa die Journey-Flows	value ist live, wenn die Erfassung von einer lebenden Person stammt, oder not_live, wenn nicht; status ist validated, wenn die Prüfung gelaufen ist
ndocs	Wenn es Intelligence zur Person gibt	Die Intelligence der Person

Ein Journey-Ergebnis sieht so aus:

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}

Prüfen Sie liveness, bevor Sie dem Ergebnis vertrauen: Behandeln Sie die Erfassung bei not_live als fehlgeschlagen und bitten Sie die Person, es erneut zu versuchen. Ein Prozess mit not_live zählt für die Intelligence von niemandem.

Fehler

Status	message	Bedeutung
400	INVALID_REQUEST, REQUEST_TOO_LARGE	Kein einzelnes JSON-Objekt, ein reserviertes Feld, ein falscher Typ oder ein Body über 2 MiB
400	MISSING_<FIELD>, INVALID_<FIELD>	Ein Pflichtfeld fehlt oder ist fehlerhaft, etwa MISSING_CLIENT_ID
401	Leer ("")	Unico hat Ihren Access Key abgelehnt: Er fehlt, ist falsch oder nicht mehr gültig. Der Prozess wird als fehlgeschlagen gespeichert. Prüfen Sie HUMAN_API_ACCESS_KEY
409	CORRELATION_ID_ALREADY_USED	Ein anderer Prozess hat die correlationId bereits. Es wird nichts gespeichert oder gesendet
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	credential.type steht nicht im Katalog. Es wird nichts gespeichert oder gesendet
4xx	Die message des Flows	Der Flow hat die Anfrage abgelehnt, zum Beispiel wegen eines ungültigen Bildes. Siehe Flow-Ablehnungen
502	UPSTREAM_UNAVAILABLE	Der Prozess konnte nicht rechtzeitig bestätigt werden
503	DATABASE_UNAVAILABLE	Die Datenbank ist ausgefallen. Es wurde nichts verarbeitet
500	INTERNAL	Unerwarteter Fehler

Flow-Ablehnungen

Wenn ein Flow die Anfrage ablehnt, antwortet das Create mit 4xx und dem Grund in message, im üblichen Envelope. Die häufigsten:

message	Ursache
invalid flow	flow ist kein für Ihr Konto aktivierter Flow
INVALID_IMAGE (400)	api+humantoken ohne imageBase64
INVALID_REQUEST (400)	imageBase64 ist kein Bild in Base64
IMAGE_TOO_LARGE	Das Bild ist größer als 800 KB
UNSUPPORTED_IMAGE_FORMAT	Das Bild ist weder PNG, JPEG noch WebP
PERMISSION_DENIED (403)	Ihr Access Key ist für diesen Flow nicht aktiviert

Ein abgelehnter Prozess wird als fehlgeschlagen gespeichert. Korrigieren Sie die Anfrage und erstellen Sie einen neuen Prozess mit einer neuen correlationId.

Lesen Sie Fehler und Wiederholungen, bevor Sie eine Wiederholungslogik einbauen: Ein neuer Versuch braucht eine neue correlationId.

Weiter

Prozess abrufen