Prozess abrufenGET

Rufen Sie einen bestehenden Prozess anhand seiner Kennung ab. Gemäß dem API-Contract wird das Ergebnis bereits synchron bei der Prozesserstellung zurückgegeben — verwenden Sie diesen Endpunkt für erneute Abfragen, Audits und Support.

Warnung

Bevor Sie den Prozess abrufen, prüfen Sie unsere Webhook-Konfiguration und Fallback-Strategien — hier klicken.

Endpunkt

Umgebung	URL
Produktion	GET https://api.id.unico.app/processes/v1/{processId}
Sandbox	GET https://api.id.uat.unico.app/processes/v1/{processId}

Anfrage

Headers

Header	Wert
Authorization	Bearer <access_token>
APIKEY	Bereitgestellter API-Schlüssel.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
processId	string (UUID)	ja	Prozesskennung, die von Prozess erstellen zurückgegeben wird.

Beispiel

cURL

curl -X GET https://api.id.unico.app/processes/v1/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY"

Node.js

import fetch from 'node-fetch';

const res = await fetch(
  `https://api.id.unico.app/processes/v1/${processId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      APIKEY: apiKey
    }
  }
);
const result = await res.json();

Antworten

200 OK

Der Contract ist einheitlich — das Feld idCloud.result trägt das konsolidierte Urteil der verwendeten Fähigkeiten.

Unico konsolidiert die Ergebnisse der ausgeführten Fähigkeiten in einem einzigen idCloud.result, bereit, um den nächsten Schritt Ihres Flows zu entscheiden — ohne dass Sie einzelne Ergebnisse orchestrieren müssen.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

Feld	Typ	Beschreibung
id	string (UUID)	Prozesskennung.
status	integer	1 (in Bearbeitung), 2 (Abweichung), 3 (erfolgreich abgeschlossen), 4 (storniert), 5 (Fehler).

Mögliche Ergebniswerte

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

Die zurückgegebenen Werte hängen vom Recipe ab, das in Ihrem APIKey konfiguriert ist. Siehe Flows für die Ergebniswerte, die jedes Recipe zurückgeben kann.

Kunden in Brasilien erhalten möglicherweise die Antwort nach Fähigkeit

Die Gesamtstruktur der Antwort bleibt gleich — das einzelne Ergebnis ist der Standard.

Integrationen in Brasilien erhalten möglicherweise die offenen Ergebnisse pro Fähigkeit. Jede in der APIKey aktivierte Fähigkeit fügt der Antwort einen eigenen Block hinzu — Felder für deaktivierte Fähigkeiten werden weggelassen.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "unicoId": {
    "result": "yes"
  },
  "riskLevel": {
    "result": "inconclusive"
  },
  "idFace": {
    "personId": "a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890",
    "result": "FOUND"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "government": {
    "serpro": 87
  },
  "liveness": 1,
  "idAge": {
    "result": "yes"
  },
  "cardholderVerification": {
    "result": "approved"
  }
}

Feld	Typ	Beschreibung
unicoId.result	string	yes, no, inconclusive — siehe Identitätsprüfung.
riskLevel.result	string	not_approved, critical_risk, high_risk, inconclusive — siehe Betrugseinstufung nach Risiko.
idFace.result	string	FOUND — siehe Gesichts-Identifikator.
idFace.personId	string	Stabiler, opaker Bezeichner für das Gesicht, zurückgegeben zusammen mit idFace.result = FOUND. Kann kein Gesicht im Bild identifiziert werden, liefert der Prozess Fehler 20532 anstelle eines idFace-Blocks.
identityFraudsters.result	string	Veraltet. Verwenden Sie stattdessen riskLevel. Kunden mit laufenden Integrationen können es weiterhin verwenden, während sie die Migration mit ihrem Projektteam koordinieren.
government.serpro	integer	Serpro-Ähnlichkeitswert (0–100, -1, -2). Nur in Brasilien verfügbar. Siehe Serpro-Ähnlichkeitsabgleich.
liveness	integer	1 (bestanden), 2 (nicht bestanden) — siehe Lebenderkennung.
idAge.result	string	yes, no, inconclusive — siehe Altersverifizierung. Nur in Brasilien verfügbar.
score	integer	Probabilistischer Risiko-Score. Vorhanden, wenn unicoId.result = inconclusive und die Risiko-Score-Orchestrierung aktiv ist. Positive Werte deuten auf eine höhere Wahrscheinlichkeit hin, dass es sich um den Inhaber handelt; negative Werte deuten auf ein höheres Risiko hin. Nur in Brasilien verfügbar.
cardholderVerification.result	string	approved, unsure — siehe Cardholder Verification. Fehlt, solange status noch nicht 3 (abgeschlossen) ist. Nur in Brasilien verfügbar.

Wann dieser Endpunkt verwendet werden sollte

Der API-Contract gibt Ergebnisse synchron zurück, daher benötigen die meisten Integrationen diesen Endpunkt nicht. Verwenden Sie ihn, wenn:

• Sie nur die processId gespeichert haben und das vollständige Ergebnis später abrufen müssen (Audit, Support).
• Sie vermuten, dass die ursprüngliche Antwort während der Übertragung verloren ging (Netzwerkfehler, nachdem die Plattform die Arbeit abgeschlossen hat).
• Sie ein Back-Office-Tool erstellen, das historische Prozesse überprüft.

Fehlercodes

400 Bad Request

Code	Nachricht	Beschreibung
20023	O parâmetro processId não foi informado.	Der processId-Parameter fehlt.
20002	O parâmetro APIKey não foi informado.	Der APIKEY-Parameter fehlt im Anfrage-Header.
20001	O parâmetro authtoken não foi informado.	Der Integrationstoken-Parameter fehlt im Anfrage-Header.

404 Not Found

Code	Nachricht	Beschreibung
50001	O processo informado não foi encontrado.	Der Prozess existiert nicht in der Datenbank.

403 Forbidden

Code	Nachricht	Beschreibung
30017	User does not have permission to perform this action.	Fehlerhaftes JWT oder Benutzer ohne Berechtigung für diese Operation.
10502	O token informado está expirado.	Wenn das verwendete Access-Token abgelaufen ist.
10501	O token informado é inválido.	Das Authentifizierungstoken ist ungültig.
10201	O AppKey informado é inválido.	Der APIKEY-Parameter wurde nicht angegeben oder existiert nicht.

410 Gone

Der Prozess existiert, resultierte jedoch in einem Fehler. Gibt nur id und status: 5 zurück.

429 Too Many Requests

Rate limit reached. When your system receives an HTTP 429 error, you must implement mechanisms to prevent cascading failures and avoid worsening the restriction.

Best practices:

• Cool-down period (backoff): Immediately halt or throttle subsequent requests from your system. Do not continuously retry failed requests in a tight loop.
• Queueing & throttling: Buffer or queue outgoing requests on your end to control the traffic flow before re-sending them.
• Exponential backoff with jitter: When retrying, increase the waiting time exponentially between attempts (e.g., 1 s, 2 s, 4 s, 8 s) and add a small random delay ("jitter") to prevent a herd effect where all queued requests retry at the exact same millisecond.

Warnung

Continuously hitting a rate-limited endpoint without backing off can prolong the restriction period and severely impact your system's operational throughput. Properly throttling requests on your side ensures a smoother, more resilient integration.

For default limits, increase requests and additional details, see Rate Limits.

500 Internal Server Error

Code	Nachricht	Beschreibung
99999	Internal failure! Try again later	Wenn ein interner Fehler auftritt.

Flows

Ein Recipe ist die Kombination von Fähigkeiten (Lebenderkennung, Identitätsprüfung, Risikosignale, Dokumente ...), die in der APIKey Ihres Projekts konfiguriert ist. Es definiert, was Unico in jedem Prozess ausführt und wie die Ergebnisse im einzelnen result konsolidiert werden — Sie müssen auf Ihrer Seite nichts orchestrieren.

Unico pflegt einen Katalog vordefinierter, benannter und versionierter Recipes (z. B. byunico-idlive-idunico-oneresponse-std). Einige sind exklusiv für Brasilien, etwa solche, die Score, Serpro oder Altersverifizierung einschließen.

Welche Fähigkeiten führt Ihr Prozess aus?

Die Kombination von Fähigkeiten — der Flow Ihres Projekts — wird in Ihrer APIKey-Konfiguration festgelegt. Prüfen Sie die vordefinierten Recipes oder wenden Sie sich an Ihren Unico-Projektansprechpartner, um sie anzupassen.