Zum Hauptinhalt springen
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​

UmgebungURL
ProduktionGET https://api.idcloud.unico.app/client/v1/process/{processId}
SandboxGET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

Anfrage​

Headers
HeaderWert
AuthorizationBearer <access_token>
Pfadparameter
ParameterTypErforderlichBeschreibung
processIdstring (UUID)jaProzesskennung, die von Prozess erstellen zurückgegeben wird.

Beispiel​

curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
  -H "Authorization: Bearer $TOKEN"

Antworten​

200 OK
{
  "process": {
    "id": "226fd950-4b80-4da6-a476-ba9d397ddc91",
    "flow": "id_r2",
    "callbackUri": "/",
    "userRedirectUrl": "https://cadastro.uat.unico.app/flow?collect-data=true&dynamic-wrapper=true&id=226fd950-4b80-4da6-a476-ba9d397ddc91",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_APPROVED",
    "createdAt": "2026-08-06T01:42:21.693615Z",
    "finishedAt": "2026-08-06T01:43:03.080508Z",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "40*******50",
      "friendlyName": "teste",
      "email": "",
      "phone": "5511999999999",
      "notifications": [
        { "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP" }
      ],
      "phoneCountryCodeAlpha3": ""
    },
    "purpose": "personAuthentication",
    "services": [],
    "authenticationInfo": { "authenticationId": "55cba227-9828-49df-a16f-bcdaa7bdaa4d" },
    "capacities": ["PROCESS_CAPACITY_IDCLOUDONE"],
    "expiresAt": "2026-08-13T01:42:21.536500Z",
    "token": "",
    "companyData": { "branchId": "", "countryCode": "BRA" },
    "simulated": false
  }
}
Prozessfelder
FeldBedeutung
idProzess-UUID; der Schlüssel zum Abfragen und Nachverfolgen des Flows.
flowArt der ausgeführten Journey (z. B. id_r2, idlivetrust_r2, idtrust_r2, ...).
callbackUriCallback-URI, zu der die Client-App am Ende des Flows weitergeleitet wird.
userRedirectUrlVollständige URL der CbU-Seite, die der Benutzer öffnet, um die Journey auszuführen (enthält die id und Verhaltens-Flags).
stateLebenszyklusstatus des Prozesses. PROCESS_STATE_*-Werte (z. B. CREATED, FAILED, FINISHED, AWAITING_FOR_DOCUMENT, UNSPECIFIED).
resultEndgültiges Urteil der Auswertung. PROCESS_RESULT_*-Werte (z. B. APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Nur aussagekräftig, wenn state = PROCESS_STATE_FINISHED.
createdAtZeitstempel der Prozesserstellung (UTC).
finishedAtZeitstempel des Prozessabschlusses (UTC).
personUnterobjekt mit den Daten der zu verifizierenden Person.
purposeZweck des Prozesses (z. B. personAuthentication, Personenregistrierung).
servicesListe der dem Prozess zugeordneten zusätzlichen Services; leer, wenn keine vorhanden sind.
authenticationInfo.authenticationIdID des vom Flow erzeugten Identitätsauthentifizierungs-Ereignisses.
capacitiesVerwendete Fähigkeiten/Produkte. PROCESS_CAPACITY_*-Werte (z. B. IDCLOUDONE).
expiresAtZeitstempel des Prozess-/Link-Ablaufs (UTC).
tokenSitzungs-/Zugriffstoken, das dem Prozess zugeordnet ist (kann leer sein).
companyDataUnterobjekt mit den Daten des Unternehmens/Mandanten, dem der Prozess gehört.
simulatedBoolescher Wert; ob es sich um einen Simulations-/Sandbox-Prozess (true) oder einen echten Prozess (false) handelt.
Personenfelder
FeldBedeutung
duiTypeArt des eindeutigen Identifikationsdokuments. DUI_TYPE_*-Werte (z. B. BR_CPF).
duiValueDokumentwert (z. B. die CPF-Nummer).
friendlyNameAnzeigename/Spitzname für die Person (Freitext, nicht validiert).
emailE-Mail-Adresse der Person; kann leer sein.
phoneTelefonnummer im E.164-Format (Landesvorwahl + Vorwahl + Nummer).
notificationsListe der Benachrichtigungskanäle. Jeder Eintrag enthält notificationChannel mit NOTIFICATION_CHANNEL_*-Werten (z. B. WHATSAPP, SMS, EMAIL).
phoneCountryCodeAlpha3ISO-Alpha-3-Ländercode der Telefonnummer (z. B. BRA); kann leer sein.
Unternehmensdatenfelder
FeldBedeutung
branchIdKennung der Filiale des Mandanten; leer, wenn keine Segmentierung nach Filiale erfolgt.
countryCodeLand des Unternehmens in ISO-Alpha-3 (z. B. BRA).
Dokumenttypen und OCR-Felder

process.services[].documents[].doc.code gibt den Dokumenttyp als kurzen Code in Großbuchstaben an. Aus unico.moja.dictionary.br.cnh.v2.Cnh wird CNH. Der Code enthält weder das Land noch die Schemaversion; die Version wird separat in doc.version zurückgegeben.

Dokumenttypen, die das einheitliche Schema verwenden — unified_schema in der Feldreferenz —, werden als der bei der Erfassung identifizierte Typ in Großbuchstaben angegeben: IDCARD, DRIVERLICENSE, PASSPORT oder VOTERID. US-amerikanische Reisepässe behalten ihre Variante, statt zu PASSPORT zusammengefasst zu werden; daher werden auch Werte wie POLYCARBONATEPASSPORT, PASSPORTCARD und PAPERPASSPORT zurückgegeben. Zum Beispiel werden unico.moja.dictionary.ar.generic.v1.IdCard und unico.moja.dictionary.us.generic.v1.PolycarbonatePassport als IDCARD und POLYCARBONATEPASSPORT angegeben.

Spezifische Schemata

Dokumenttypen mit eigenem Feldschema — aufgeführt unter specific_document_schemas in der Feldreferenz — finden Sie in der folgenden Tabelle. Verwenden Sie den Dictionary-Typ, um das jeweilige Schema in dieser Datei nachzuschlagen.

Landdoc.codeDictionary-TypDokument
BRRGunico.moja.dictionary.br.rg.v2.RgRG
BRCNHunico.moja.dictionary.br.cnh.v2.CnhCNH (Führerschein)
BRCINunico.moja.dictionary.br.cin.v1.CinCIN
BRPASSAPORTEunico.moja.dictionary.br.passaporte.v1.PassaporteReisepass
MXINEunico.moja.dictionary.mx.ine.v1.IneINE-Wählerausweis
MXLPCunico.moja.dictionary.mx.lpc.v1.LpcLicencia para conducir (Führerschein)
MXPASAPORTEunico.moja.dictionary.mx.pasaporte.v1.PasaporteReisepass
—UNKNOWNunico.moja.dictionary.other.unknown.v1.UnknownTyp konnte nicht identifiziert werden — doc.data ist leer
PASSAPORTE und PASAPORTE sind unterschiedliche Dokumente

Der brasilianische Reisepass ist PASSAPORTE (mit zwei S) und der mexikanische PASAPORTE (mit einem S), jeweils entsprechend der Schreibweise im eigenen Dictionary. Das ist kein Tippfehler — behandeln Sie die beiden Werte nicht als gleichwertig.

Es wird keine OCR-Extraktion durchgeführt und kein Feld in doc.data zurückgegeben, wenn doc.code den Wert UNKNOWN hat.

BrazilKunden in Brasilien erhalten möglicherweise die vollständige Prozess-Payload

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

Integrationen in Brasilien erhalten möglicherweise das vollständige Prozessobjekt unten, mit Ergebnissen pro Fähigkeit in authenticationInfo.

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idchecktrust",
    "callbackUri": "https://example.com/callback",
    "userRedirectUrl": "https://example.com/redirect",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_OK",
    "createdAt": "2024-01-01T10:00:00Z",
    "finishedAt": "2024-01-01T10:15:00Z",
    "expiresAt": "2024-01-08T10:00:00Z",
    "purpose": "VERIFICATION",
    "clientReference": "client-ref-abc",
    "useCase": "smart_revalidation",
    "capacities": ["liveness", "face_match"],
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "12345678909",
      "friendlyName": "Luke Skywalker",
      "notifications": [
        {
          "notificationChannel": "email"
        }
      ]
    },
    "authenticationInfo": {
      "authenticationId": "auth-123",
      "livenessResult": "LIVENESS_RESULT_LIVE",
      "authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
      "identityFraudstersResult": "TRUST_RESULT_INCONCLUSIVE",
      "bioTokenEngineResult": "BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED",
      "smartRevalidationResult": "SMART_REVALIDATION_RESULT_UNSPECIFIED",
      "idAgeResult": "ID_AGE_RESULT_UNSPECIFIED",
      "scoreEngineResult": {
        "scoreEnabled": "SCORE_ENABLED_TRUE",
        "score": 85.5
      }
    },
    "companyData": {
      "branchId": "branch-123",
      "countryCode": "BR"
    },
    "bioTokenData": {
      "referenceProcessId": "ref-proc-123",
      "authenticationId": "auth-ref-123"
    },
    "services": [
      {
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": ["doc-abc-123"],
        "consent_granted": true,
        "documents": [
          {
            "doc_id": "doc-abc-123",
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "validate_doc": true,
            "reused_doc": false,
            "signed_url": "https://example.com/doc?token=xyz",
            "doc": {
              "version": 1,
              "code": "CNH",
              "data": {
                "numero": "044589731564",
                "cpfNumero": "12345678909",
                "nomeCivil": "Luke Skywalker",
                "dataNascimento": "1990-05-12T00:00:00Z",
                "dataExpiracao": "2027-12-07T00:00:00Z",
                "categoria": "B"
              }
            }
          }
        ]
      }
    ]
  }
}
Felder der obersten Ebene
FeldTypBeschreibung
process.idstring (UUID)Prozesskennung.
process.flowstringBei der Erstellung gesendete Flow-Kennung.
process.callbackUristringFür Prozessereignisse konfigurierte Callback-URL.
process.userRedirectUrlstringURL zur Weiterleitung des Benutzers nach Abschluss der Journey.
process.stateenumAktueller Prozessstatus. Siehe Werte unten.
process.resultenumVerifizierungsergebnis. Nur vorhanden, wenn state = PROCESS_STATE_FINISHED.
process.createdAtstring (datetime)ISO-8601-Zeitstempel der Prozesserstellung.
process.finishedAtstring (datetime)ISO-8601-Zeitstempel des Prozessabschlusses. Nur vorhanden, wenn state = PROCESS_STATE_FINISHED.
process.expiresAtstring (datetime)ISO-8601-Zeitstempel des Prozessablaufs.
process.purposestringZweck des Prozesses, wie im Flow konfiguriert.
process.clientReferencestringOptionale clientseitige Referenz zur Indexierung im Portal.
process.useCasestringDem Flow zugeordnete Szenario-Kennung.
process.capacitiesarray of stringsListe der in diesem Prozess aktivierten Fähigkeiten.
process.tokenstringSigniertes JWT für die SDK-Integration.
process.personobjectBei der Erstellung angegebene Identifikation.
process.person.notificationsarrayFür die Journey konfigurierte Benachrichtigungskanäle (z. B. email).
process.authenticationInfoobjectErgebnisse pro Fähigkeit. Siehe unten.
process.companyDataobjectUnternehmens- und Filialkontext.
process.companyData.branchIdstringFilialkennung.
process.companyData.countryCodestringISO-3166-1-Alpha-2-Ländercode.
process.bioTokenDataobjectReferenzprozess-Info — nur in 1:1-Validierungs- und Intelligente-Revalidierungs-Abläufen vorhanden.
process.servicesarraySignierte Umschläge, erfasste Dokumente und andere Service-Ausgaben. Siehe unten.
process.state-Werte
WertBedeutung
PROCESS_STATE_CREATEDProzess erstellt; Benutzer hat die Journey noch nicht abgeschlossen.
AWAITING_FOR_DOCUMENTProzess ohne Ausweisdokument erstellt; wartet darauf, dass es über Prozessdokument setzen gesetzt wird. Nur vorhanden, wenn der Custom Flow optionale Dokumente erlaubt.
PROCESS_STATE_FINISHEDJourney abgeschlossen. Prüfen Sie result und authenticationInfo.
PROCESS_STATE_FAILEDVerarbeitungsfehler.
Inkonsistenz bei der State-Benennung

AWAITING_FOR_DOCUMENT folgt nicht der PROCESS_STATE_*-Präfixkonvention, die von den anderen States verwendet wird. Dies ist eine bekannte Inkonsistenz bei der Benennung in der aktuellen API.

process.result-Werte
WertBedeutung
PROCESS_RESULT_OKAlle Fähigkeiten haben positive Ergebnisse zurückgegeben.
PROCESS_RESULT_INVALID_IDENTITYMindestens eine Fähigkeit hat ein eindeutig negatives Ergebnis zurückgegeben (z. B. Lebenderkennung fehlgeschlagen, Identität nicht übereinstimmend).
PROCESS_RESULT_ERRORFehler bei der Ergebnisverarbeitung.
PROCESS_RESULT_EXPIREDProzess ist abgelaufen, bevor die Journey abgeschlossen wurde.
PROCESS_RESULT_UNSPECIFIEDProzess noch nicht abgeschlossen.
Fähigkeitsergebnisse in authenticationInfo

Alle Felder werden unabhängig vom Flow immer zurückgegeben. Felder für nicht im Flow verwendete Fähigkeiten geben *_UNSPECIFIED zurück.

Abgekürzte Enum-Werte

Kurzwerte (z. B. livenessResult = LIVE, authenticationResult = INCONCLUSIVE) entsprechen direkt den hier dokumentierten vollständigen Enum-Werten (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) — das Präfix wird der Kürze halber weggelassen.

FeldFähigkeitMögliche Werte
authenticationId—Eindeutige Kennung für diesen Authentifizierungsversuch.
livenessResultLebenderkennungLIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED
authenticationResultIdentitätsprüfungAUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResultBetrugseinstufung nach RisikoTRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED
bioTokenEngineResult1:1-ValidierungBIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResultIntelligente RevalidierungSMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResultAltersverifizierungID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.scoreEnabledRisiko-ScoreSCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.scoreRisiko-ScoreZahl von -100 bis +100. Vorhanden, wenn authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE und Risiko-Score aktiviert ist.
serproResult.scoreSerpro-Ähnlichkeitsabgleich0–100 (Ähnlichkeit); -1 (kein Gesicht für diesen CPF hinterlegt); -2 (Integrationsfehler).
process.services-Felder
Gemischte Namenskonventionen in services

Das Array services verwendet camelCase für Umschlag-Ebenen-Felder (envelopeId, documentIds) und snake_case für Dokument-Ebenen-Felder (doc_id, consent_granted, face_match usw.). Dies spiegelt die tatsächliche API-Antwort wider — beide Konventionen sind absichtlich und kein Dokumentationsfehler.

FeldTypBeschreibung
envelopeIdstring (UUID)Kennung des signierten Umschlags.
documentIdsarray of stringsIDs der in diesem Service erfassten Dokumente.
consent_grantedbooleanOb der Benutzer der Datenweitergabe zugestimmt hat.
documentsarrayErfasste Dokumente mit OCR-Daten und Validierungsergebnissen.
documents[].doc_idstringDokumentkennung.
documents[].typifiedbooleanOb der Dokumenttyp erfolgreich identifiziert wurde.
documents[].cpf_matchbooleanOb der CPF auf dem Dokument mit dem angegebenen CPF übereinstimmt (nur Brasilien).
documents[].face_matchbooleanOb das Selfie mit dem Foto auf dem Dokument übereinstimmt.
documents[].validate_docbooleanOb das Dokument die Authentizitätsprüfung bestanden hat.
documents[].reused_docbooleanOb dieses Dokument von einem früheren Prozess wiederverwendet wurde.
documents[].signed_urlstringVorsignierte URL zum Herunterladen des Dokument-PDFs (5 Minuten gültig — erneut abrufen zum Erneuern).
documents[].doc.versionintegerOCR-Schema-Version.
documents[].doc.codestringKurzer Dokumenttyp-Code (z. B. CNH). Siehe Dokumenttypen und OCR-Felder für alle Werte und die Herleitung des Codes.
documents[].doc.dataobjectExtrahierte OCR-Felder. Der Inhalt variiert je nach Dokumenttyp — die vollständige Übersicht finden Sie in der vollständigen Feldreferenz. Die Feldnamen in doc.data (z. B. nomeCivil, dataNascimento) werden auf Portugiesisch zurückgegeben — das sind die tatsächlichen Werte, die von der OCR-Engine erzeugt werden.

Fehlercodes​

CodeNachrichtBeschreibung
3process id is invalidWenn die Prozess-ID ungültig ist.

Polling vs. Webhook​

Sie können diesen Endpunkt abfragen, um den Fortschritt zu prüfen, aber das empfohlene Muster ist, einen Webhook zu abonnieren und diesen Endpunkt nur als Fallback aufzurufen. Siehe Webhooks und Ereignisse.

Nächste Schritte​

Zuletzt aktualisiert am