Skip to main content
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​

EnvironmentURL
ProductionGET https://api.idcloud.unico.app/client/v1/process/{processId}
SandboxGET https://api.idcloud.uat.unico.app/client/v1/process/{processId}

Request​

Headers
HeaderValue
AuthorizationBearer <access_token>
Path parameters
ParameterTypeRequiredDescription
processIdstring (UUID)yesProcess identifier returned by Create Process.

Example​

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

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
FieldMeaning
idProcess UUID; the key used to query and track the flow.
flowType of journey executed (e.g. id_r2, idlivetrust_r2, idtrust_r2, ...).
callbackUriCallback URI the client app is redirected to at the end of the flow.
userRedirectUrlFull URL of the CbU page the user opens to run the journey (carries the id and behavior flags).
stateProcess lifecycle state. PROCESS_STATE_* values (e.g. CREATED, FAILED, FINISHED, AWAITING_FOR_DOCUMENT, UNSPECIFIED).
resultFinal verdict of the evaluation. PROCESS_RESULT_* values (e.g. APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Only conclusive when state = PROCESS_STATE_FINISHED.
createdAtProcess creation timestamp (UTC).
finishedAtProcess completion timestamp (UTC).
personSub-object with the data of the person being verified.
purposePurpose of the process (e.g. personAuthentication, person registration).
servicesList of additional services attached to the process; empty when none.
authenticationInfo.authenticationIdID of the identity authentication event generated by the flow.
capacitiesCapabilities/products used. PROCESS_CAPACITY_* values (e.g. IDCLOUDONE).
expiresAtProcess/link expiration timestamp (UTC).
tokenSession/access token associated with the process (may be empty).
companyDataSub-object with the data of the company/tenant that owns the process.
simulatedBoolean; whether this is a simulation/sandbox process (true) or a real one (false).
Person fields
FieldMeaning
duiTypeType of the unique identification document. DUI_TYPE_* values (e.g. BR_CPF).
duiValueDocument value (e.g. the CPF number).
friendlyNameFriendly name/nickname for the person (free text, not validated).
emailPerson's email; may be empty.
phonePhone number in E.164 format (country code + area code + number).
notificationsList of notification channels. Each item carries notificationChannel with NOTIFICATION_CHANNEL_* values (e.g. WHATSAPP, SMS, EMAIL).
phoneCountryCodeAlpha3ISO alpha-3 country code of the phone number (e.g. BRA); may be empty.
Company data fields
FieldMeaning
branchIdIdentifier of the tenant's branch; empty when not segmented by branch.
countryCodeCompany'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.

Countrydoc.codeDictionary typeDocument
BRRGunico.moja.dictionary.br.rg.v2.RgRG
BRCNHunico.moja.dictionary.br.cnh.v2.CnhCNH (driver's license)
BRCINunico.moja.dictionary.br.cin.v1.CinCIN
BRPASSAPORTEunico.moja.dictionary.br.passaporte.v1.PassaportePassport
MXINEunico.moja.dictionary.mx.ine.v1.IneINE voter credential
MXLPCunico.moja.dictionary.mx.lpc.v1.LpcLicencia para conducir (driver's license)
MXPASAPORTEunico.moja.dictionary.mx.pasaporte.v1.PasaportePassport
—UNKNOWNunico.moja.dictionary.other.unknown.v1.UnknownType 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.

BrazilClients in Brazil may receive the full process payload

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": "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
FieldTypeDescription
process.idstring (UUID)Process identifier.
process.flowstringFlow identifier sent on creation.
process.callbackUristringCallback URL configured for process events.
process.userRedirectUrlstringURL to redirect the user after the journey is completed.
process.stateenumCurrent process state. See values below.
process.resultenumVerification outcome. Present only when state = PROCESS_STATE_FINISHED.
process.createdAtstring (datetime)ISO 8601 timestamp when the process was created.
process.finishedAtstring (datetime)ISO 8601 timestamp when the process finished. Present only when state = PROCESS_STATE_FINISHED.
process.expiresAtstring (datetime)ISO 8601 timestamp when the process expires.
process.purposestringPurpose of the process as configured in the flow.
process.clientReferencestringOptional client-side reference for indexing in the portal.
process.useCasestringScenario identifier associated with the flow.
process.capacitiesarray of stringsList of capabilities activated in this process.
process.tokenstringSigned JWT for SDK integration.
process.personobjectIdentification provided on creation.
process.person.notificationsarrayNotification channels configured for the journey (e.g. email).
process.authenticationInfoobjectPer-capability results. See below.
process.companyDataobjectCompany and branch context.
process.companyData.branchIdstringBranch identifier.
process.companyData.countryCodestringISO 3166-1 alpha-2 country code.
process.bioTokenDataobjectReference process info — present only in 1:1 validation and Smart Revalidation flows.
process.servicesarraySigned envelopes, captured documents, and other service outputs. See below.
process.state values
ValueMeaning
PROCESS_STATE_CREATEDProcess created; user has not yet completed the journey.
AWAITING_FOR_DOCUMENTProcess 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_FINISHEDJourney completed. Check result and authenticationInfo.
PROCESS_STATE_FAILEDProcessing 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
ValueMeaning
PROCESS_RESULT_OKAll capabilities returned positive results.
PROCESS_RESULT_INVALID_IDENTITYAt least one capability returned a definitive negative (e.g. liveness failed, identity not matched).
PROCESS_RESULT_ERRORError during result processing.
PROCESS_RESULT_EXPIREDProcess expired before the journey was completed.
PROCESS_RESULT_UNSPECIFIEDProcess 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.

FieldCapabilityPossible values
authenticationId—Unique identifier for this authentication attempt.
livenessResultLivenessLIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED
authenticationResultIdentity VerificationAUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED
identityFraudstersResultFraud Risk ClassificationTRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED
bioTokenEngineResult1:1 ValidationBIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED
smartRevalidationResultSmart RevalidationSMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED
idAgeResultAge VerificationID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED
scoreEngineResult.scoreEnabledRisk ScoreSCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED
scoreEngineResult.scoreRisk ScoreNumber from -100 to +100. Present when authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE and Risk Score is enabled.
serproResult.scoreSerpro Similarity0–100 (similarity); -1 (no face on file for this CPF); -2 (integration error).
process.services fields
Mixed naming conventions in services

The services array uses camelCase for envelope-level fields (envelopeId, documentIds) and snake_case for document-level fields (doc_id, consent_granted, face_match, etc.). This reflects the actual API response — both conventions are intentional and not a documentation error.

FieldTypeDescription
envelopeIdstring (UUID)Signed envelope identifier.
documentIdsarray of stringsIDs of captured documents in this service.
consent_grantedbooleanWhether the user granted data sharing consent.
documentsarrayCaptured documents with OCR data and validation results.
documents[].doc_idstringDocument identifier.
documents[].typifiedbooleanWhether the document type was successfully identified.
documents[].cpf_matchbooleanWhether the CPF on the document matches the provided CPF (Brazil only).
documents[].face_matchbooleanWhether the selfie matches the photo on the document.
documents[].validate_docbooleanWhether the document passed authenticity validation.
documents[].reused_docbooleanWhether this document was reused from a previous process.
documents[].signed_urlstringPre-signed URL to download the document PDF (valid for 5 minutes — re-fetch to renew).
documents[].doc.versionintegerOCR schema version.
documents[].doc.codestringShort document type code (e.g. CNH). See Document types and OCR fields for every value and how the code is derived.
documents[].doc.dataobjectExtracted OCR fields. Content varies by document type — see the full field reference for the complete catalog. Field names within doc.data (e.g. nomeCivil, dataNascimento) are returned in Portuguese — these are the actual values produced by the OCR engine.

Error Codes​

CodeMessageDescription
3process id is invalidWhen the process ID is invalid.

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​

Last updated on