Get Process

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

200 OK

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idunicosign",
    "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
      },
      "serproResult": {
        "score": 92
      }
    },
    "companyData": {
      "branchId": "branch-123",
      "countryCode": "BR"
    },
    "bioTokenData": {
      "referenceProcessId": "ref-proc-123",
      "authenticationId": "auth-ref-123"
    },
    "services": [
      {
        "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
        "documentIds": ["doc-abc-123"],
        "consent_granted": true,
        "documents": [
          {
            "doc_id": "doc-abc-123",
            "typified": true,
            "cpf_match": true,
            "face_match": true,
            "validate_doc": true,
            "reused_doc": false,
            "signed_url": "https://example.com/doc?token=xyz",
            "doc": {
              "version": 1,
              "code": "CNH",
              "data": {
                "numero": "044589731564",
                "cpfNumero": "12345678909",
                "nomeCivil": "Luke Skywalker",
                "dataNascimento": "1990-05-12T00:00:00Z",
                "dataExpiracao": "2027-12-07T00:00:00Z",
                "categoria": "B"
              }
            }
          }
        ]
      }
    ]
  }
}

Top-level fields

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	Use case 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-2 country code.
`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.

process.state values

Value	Meaning
`PROCESS_STATE_CREATED`	Process created; user has not yet completed the journey.
`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.

State naming inconsistency

AWAITING_FOR_DOCUMENT does not follow the PROCESS_STATE_* prefix convention used by the other states. This is a known naming inconsistency in the current API.

process.result values

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.

Capability results in authenticationInfo

All fields are always returned regardless of the flow. Fields for capabilities not used in the flow return *_UNSPECIFIED.

Abbreviated enum values

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`	Risk Fraud 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).

process.services fields

Field	Type	Description
`envelopeId`	string (UUID)	Signed envelope identifier.
`documentIds`	array of strings	IDs of captured documents in this service.
`consent_granted`	boolean	Whether the user granted data sharing consent.
`documents`	array	Captured documents with OCR data and validation results.
`documents[].doc_id`	string	Document identifier.
`documents[].typified`	boolean	Whether the document type was successfully identified.
`documents[].cpf_match`	boolean	Whether the CPF on the document matches the provided CPF.
`documents[].face_match`	boolean	Whether the selfie matches the photo on the document.
`documents[].validate_doc`	boolean	Whether the document passed authenticity validation.
`documents[].reused_doc`	boolean	Whether this document was reused from a previous process.
`documents[].signed_url`	string	Pre-signed URL to download the document PDF (valid for 5 minutes — re-fetch to renew).
`documents[].doc.version`	integer	OCR schema version.
`documents[].doc.code`	string	Document type code (e.g. `CNH`, `RG`).
`documents[].doc.data`	object	Extracted OCR fields. Content varies by document type and available data.

400 Bad Request

The processId path parameter is missing or malformed.

401 Unauthorized

Bearer token missing, expired, or invalid.

404 Not Found

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

429 Too Many Requests

Rate limit reached.

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.

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.

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.

Endpoint​

Request​

Example​

Responses​

Error Codes​

Polling vs webhook​

What's next​