Get ProcessGET

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.

warning

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

Headers

Header	Value
Authorization	Bearer <access_token>

Path parameters

Parameter	Type	Required	Description
processId	string (UUID)	yes	Process identifier returned by Create Process.

Example

cURL

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

Node.js

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

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

Process fields

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. PROCESS_STATE_* values (e.g. CREATED, FAILED, FINISHED, AWAITING_FOR_DOCUMENT, 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).

Person fields

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.

Company data fields

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).

Document types and OCR fields

Document types that use the unified schema — unified_schema in the field reference — are reported as the uppercased type identified during capture: IDCARD, DRIVERLICENSE, PASSPORT or VOTERID. U.S. passports keep their variant instead of collapsing into PASSPORT, so values such as POLYCARBONATEPASSPORT, PASSPORTCARD and PAPERPASSPORT 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.

process.services[].documents[].doc.code reports the document type as a short uppercase code. unico.moja.dictionary.br.cnh.v2.Cnh becomes CNH. The code carries neither the country nor the schema version; the version is returned separately in doc.version.

Specific schemas

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 — doc.data is empty

PASSAPORTE and PASAPORTE are different documents

The 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.

Error Codes

400 Bad Request

Code	Message	Description
3	process id is invalid	When the process ID is invalid.

401 Unauthorized

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.

404 Not Found

Code	Message	Description
5	error getting process: rpc error: code = NotFound desc = process not found	When the process ID was not found.

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.

warning

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