Get Process

warning

Before retrieving the process, review our webhook configuration and fallback strategies — click here.

In the API contract, the POST /processes/v1 response is already the final result. This endpoint exists for re-querying — for example, when you need to inspect a process you persisted earlier, or audit a previous transaction.

Endpoint

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

Request

Headers

Header	Value
Authorization	Bearer <access_token>
APIKEY	Provisioned API key.

Path parameters

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

Example

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();

Responses

200 OK

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

Response fields depend on your APIKey

The example above shows all possible capability fields. Your actual response will only include fields for the capabilities enabled in your APIKey configuration — fields for disabled capabilities are omitted entirely. Contact your Unico project manager to enable or adjust capabilities.

Field	Type	Description
id	string (UUID)	Process identifier.
status	integer	1 (processing), 2 (divergence), 3 (finished with success), 4 (canceled), 5 (error).
unicoId.result	string	yes, no, inconclusive — see Identity Verification.
riskLevel.result	string	not_approved, critical_risk, high_risk, inconclusive — see Fraud Risk Classification.
idFace.result	string	FOUND, NOT_FOUND — see Face Identifier.
idFace.personId	string	Stable opaque identifier for the face. Present only when idFace.result = FOUND.
identityFraudsters.result	string	Deprecated. Use riskLevel instead. Clients with ongoing integrations may continue using it while coordinating the migration with their project team.
government.serpro	integer	Serpro similarity score (0–100, -1, -2). Available in Brazil only. See Serpro Similarity.
liveness	integer	1 (passed), 2 (failed) — see Liveness.
score	integer	Probabilistic risk score. Present when unicoId.result = inconclusive and risk score orchestration is active. Positive values indicate higher probability of being the holder; negative values indicate higher risk. Available in Brazil only.

400 Bad Request

The processId path parameter is missing or malformed. See Error Codes below.

403 Forbidden

Bearer token or APIKEY missing, expired, or invalid.

404 Not Found

The processId does not exist or does not belong to the authenticated tenant.

410 Gone

The process exists but resulted in an error. Returns only id and status: 5.

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

Unexpected server error.

When to use this endpoint

The API contract returns results synchronously, so most integrations don't need this endpoint. Use it when:

• You persisted only the processId and need to retrieve the full result later (audit, support).
• You suspect the original response was lost in transit (network error after the platform completed the work).
• You're building a back-office tool that reviews historical processes.

Error Codes

400 Bad Request

Code	Message	Description
20023	O parâmetro processId não foi informado.	The process id parameter is missing.
20002	O parâmetro APIKey não foi informado.	The APIKEY parameter is missing from the request header.
20001	O parâmetro authtoken não foi informado.	The integration token parameter is missing from the request header.

404 Not Found

Code	Message	Description
50001	O processo informado não foi encontrado.	The process does not exist in the database.

403 Forbidden

Code	Message	Description
30017	User does not have permission to perform this action.	Malformed JWT or user without permission to perform this operation.
10502	O token informado está expirado.	When the access-token used has expired.
10501	O token informado é inválido.	The authentication token is invalid.
10201	O AppKey informado é inválido.	The APIKEY parameter has not been entered or does not exist.

410 Gone

The process exists but resulted in an error. Returns only id and status: 5.

500 Internal Server Error

Code	Message	Description
99999	Internal failure! Try again later	When there is an internal error.