Récupérer un processus existant par son identifiant. Selon le contrat de l'API, le résultat est déjà renvoyé de manière synchrone à la création du processus — utilisez cet endpoint pour les nouvelles interrogations, l'audit et le support.
Avant de récupérer le processus, consultez notre configuration de webhook et nos stratégies de fallback — cliquez ici.
Endpoint
| Environnement | URL |
|---|---|
| Production | GET https://api.idcloud.unico.app/client/v1/process/{processId} |
| Sandbox | GET https://api.idcloud.uat.unico.app/client/v1/process/{processId} |
Requête
| En-tête | Valeur |
|---|---|
Authorization | Bearer <access_token> |
| Paramètre | Type | Requis | Description |
|---|---|---|---|
processId | string (UUID) | oui | Identifiant du processus renvoyé par Créer un processus. |
Exemple
- cURL
- Node.js
curl -X GET https://api.idcloud.unico.app/client/v1/process/$PROCESS_ID \
-H "Authorization: Bearer $TOKEN"
import fetch from 'node-fetch';
const res = await fetch(
`https://api.idcloud.unico.app/client/v1/process/${processId}`,
{ headers: { Authorization: `Bearer ${accessToken}` } }
);
const { process: proc } = await res.json();
Réponses
{
"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
}
}
| Champ | Signification |
|---|---|
id | UUID du processus ; la clé utilisée pour interroger et suivre le flux. |
flow | Type de parcours exécuté (ex. id_r2, idlivetrust_r2, idtrust_r2, ...). |
callbackUri | URI de callback vers laquelle l'application cliente est redirigée à la fin du flux. |
userRedirectUrl | URL complète de la page CbU que l'utilisateur ouvre pour effectuer le parcours (contient l'id et les indicateurs de comportement). |
state | État du cycle de vie du processus (ex. PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED). |
result | Verdict final de l'évaluation. Valeurs PROCESS_RESULT_* (ex. APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Concluant uniquement lorsque state = PROCESS_STATE_FINISHED. |
createdAt | Horodatage de création du processus (UTC). |
finishedAt | Horodatage de fin du processus (UTC). |
person | Sous-objet contenant les données de la personne vérifiée. |
purpose | Finalité du processus (ex. personAuthentication, enregistrement de personne). |
services | Liste des services additionnels attachés au processus ; vide en l'absence de service. |
authenticationInfo.authenticationId | ID de l'événement d'authentification d'identité généré par le flux. |
capacities | Capacités/produits utilisés. Valeurs PROCESS_CAPACITY_* (ex. IDCLOUDONE). |
expiresAt | Horodatage d'expiration du processus/lien (UTC). |
token | Jeton de session/accès associé au processus (peut être vide). |
companyData | Sous-objet contenant les données de l'entreprise/tenant propriétaire du processus. |
simulated | Booléen ; indique s'il s'agit d'un processus de simulation/sandbox (true) ou réel (false). |
| Champ | Signification |
|---|---|
duiType | Type du document d'identification unique. Valeurs DUI_TYPE_* (ex. BR_CPF). |
duiValue | Valeur du document (ex. le numéro de CPF). |
friendlyName | Nom convivial/surnom de la personne (texte libre, non validé). |
email | E-mail de la personne ; peut être vide. |
phone | Numéro de téléphone au format E.164 (code pays + code régional + numéro). |
notifications | Liste des canaux de notification. Chaque élément porte notificationChannel avec des valeurs NOTIFICATION_CHANNEL_* (ex. WHATSAPP, SMS, EMAIL). |
phoneCountryCodeAlpha3 | Code pays ISO alpha-3 du numéro de téléphone (ex. BRA) ; peut être vide. |
| Champ | Signification |
|---|---|
branchId | Identifiant de la filiale du tenant ; vide lorsqu'il n'y a pas de segmentation par filiale. |
countryCode | Pays de l'entreprise en ISO alpha-3 (ex. BRA). |
process.services[].documents[].doc.code rapporte le type de document sous l'une de deux formes. Les documents traités par le module de documents d'Unico, y compris les documents réutilisés, portent un code court en majuscules (CNH). Les processus créés uniquement via l'API portent généralement le type de dictionnaire complet (unico.moja.dictionary.br.cnh.v2.Cnh), mais peuvent aussi porter un code court. Gérez les deux formes, quel que soit le mode d'intégration.
Le code court ne porte ni le pays ni la version du schéma ; la version est renvoyée séparément dans doc.version.
Dans la forme courte, les types de documents qui utilisent le schéma unifié — unified_schema dans la référence des champs — sont rapportés sous forme du type identifié pendant la capture, en majuscules. Les valeurs les plus courantes sont IDCARD, DRIVERLICENSE, PASSPORT et VOTERID, mais la liste est ouverte : les autres types identifiés pendant la capture sont renvoyés tels quels, en majuscules. Gérez les valeurs hors de cette liste.
Les passeports américains conservent leur variante au lieu d'être ramenés à PASSPORT : POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT et REFUGEEPASSPORT sont également renvoyés.
Par exemple, unico.moja.dictionary.ar.generic.v1.IdCard et unico.moja.dictionary.us.generic.v1.PolycarbonatePassport sont rapportés comme IDCARD et POLYCARBONATEPASSPORT.
Les types de documents qui utilisent leur propre schéma de champs — listés sous specific_document_schemas dans la référence des champs — sont présentés dans le tableau ci-dessous. Utilisez le type de dictionnaire pour rechercher chaque schéma dans ce fichier.
| Pays | doc.code | Type de dictionnaire | Document |
|---|---|---|---|
| BR | RG | unico.moja.dictionary.br.rg.v2.Rg | RG |
| BR | CNH | unico.moja.dictionary.br.cnh.v2.Cnh | CNH (permis de conduire) |
| BR | CIN | unico.moja.dictionary.br.cin.v1.Cin | CIN |
| BR | PASSAPORTE | unico.moja.dictionary.br.passaporte.v1.Passaporte | Passeport |
| MX | INE | unico.moja.dictionary.mx.ine.v1.Ine | Titre d'électeur INE |
| MX | LPC | unico.moja.dictionary.mx.lpc.v1.Lpc | Licencia para conducir (permis de conduire) |
| MX | PASAPORTE | unico.moja.dictionary.mx.pasaporte.v1.Pasaporte | Passeport |
| — | UNKNOWN | unico.moja.dictionary.other.unknown.v1.Unknown | Le type n'a pas pu être identifié, ou il s'agit d'un type brésilien ou mexicain sans schéma propre — doc.data est vide |
Les documents brésiliens et mexicains utilisent uniquement les schémas spécifiques ci-dessus. Un document brésilien ou mexicain de tout autre type — par exemple, une carte de résident mexicaine — est rapporté comme UNKNOWN, et non avec le schéma unifié.
PASSAPORTE et PASAPORTE sont des documents différentsLe passeport brésilien est PASSAPORTE (double S) et le mexicain est PASAPORTE (S simple), chacun reflétant l'orthographe de son propre dictionnaire. Ce n'est pas une faute de frappe — ne traitez pas les deux valeurs comme équivalentes.
Aucune extraction OCR n'est effectuée et aucun champ n'est rapporté dans doc.data lorsque doc.code est UNKNOWN.
Les clients au Brésil peuvent recevoir le payload complet du processusLa structure globale de la réponse reste la même — le résultat unique est la valeur par défaut.

La structure globale de la réponse reste la même — le résultat unique est la valeur par défaut.
Les intégrations au Brésil peuvent recevoir l'objet processus complet ci-dessous, avec les résultats par capacité dans authenticationInfo.
{
"process": {
"id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
"flow": "iddocs_r2",
"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": "USE_CASE_LOGIN",
"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_UNSPECIFIED",
"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": "BRA"
},
"bioTokenData": {
"referenceProcessId": "ref-proc-123",
"authenticationId": "auth-ref-123"
},
"services": [
{
"consent_granted": true,
"documents": [
{
"doc_id": "doc-abc-123",
"share_id": "share-abc-123",
"typified": true,
"cpf_match": true,
"validate_doc": true,
"face_match": true,
"verified": true,
"reused_doc": false,
"signed_url": "https://example.com/doc?token=xyz",
"doc": {
"version": 2,
"code": "CNH",
"data": {
"numero": "044589731564",
"cpfNumero": "12345678909",
"nomeCivil": "Luke Skywalker",
"dataNascimento": "1990-05-12T00:00:00Z",
"dataExpiracao": "2027-12-07T00:00:00Z",
"categoria": "B"
}
}
}
]
}
]
}
}
| Champ | Type | Description |
|---|---|---|
process.id | string (UUID) | Identifiant du processus. |
process.flow | string | Identifiant du flux envoyé à la création. |
process.callbackUri | string | URL de callback configurée pour les événements du processus. |
process.userRedirectUrl | string | URL pour rediriger l'utilisateur une fois le parcours terminé. |
process.state | enum | État actuel du processus. Voir les valeurs ci-dessous. |
process.result | enum | Résultat de la vérification. Présent uniquement lorsque state = PROCESS_STATE_FINISHED. |
process.createdAt | string (datetime) | Horodatage ISO 8601 de la création du processus. |
process.finishedAt | string (datetime) | Horodatage ISO 8601 de fin du processus. Présent uniquement lorsque state = PROCESS_STATE_FINISHED. |
process.expiresAt | string (datetime) | Horodatage ISO 8601 d'expiration du processus. |
process.purpose | string | Finalité du processus telle que configurée dans le flux. |
process.clientReference | string | Référence côté client optionnelle pour l'indexation dans le portail. |
process.useCase | string | Identifiant du scénario associé au flux. |
process.capacities | array of strings | Liste des capacités activées dans ce processus. |
process.token | string | JWT sign é pour l'intégration SDK. |
process.person | object | Identification fournie à la création. |
process.person.notifications | array | Canaux de notification configurés pour le parcours (ex. email). |
process.authenticationInfo | object | Résultats par capacité. Voir ci-dessous. |
process.companyData | object | Contexte de l'entreprise et de la filiale. |
process.companyData.branchId | string | Identifiant de la filiale. |
process.companyData.countryCode | string | Code pays ISO 3166-1 alpha-3 (ex. BRA). |
process.bioTokenData | object | Informations du processus de référence — présent uniquement dans les flux de Validation 1:1 et de Revalidation intelligente. |
process.services | array | Enveloppes signées, documents capturés, et autres sorties de service. Voir ci-dessous. |
| Valeur | Signification |
|---|---|
PROCESS_STATE_CREATED | Processus créé ; l'utilisateur n'a pas encore terminé le parcours. |
PROCESS_STATE_AWAITING_FOR_DOCUMENT | Processus créé sans document d'identification. Présent uniquement lorsque le Custom Flow autorise un document optionnel. Envoyez le document avec Définir le document du processus. |
PROCESS_STATE_FINISHED | Parcours terminé. Vérifiez result et authenticationInfo. |
PROCESS_STATE_FAILED | Erreur de traitement. |
| Valeur | Signification |
|---|---|
PROCESS_RESULT_OK | Toutes les capacités ont renvoyé des résultats positifs. |
PROCESS_RESULT_INVALID_IDENTITY | Au moins une capacité a renvoyé un résultat négatif définitif (ex. échec de la détection de vie, identité non correspondante). |
PROCESS_RESULT_ERROR | Erreur pendant le traitement du résultat. |
PROCESS_RESULT_EXPIRED | Le processus a expiré avant que le parcours ne soit terminé. |
PROCESS_RESULT_UNSPECIFIED | Processus pas encore terminé. |
Tous les champs sont toujours renvoyés, quel que soit le flux. Les champs des capacités non utilisées dans le flux renvoient *_UNSPECIFIED.
Les valeurs abrégées (ex. livenessResult = LIVE, authenticationResult = INCONCLUSIVE) correspondent directement aux valeurs d'enum complètes documentées ici (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) — le préfixe est omis par souci de concision.
| Champ | Capacité | Valeurs possibles |
|---|---|---|
authenticationId | — | Identifiant unique de cette tentative d'authentification. |
livenessResult | Détection de Vie | LIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED |
authenticationResult | Vérification d'identité | AUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED |
identityFraudstersResult | Classification du risque de fraude | TRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED |
bioTokenEngineResult | Validation 1:1 | BIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED |
smartRevalidationResult | Revalidation intelligente | SMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED |
idAgeResult | Vérification de l'âge | ID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED |
scoreEngineResult.scoreEnabled | Score de Risque | SCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED |
scoreEngineResult.score | Score de Risque | Nombre de -100 à +100. Présent lorsque authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE et que le Score de Risque est activé. |
serproResult.score | Retour de similarité Serpro | 0–100 (similarité) ; -1 (aucun visage enregistré pour ce CPF) ; -2 (erreur d'intégration). |
deviceMetadata | Métadonnées de l'Appareil | Objet avec status (found, not_found, unavailable) et les données de l'appareil. Absent lorsque la capacité n'est pas activée dans le flux. |
services contient un élément par module terminé dans le processus : la dernière exécution terminée de chaque module, et seulement tant que le processus est PROCESS_STATE_FINISHED ou PROCESS_STATE_AWAITING_FOR_DOCUMENT. Les processus créés uniquement via l'API portent leur élément de document quel que soit leur état. Un élément de capture de documents porte documents et consent_granted. Un élément de signature électronique porte envelope_id et document_ids. Les éléments n'ont pas de champ de type et leur ordre n'est pas stable : identifiez chacun par ses clés, et non par sa position, et ignorez les éléments que vous ne reconnaissez pas. Les clés sont en snake_case, sauf celles de doc.data, qui suivent le schéma du document (ex. nomeCivil).
| Champ | Type | Description |
|---|---|---|
consent_granted | boolean | Élément de capture de documents. Indique si l'utilisateur a accordé le consentement au partage des documents avec votre entreprise. |
documents | array | Élément de capture de documents. Documents capturés avec les données OCR et les résultats de validation. |
documents[].doc_id | string | Identifiant du document. |
documents[].share_id | string | Identifiant du partage que l'utilisateur a accordé à votre entreprise pour ce processus. |
documents[].typified | boolean | Indique si le type de document a été identifié. |
documents[].cpf_match | boolean | Brésil uniquement. Indique si le CPF du document correspond au CPF envoyé à la création. Toujours présent pour les entreprises dont le pays est défini sur le Brésil ; omis pour les autres pays et pour les entreprises sans pays défini. |
documents[].validate_doc | boolean | Brésil uniquement. Indique si le document a réussi la validation de documents d'Unico. Toujours présent pour les entreprises dont le pays est défini sur le Brésil (false lorsque la validation n'a pas été exécutée) ; omis pour les autres pays et pour les entreprises sans pays défini. |
documents[].face_match | boolean or null | Indique si le selfie correspond à la photo du document. null signifie que la vérification n'a pas été exécutée — ce n'est pas un résultat négatif. |
documents[].verified | boolean or null | true uniquement lorsque le type de document est connu, que le document n'a pas été supprimé, que face_match vaut true et que le document a réussi les contrôles de qualité. false sinon, y compris lorsque face_match n'a pas été exécuté. null lorsque le processus n'est pas passé par le module de documents. |
documents[].reused_doc | boolean | Indique si ce document a été réutilisé à partir d'un processus précédent. |
documents[].signed_url | string | URL signée de courte durée pour télécharger l'image du document. Elle expire : ne la stockez pas et ne comptez pas sur une durée de validité fixe ; appelez à nouveau cet endpoint pour en obtenir une nouvelle. |
documents[].doc.version | integer | Version du dictionnaire du type de document (ex. 2 pour unico.moja.dictionary.br.cnh.v2.Cnh). |
documents[].doc.code | string | Type de document, sous forme de code court (ex. CNH) ou de type de dictionnaire complet (ex. unico.moja.dictionary.br.cnh.v2.Cnh). Les documents traités par le module de documents portent le code court. Gérez les deux. Voir Types de documents et champs OCR pour toutes les valeurs et la manière dont le code est dérivé. |
documents[].doc.data | object | Champs OCR extraits. Le contenu varie selon le type de document — voir la référence complète des champs pour le catalogue complet. Les noms de champs suivent le schéma du document : portugais pour les documents brésiliens (ex. nomeCivil, dataNascimento), espagnol pour les documents mexicains et anglais pour le schéma unifié. |
envelope_id | string (UUID) | Élément de signature électronique. Identifiant de l'enveloppe signée. |
document_ids | array of strings | Élément de signature électronique. IDs des documents de l'enveloppe. |
Dans un processus créé uniquement via l'API, l'élément de document provient de l'appel à l'API, et non du module de documents d'Unico, et certaines valeurs diffèrent du tableau ci-dessus :
consent_grantedvaut toujoursfalse: votre entreprise recueille le consentement, et Unico ne le suit pas.share_idetsigned_urlsont vides.face_matchvaut toujourstrueoufalse, jamaisnull.verifiedvaut toujoursnull.doc.versionvaut0.doc.codeporte généralement le type de dictionnaire complet (ex.unico.moja.dictionary.br.cnh.v2.Cnh), mais peut porter un code court.doc.datavautnulllorsque les données OCR n'ont pas pu être lues.
Codes d'erreur
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 429 Too Many Requests
- 500 Internal Server Error
| Code | Message | Description |
|---|---|---|
3 | process id is invalid | Lorsque l'ID du processus est invalide. |
| Code | Message | Description |
|---|---|---|
| — | Jwt header is an invalid JSON | Lorsque le jeton d'accès utilisé contient des caractères incorrects. |
| — | Jwt is expired | Lorsque le jeton d'accès utilisé a expiré. |
| Code | Message | Description |
|---|---|---|
5 | error getting process: rpc error: code = NotFound desc = process not found | Lorsque l'ID du processus n'a pas été trouvé. |
Limite de débit atteinte. Lorsque votre système reçoit une erreur HTTP 429, vous devez implémenter des mécanismes pour prévenir les défaillances en cascade et éviter d'aggraver la restriction.
Bonnes pratiques :
- Période de repos (backoff) : Arrêtez ou réduisez immédiatement les requêtes suivantes de votre système. Ne réessayez pas continuellement les requêtes échouées dans une boucle serrée.
- File d'attente et limitation (Queueing & throttling) : Mettez en mémoire tampon ou en file d'attente les requêtes sortantes de votre côté pour contrôler le flux de trafic avant de les renvoyer.
- Backoff exponentiel avec jitter : Lors des nouvelles tentatives, augmentez le temps d'attente de manière exponentielle entre les essais (par exemple, 1 s, 2 s, 4 s, 8 s) et ajoutez un petit délai aléatoire ("jitter") pour éviter un effet de troupeau où toutes les requêtes en file d'attente réessaient exactement à la même milliseconde.
Envoyer continuellement des requêtes vers un endpoint soumis à une limite de débit sans appliquer de backoff peut prolonger la période de restriction et impacter sévèrement le débit opérationnel de votre système. Limiter correctement les requêtes de votre côté garantit une intégration plus fluide et plus résiliente.
Pour les limites par défaut, l'augmentation des requêtes et des détails supplémentaires, consultez Limites de débit.
| Code | Message | Description |
|---|---|---|
99999 | Internal failure! Try again later | Lorsqu'il y a une erreur interne. |
Polling ou webhook
Vous pouvez interroger (polling) cet endpoint pour vérifier la progression, mais le pattern recommandé consiste à vous abonner à un webhook et à n'appeler cet endpoint qu'en fallback. Voir Webhooks et événements.
Prochaines étapes
- Pour le selfie capturé, voir Récupérer le selfie.
- Pour le pack de preuves d'audit, voir Récupérer le jeu de preuves.