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.

Markdown
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 (e.g. PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_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

process.services[].documents[].doc.code reports the document type in one of two forms. Documents processed by Unico's document module, including reused documents, carry a short uppercase code (CNH). Processes created through the API only usually carry the full dictionary type (unico.moja.dictionary.br.cnh.v2.Cnh), but can also carry a short code. Handle both forms on every integration path. The short code carries neither the country nor the schema version; the version is returned separately in doc.version.

In the short form, document types that use the unified schema — unified_schema in the field reference — are reported as the uppercased type identified during capture. The most common values are IDCARD, DRIVERLICENSE, PASSPORT and VOTERID, but the list is open: other types identified during capture are returned as they are, uppercased. Handle values outside this list. U.S. passports keep their variant instead of collapsing into PASSPORT: POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT and REFUGEEPASSPORT 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.

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, or a Brazilian or Mexican type without its own schema — doc.data is empty

Brazilian and Mexican documents use only the specific schemas above. A Brazilian or Mexican document of any other type — for example, a Mexican resident card — is reported as UNKNOWN, not with the unified schema.

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": "iddocs_r2",
"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": "USE_CASE_LOGIN",
"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_UNSPECIFIED",
"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": "BRA"
},
"bioTokenData": {
"referenceProcessId": "ref-proc-123",
"authenticationId": "auth-ref-123"
},
"services": [
{
"consent_granted": true,
"documents": [
{
"doc_id": "doc-abc-123",
"share_id": "share-abc-123",
"typified": true,
"cpf_match": true,
"validate_doc": true,
"face_match": true,
"verified": true,
"reused_doc": false,
"signed_url": "https://example.com/doc?token=xyz",
"doc": {
"version": 2,
"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-3 country code (e.g. BRA).
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.
PROCESS_STATE_AWAITING_FOR_DOCUMENTProcess created without an identification document. Only present when the Custom Flow allows optional document. Send the document with Set Process Document.
PROCESS_STATE_FINISHEDJourney completed. Check result and authenticationInfo.
PROCESS_STATE_FAILEDProcessing error.
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).
deviceMetadataDevice MetadataObject with status (found, not_found, unavailable) and the device data. Absent when the capability is not enabled in the flow.
process.services fields
One item per module

services holds one item per module that finished in the process: the latest finished run of each module, and only while the process is PROCESS_STATE_FINISHED or PROCESS_STATE_AWAITING_FOR_DOCUMENT. Processes created through the API only carry their document item in any state. A document capture item carries documents and consent_granted. An electronic signature item carries envelope_id and document_ids. Items have no type field and their order is not stable: match each one by its keys, not by its position, and ignore items you do not recognize. Keys are snake_case, except those inside doc.data, which follow the document's schema (e.g. nomeCivil).

FieldTypeDescription
consent_grantedbooleanDocument capture item. Whether the user granted consent to share the documents with your company.
documentsarrayDocument capture item. Captured documents with OCR data and validation results.
documents[].doc_idstringDocument identifier.
documents[].​share_idstringIdentifier of the share the user granted to your company for this process.
documents[].​typifiedbooleanWhether the document type was identified.
documents[].​cpf_matchbooleanBrazil only. Whether the CPF on the document matches the CPF sent on creation. Always present for companies whose country is set to Brazil; omitted for other countries and for companies with no country set.
documents[].​validate_docbooleanBrazil only. Whether the document passed Unico's document validation. Always present for companies whose country is set to Brazil (false when the validation did not run); omitted for other countries and for companies with no country set.
documents[].​face_matchboolean or nullWhether the selfie matches the photo on the document. null means the check did not run — it is not a negative result.
documents[].​verifiedboolean or nulltrue only when the document type is known, the document was not deleted, face_match is true and the document passed the quality checks. false otherwise, including when face_match did not run. null when the process did not go through the document module.
documents[].​reused_docbooleanWhether this document was reused from a previous process.
documents[].​signed_urlstringShort-lived signed URL to download the document image. It expires: don't store it or rely on a fixed lifetime, and call this endpoint again to get a new one.
documents[].​doc.​versionintegerVersion of the document type's dictionary (e.g. 2 for unico.moja.dictionary.br.cnh.v2.Cnh).
documents[].​doc.​codestringDocument type, as a short code (e.g. CNH) or as the full dictionary type (e.g. unico.moja.dictionary.br.cnh.v2.Cnh). Documents processed by the document module carry the short code. Handle both. 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 follow the document's schema: Portuguese for Brazilian documents (e.g. nomeCivil, dataNascimento), Spanish for Mexican documents and English for the unified schema.
envelope_idstring (UUID)Electronic signature item. Signed envelope identifier.
document_idsarray of stringsElectronic signature item. IDs of the documents in the envelope.
Processes created through the API only

In a process created through the API only, the document item comes from the API call, not from Unico's document module, and some values differ from the table above:

  • consent_granted is always false: your company collects the consent, and Unico does not track it.
  • share_id and signed_url are empty.
  • face_match is always true or false, never null.
  • verified is always null.
  • doc.version is 0.
  • doc.code usually carries the full dictionary type (e.g. unico.moja.dictionary.br.cnh.v2.Cnh), but can carry a short code.
  • doc.data is null when the OCR data could not be read.

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​