Prozess erstellen | Unico Developer Portal

Prozess erstellenPOST

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

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
`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

Vor dem Aufruf​

Flows​

Request​

Gemeinsame Felder​

Das Feld credential​

Flow-Felder​

Body-Regeln​

Response​

Das Ergebnis in data​

Fehler​

Flow-Ablehnungen​

Weiter​