Retrieve an existing process by its identifier. Per the API contract, the result is already returned synchronously on process creation — use this endpoint for re-queries, auditing, and support.
Before retrieving the process, review our webhook configuration and fallback strategies — click here.
Endpoint
| Environment | URL |
|---|---|
| Production | GET https://api.idcloud.unico.app/client/v1/process/{processId} |
| Sandbox | GET https://api.idcloud.uat.unico.app/client/v1/process/{processId} |
Request
| Header | Value |
|---|---|
Authorization | Bearer <access_token> |
| Parameter | Type | Required | Description |
|---|---|---|---|
processId | string (UUID) | yes | Process identifier returned by Create Process. |
Example
- 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();
Responses
{
"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
}
}
| Field | Meaning |
|---|---|
id | Process UUID; the key used to query and track the flow. |
flow | Type of journey executed (e.g. id_r2, idlivetrust_r2, idtrust_r2, ...). |
callbackUri | Callback URI the client app is redirected to at the end of the flow. |
userRedirectUrl | Full URL of the CbU page the user opens to run the journey (carries the id and behavior flags). |
state | Process lifecycle state (e.g. PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED). |
result | Final verdict of the evaluation. PROCESS_RESULT_* values (e.g. APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Only conclusive when state = PROCESS_STATE_FINISHED. |
createdAt | Process creation timestamp (UTC). |
finishedAt | Process completion timestamp (UTC). |
person | Sub-object with the data of the person being verified. |
purpose | Purpose of the process (e.g. personAuthentication, person registration). |
services | List of additional services attached to the process; empty when none. |
authenticationInfo.authenticationId | ID of the identity authentication event generated by the flow. |
capacities | Capabilities/products used. PROCESS_CAPACITY_* values (e.g. IDCLOUDONE). |
expiresAt | Process/link expiration timestamp (UTC). |
token | Session/access token associated with the process (may be empty). |
companyData | Sub-object with the data of the company/tenant that owns the process. |
simulated | Boolean; whether this is a simulation/sandbox process (true) or a real one (false). |
| Field | Meaning |
|---|---|
duiType | Type of the unique identification document. DUI_TYPE_* values (e.g. BR_CPF). |
duiValue | Document value (e.g. the CPF number). |
friendlyName | Friendly name/nickname for the person (free text, not validated). |
email | Person's email; may be empty. |
phone | Phone number in E.164 format (country code + area code + number). |
notifications | List of notification channels. Each item carries notificationChannel with NOTIFICATION_CHANNEL_* values (e.g. WHATSAPP, SMS, EMAIL). |
phoneCountryCodeAlpha3 | ISO alpha-3 country code of the phone number (e.g. BRA); may be empty. |
| Field | Meaning |
|---|---|
branchId | Identifier of the tenant's branch; empty when not segmented by branch. |
countryCode | Company's country in ISO alpha-3 (e.g. BRA). |
process.services[].documents[].doc.code reports the document type as a short uppercase code. unico.moja.dictionary.br.cnh.v2.Cnh becomes CNH.
The short code carries neither the country nor the schema version; the version is returned separately in doc.version.
In the short form, document types that use the unified schema — unified_schema in the field reference — are reported as the uppercased type identified during capture. The most common values are IDCARD, DRIVERLICENSE, PASSPORT and VOTERID, but the list is open: other types identified during capture are returned as they are, uppercased. Handle values outside this list.
U.S. passports keep their variant instead of collapsing into PASSPORT: POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT and REFUGEEPASSPORT are also returned.
For instance, unico.moja.dictionary.ar.generic.v1.IdCard and unico.moja.dictionary.us.generic.v1.PolycarbonatePassport are reported as IDCARD and POLYCARBONATEPASSPORT.
Document types that use their own field schema — listed under specific_document_schemas in the field reference — are shown in the table below. Use the dictionary type to look each schema up in that file.
| Country | doc.code | Dictionary type | Document |
|---|---|---|---|
| BR | RG | unico.moja.dictionary.br.rg.v2.Rg | RG |
| BR | CNH | unico.moja.dictionary.br.cnh.v2.Cnh | CNH (driver's license) |
| BR | CIN | unico.moja.dictionary.br.cin.v1.Cin | CIN |
| BR | PASSAPORTE | unico.moja.dictionary.br.passaporte.v1.Passaporte | Passport |
| MX | INE | unico.moja.dictionary.mx.ine.v1.Ine | INE voter credential |
| MX | LPC | unico.moja.dictionary.mx.lpc.v1.Lpc | Licencia para conducir (driver's license) |
| MX | PASAPORTE | unico.moja.dictionary.mx.pasaporte.v1.Pasaporte | Passport |
| — | UNKNOWN | unico.moja.dictionary.other.unknown.v1.Unknown | Type could not be identified, or a Brazilian or Mexican type without its own schema — doc.data is empty |
Brazilian and Mexican documents use only the specific schemas above. A Brazilian or Mexican document of any other type — for example, a Mexican resident card — is reported as UNKNOWN, not with the unified schema.
PASSAPORTE and PASAPORTE are different documentsThe Brazilian passport is PASSAPORTE (double S) and the Mexican one is PASAPORTE (single S), each mirroring its own dictionary spelling. This is not a typo — do not treat the two values as equivalent.
No OCR extraction is performed and no field is reported in doc.data when doc.code is UNKNOWN.
Clients in Brazil may receive the full process payloadThe overall response structure stays the same — the single result is the default.

The overall response structure stays the same — the single result is the default.
Integrations in Brazil may receive the full process object below, with per-capability results 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": "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"
}
}
}
]
}
]
}
}
| Field | Type | Description |
|---|---|---|
process.id | string (UUID) | Process identifier. |
process.flow | string | Flow identifier sent on creation. |
process.callbackUri | string | Callback URL configured for process events. |
process.userRedirectUrl | string | URL to redirect the user after the journey is completed. |
process.state | enum | Current process state. See values below. |
process.result | enum | Verification outcome. Present only when state = PROCESS_STATE_FINISHED. |
process.createdAt | string (datetime) | ISO 8601 timestamp when the process was created. |
process.finishedAt | string (datetime) | ISO 8601 timestamp when the process finished. Present only when state = PROCESS_STATE_FINISHED. |
process.expiresAt | string (datetime) | ISO 8601 timestamp when the process expires. |
process.purpose | string | Purpose of the process as configured in the flow. |
process.clientReference | string | Optional client-side reference for indexing in the portal. |
process.useCase | string | Scenario identifier associated with the flow. |
process.capacities | array of strings | List of capabilities activated in this process. |
process.token | string | Signed JWT for SDK integration. |
process.person | object | Identification provided on creation. |
process.person.notifications | array | Notification channels configured for the journey (e.g. email). |
process.authenticationInfo | object | Per-capability results. See below. |
process.companyData | object | Company and branch context. |
process.companyData.branchId | string | Branch identifier. |
process.companyData.countryCode | string | ISO 3166-1 alpha-3 country code (e.g. BRA). |
process.bioTokenData | object | Reference process info — present only in 1:1 validation and Smart Revalidation flows. |
process.services | array | Signed envelopes, captured documents, and other service outputs. See below. |
| Value | Meaning |
|---|---|
PROCESS_STATE_CREATED | Process created; user has not yet completed the journey. |
PROCESS_STATE_AWAITING_FOR_DOCUMENT | Process created without an identification document; waiting for it to be set via Set Process Document. Only present when the Custom Flow allows optional document. |
PROCESS_STATE_FINISHED | Journey completed. Check result and authenticationInfo. |
PROCESS_STATE_FAILED | Processing error. |
| Value | Meaning |
|---|---|
PROCESS_RESULT_OK | All capabilities returned positive results. |
PROCESS_RESULT_INVALID_IDENTITY | At least one capability returned a definitive negative (e.g. liveness failed, identity not matched). |
PROCESS_RESULT_ERROR | Error during result processing. |
PROCESS_RESULT_EXPIRED | Process expired before the journey was completed. |
PROCESS_RESULT_UNSPECIFIED | Process not yet finished. |
All fields are always returned regardless of the flow. Fields for capabilities not used in the flow return *_UNSPECIFIED.
Shorthand values (e.g. livenessResult = LIVE, authenticationResult = INCONCLUSIVE) map directly to the full enum values documented here (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) — the prefix is omitted for brevity.
| Field | Capability | Possible values |
|---|---|---|
authenticationId | — | Unique identifier for this authentication attempt. |
livenessResult | Liveness | LIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED |
authenticationResult | Identity Verification | AUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED |
identityFraudstersResult | Fraud Risk Classification | TRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED |
bioTokenEngineResult | 1:1 Validation | BIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED |
smartRevalidationResult | Smart Revalidation | SMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED |
idAgeResult | Age Verification | ID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED |
scoreEngineResult.scoreEnabled | Risk Score | SCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED |
scoreEngineResult.score | Risk Score | Number from -100 to +100. Present when authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE and Risk Score is enabled. |
serproResult.score | Serpro Similarity | 0–100 (similarity); -1 (no face on file for this CPF); -2 (integration error). |
deviceMetadata | Device Metadata | Object with status (found, not_found, unavailable) and the device data. Absent when the capability is not enabled in the flow. |
services holds one item per module that ran in the process. A document capture item carries documents and consent_granted. An electronic signature item carries envelope_id and document_ids. Items have no type field: identify each one by its keys, and ignore items you do not recognize. Keys are snake_case, except those inside doc.data, which follow the document's schema (e.g. nomeCivil).
| Field | Type | Description |
|---|---|---|
consent_granted | boolean | Document capture item. Whether the user granted consent to share the documents with your company. |
documents | array | Document capture item. Captured documents with OCR data and validation results. |
documents[].doc_id | string | Document identifier. |
documents[].share_id | string | Identifier of the share the user granted to your company for this process. |
documents[].typified | boolean | Whether the document type was identified. |
documents[].cpf_match | boolean | Brazil only. Whether the CPF on the document matches the CPF sent on creation. Always present for companies in Brazil; omitted for other countries. |
documents[].validate_doc | boolean | Brazil only. Whether the document passed Unico's document validation. Always present for companies in Brazil (false when the validation did not run); omitted for other countries. |
documents[].face_match | boolean or null | Whether the selfie matches the photo on the document. null means the check did not run — it is not a negative result. |
documents[].verified | boolean or null | true only when the document type is known, the document was not deleted, face_match is true and the document passed the quality checks. false otherwise, including when face_match did not run. null when the process did not go through the document module. |
documents[].reused_doc | boolean | Whether this document was reused from a previous process. |
documents[].signed_url | string | Short-lived signed URL to download the document image. It expires: don't store it or rely on a fixed lifetime, and call this endpoint again to get a new one. |
documents[].doc.version | integer | Version of the document type's dictionary (e.g. 2 for unico.moja.dictionary.br.cnh.v2.Cnh). |
documents[].doc.code | string | Short document type code (e.g. CNH). See Document types and OCR fields for every value and how the code is derived. |
documents[].doc.data | object | Extracted OCR fields. Content varies by document type — see the full field reference for the complete catalog. Field names follow the document's schema: Portuguese for Brazilian documents (e.g. nomeCivil, dataNascimento), Spanish for Mexican documents and English for the unified schema. |
envelope_id | string (UUID) | Electronic signature item. Signed envelope identifier. |
document_ids | array of strings | Electronic signature item. IDs of the documents in the envelope. |
Clients in Mexico may receive the RENAPO Verification blockThe response keeps the same structure and adds the idGov block.

The response keeps the same structure and adds the idGov block.
Integrations in Mexico with RENAPO Verification enabled receive an additional idGov block under authenticationInfo, with the record RENAPO holds for the user's CURP. It is a separate answer from the identity result.
{
"process": {
"id": "11111111-2222-3333-4444-555555555555",
"state": "PROCESS_STATE_FINISHED",
"result": "PROCESS_RESULT_APPROVED",
"person": {
"duiType": "DUI_TYPE_MX_CURP",
"duiValue": "PUEA880304MDFRJN04"
},
"authenticationInfo": {
"authenticationId": "22222222-3333-4444-5555-666666666666",
"idGov": {
"government_valid": true,
"curp": "PUEA880304MDFRJN04",
"government_name": "ANA PRUEBA EJEMPLO"
}
},
"companyData": { "countryCode": "MEX" }
}
}
Other fields and the remaining idGov keys are omitted for brevity. For the full table of idGov fields, see RENAPO Verification.
| Field | Type | Description |
|---|---|---|
authenticationInfo.idGov | object | RENAPO record for the CURP. Absent when the capability is not enabled. {} when RENAPO did not respond. Mexico only. See RENAPO Verification. |
Error Codes
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 429 Too Many Requests
- 500 Internal Server Error
| Code | Message | Description |
|---|---|---|
3 | process id is invalid | When the process ID is invalid. |
| Code | Message | Description |
|---|---|---|
| — | Jwt header is an invalid JSON | When the access token used contains incorrect characters. |
| — | Jwt is expired | When the access token used has expired. |
| Code | Message | Description |
|---|---|---|
5 | error getting process: rpc error: code = NotFound desc = process not found | When the process ID was not found. |
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.
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.
| Code | Message | Description |
|---|---|---|
99999 | Internal failure! Try again later | When there is an internal error. |
Polling vs webhook
You can poll this endpoint to check progress, but the recommended pattern is to subscribe to a webhook and only call this endpoint as a fallback. See Webhooks and Events.
What's next
- For the captured selfie, see Get Selfie.
- For the evidence audit bundle, see Get Evidence Set.