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

The contract is unique — the idCloud.result field carries the consolidated verdict of the capabilities used.

Unico consolidates the results of the executed capabilities into a single idCloud.result, ready to decide your flow's next step — with no need to orchestrate individual results.

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "idCloud": {
    "result": "approved"
  }
}

Field	Type	Description
id	string (UUID)	Process identifier.
status	integer	1 (processing), 2 (divergence), 3 (finished with success), 4 (canceled), 5 (error).

Possible result values

idCloud.result	Meaning	Recommended action
approved	Real person and validated identity.	Proceed with the flow.
denied	Identity not validated, liveness check failed, or extreme risk identified.	End the flow or redirect to an alternative flow.
critical-risk	Critical risk level identified.	End the flow or route to manual review.
high-risk	High risk level identified.	Route to manual review or an alternative flow.
retry	Insufficient capture or score to evaluate.	Ask the user for a new capture.
inconclusive	Not enough evidence for a verdict.	Route to manual review or an alternative flow.

The returned values depend on the recipe configured in your APIKey. See Flows for the result values each recipe can return.

Clients in Brazil may receive the response by capability

The overall response structure stays the same — the single result is the default.

Integrations in Brazil may receive the open, per-capability results. Each capability enabled in the APIKey adds its own block to the response — fields for disabled capabilities are omitted.

{
  "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,
  "idAge": {
    "result": "yes"
  },
  "cardholderVerification": {
    "result": "approved"
  }
}

Field	Type	Description
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 — see Face Identifier.
idFace.personId	string	Stable opaque identifier for the face, returned alongside idFace.result = FOUND. When no face can be identified in the image, the process returns error 20532 instead of an idFace block.
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.
idAge.result	string	yes, no, inconclusive — see Age Verification. Available in Brazil only.
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.
cardholderVerification.result	string	approved, unsure — see Cardholder Verification. Absent while status is not yet 3 (finished). Available in Brazil only.

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.

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.

Flows

A recipe is the combination of capabilities (liveness, identity verification, risk signals, documents...) configured in your project's APIKey. It defines what Unico executes in each process and how the results are consolidated into the single result — you don't need to orchestrate anything on your end.

Unico maintains a catalog of pre-established recipes, named and versioned (e.g. byunico-idlive-idunico-oneresponse-std). Some are exclusive to Brazil, such as those that include Score, Serpro, or age verification.

Which capabilities does your process run?

The combination of capabilities — your project's flow — is defined in your APIKey configuration. Check the pre-established recipes or talk to your Unico project contact to customize it.