Recupere um processo existente pelo seu identificador. Conforme o contrato da API, o resultado já é retornado de forma síncrona na criação do processo — use este endpoint para reconsultas, auditoria e suporte.
Antes de recuperar o processo, revise nossa configuração de webhook e as estratégias de fallback — clique aqui.
Endpoint
| Ambiente | URL |
|---|---|
| Produção | GET https://api.idcloud.unico.app/client/v1/process/{processId} |
| Sandbox | GET https://api.idcloud.uat.unico.app/client/v1/process/{processId} |
Requisição
| Header | Valor |
|---|---|
Authorization | Bearer <access_token> |
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
processId | string (UUID) | sim | Identificador do processo retornado por Criar Processo. |
Exemplo
- 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();
Respostas
{
"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
}
}
| Campo | Significado |
|---|---|
id | UUID do processo; a chave usada para consultar e acompanhar o fluxo. |
flow | Tipo de jornada executada (ex.: id_r2, idlivetrust_r2, idtrust_r2, ...). |
callbackUri | URI de callback para a qual a aplicação cliente é redirecionada ao final do fluxo. |
userRedirectUrl | URL completa da página de CbU que o usuário abre para executar a jornada (carrega o id e flags de comportamento). |
state | Estado do ciclo de vida do processo (ex.: PROCESS_STATE_CREATED, PROCESS_STATE_FAILED, PROCESS_STATE_FINISHED, PROCESS_STATE_AWAITING_FOR_DOCUMENT, PROCESS_STATE_UNSPECIFIED). |
result | Veredito final da avaliação. Valores PROCESS_RESULT_* (ex.: APPROVED, AUTHENTICATED, NOT_APPROVED, ...). Só é conclusivo quando state = PROCESS_STATE_FINISHED. |
createdAt | Timestamp (UTC) de criação do processo. |
finishedAt | Timestamp (UTC) de conclusão do processo. |
person | Subobjeto com os dados da pessoa sendo verificada. |
purpose | Finalidade do processo (ex.: personAuthentication, cadastro de pessoa). |
services | Lista de serviços adicionais vinculados ao processo; vazia quando não há nenhum. |
authenticationInfo.authenticationId | ID do evento de autenticação de identidade gerado pelo fluxo. |
capacities | Capacidades/produtos utilizados. Valores PROCESS_CAPACITY_* (ex.: IDCLOUDONE). |
expiresAt | Timestamp (UTC) de expiração do processo/link. |
token | Token de sessão/acesso associado ao processo (pode estar vazio). |
companyData | Subobjeto com os dados da empresa/tenant proprietário do processo. |
simulated | Booleano; indica se este é um processo de simulação/sandbox (true) ou real (false). |
| Campo | Significado |
|---|---|
duiType | Tipo do documento de identificação único. Valores DUI_TYPE_* (ex.: BR_CPF). |
duiValue | Valor do documento (ex.: o número do CPF). |
friendlyName | Nome amigável/apelido da pessoa (texto livre, não validado). |
email | E-mail da pessoa; pode estar vazio. |
phone | Número de telefone no formato E.164 (código do país + DDD + número). |
notifications | Lista de canais de notificação. Cada item carrega notificationChannel com valores NOTIFICATION_CHANNEL_* (ex.: WHATSAPP, SMS, EMAIL). |
phoneCountryCodeAlpha3 | Código de país ISO alpha-3 do número de telefone (ex.: BRA); pode estar vazio. |
| Campo | Significado |
|---|---|
branchId | Identificador da filial do tenant; vazio quando não há segmentação por filial. |
countryCode | País da empresa em ISO alpha-3 (ex.: BRA). |
process.services[].documents[].doc.code reporta o tipo de documento em uma de duas formas. Documentos processados pelo módulo de documentos da Unico, inclusive documentos reutilizados, carregam um código curto em maiúsculas (CNH). Processos criados somente pela API costumam carregar o tipo completo do dicionário (unico.moja.dictionary.br.cnh.v2.Cnh), mas também podem carregar um código curto. Trate as duas formas em qualquer caminho de integração.
O código curto não carrega o país nem a versão do schema; a versão é retornada separadamente em doc.version.
Na forma curta, tipos de documento que usam o schema unificado — unified_schema na referência de campos — são reportados como o identificador de tipo em maiúsculas identificado durante a captura. Os valores mais comuns são IDCARD, DRIVERLICENSE, PASSPORT e VOTERID, mas a lista é aberta: outros tipos identificados durante a captura são retornados como estão, em maiúsculas. Trate valores fora desta lista.
Passaportes dos EUA mantêm sua variante em vez de colapsar para PASSPORT: POLYCARBONATEPASSPORT, PASSPORTCARD, PAPERPASSPORT, CONSULARPASSPORT, ALIENPASSPORT e REFUGEEPASSPORT também são retornados.
Por exemplo, unico.moja.dictionary.ar.generic.v1.IdCard e unico.moja.dictionary.us.generic.v1.PolycarbonatePassport são reportados como IDCARD e POLYCARBONATEPASSPORT.
Tipos de documento que usam seu próprio schema de campos — listados em specific_document_schemas na referência de campos — são mostrados na tabela abaixo. Use o tipo do dicionário para consultar cada schema nesse arquivo.
| País | doc.code | Tipo do dicionário | Documento |
|---|---|---|---|
| BR | RG | unico.moja.dictionary.br.rg.v2.Rg | RG |
| BR | CNH | unico.moja.dictionary.br.cnh.v2.Cnh | CNH (carteira de motorista) |
| BR | CIN | unico.moja.dictionary.br.cin.v1.Cin | CIN |
| BR | PASSAPORTE | unico.moja.dictionary.br.passaporte.v1.Passaporte | Passaporte |
| MX | INE | unico.moja.dictionary.mx.ine.v1.Ine | Credencial de eleitor INE |
| MX | LPC | unico.moja.dictionary.mx.lpc.v1.Lpc | Licencia para conducir (carteira de motorista) |
| MX | PASAPORTE | unico.moja.dictionary.mx.pasaporte.v1.Pasaporte | Passaporte |
| — | UNKNOWN | unico.moja.dictionary.other.unknown.v1.Unknown | Tipo não pôde ser identificado, ou é um tipo brasileiro ou mexicano sem schema próprio — doc.data está vazio |
Documentos brasileiros e mexicanos usam apenas os schemas específicos acima. Um documento brasileiro ou mexicano de qualquer outro tipo — por exemplo, uma carteira de residente mexicana — é reportado como UNKNOWN, e não com o schema unificado.
PASSAPORTE e PASAPORTE são documentos diferentesO passaporte brasileiro é PASSAPORTE (com S duplo) e o mexicano é PASAPORTE (com S simples), cada um espelhando a grafia do seu próprio dicionário. Isso não é um erro de digitação — não trate os dois valores como equivalentes.
Nenhuma extração de OCR é realizada e nenhum campo é reportado em doc.data quando doc.code é UNKNOWN.
Clientes no Brasil podem receber o payload completo do processoA estrutura geral da resposta permanece a mesma — o resultado único é o padrão.

A estrutura geral da resposta permanece a mesma — o resultado único é o padrão.
Integrações no Brasil podem receber o objeto completo do processo abaixo, com resultados por capacidade em 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"
}
}
}
]
}
]
}
}
| Campo | Tipo | Descrição |
|---|---|---|
process.id | string (UUID) | Identificador do processo. |
process.flow | string | Identificador do fluxo enviado na criação. |
process.callbackUri | string | URL de callback configurada para eventos do processo. |
process.userRedirectUrl | string | URL para redirecionar o usuário após a conclusão da jornada. |
process.state | enum | Estado atual do processo. Veja os valores abaixo. |
process.result | enum | Resultado da verificação. Presente apenas quando state = PROCESS_STATE_FINISHED. |
process.createdAt | string (datetime) | Timestamp ISO 8601 de criação do processo. |
process.finishedAt | string (datetime) | Timestamp ISO 8601 de conclusão do processo. Presente apenas quando state = PROCESS_STATE_FINISHED. |
process.expiresAt | string (datetime) | Timestamp ISO 8601 de expiração do processo. |
process.purpose | string | Finalidade do processo conforme configurada no fluxo. |
process.clientReference | string | Referência opcional do lado do cliente para indexação no portal. |
process.useCase | string | Identificador do cenário associado ao fluxo. |
process.capacities | array de strings | Lista de capacidades ativadas neste processo. |
process.token | string | JWT assinado para integração via SDK. |
process.person | object | Identificação fornecida na criação. |
process.person.notifications | array | Canais de notificação configurados para a jornada (ex.: email). |
process.authenticationInfo | object | Resultados por capacidade. Veja abaixo. |
process.companyData | object | Contexto de empresa e filial. |
process.companyData.branchId | string | Identificador da filial. |
process.companyData.countryCode | string | Código de país ISO 3166-1 alpha-3 (ex.: BRA). |
process.bioTokenData | object | Informações do processo de referência — presente apenas em fluxos de 1:1 Validation e Smart Revalidation. |
process.services | array | Envelopes assinados, documentos capturados e outras saídas de serviço. Veja abaixo. |
| Valor | Significado |
|---|---|
PROCESS_STATE_CREATED | Processo criado; o usuário ainda não concluiu a jornada. |
PROCESS_STATE_AWAITING_FOR_DOCUMENT | Processo criado sem documento de identificação. Presente apenas quando o Custom Flow permite documento opcional. Envie o documento com Definir Documento do Processo. |
PROCESS_STATE_FINISHED | Jornada concluída. Verifique result e authenticationInfo. |
PROCESS_STATE_FAILED | Erro de processamento. |
| Valor | Significado |
|---|---|
PROCESS_RESULT_OK | Todas as capacidades retornaram resultados positivos. |
PROCESS_RESULT_INVALID_IDENTITY | Pelo menos uma capacidade retornou um negativo definitivo (ex.: liveness falhou, identidade não correspondida). |
PROCESS_RESULT_ERROR | Erro durante o processamento do resultado. |
PROCESS_RESULT_EXPIRED | Processo expirou antes da conclusão da jornada. |
PROCESS_RESULT_UNSPECIFIED | Processo ainda não finalizado. |
Todos os campos são sempre retornados independentemente do fluxo. Campos de capacidades não usadas no fluxo retornam *_UNSPECIFIED.
Valores abreviados (ex.: livenessResult = LIVE, authenticationResult = INCONCLUSIVE) mapeiam diretamente para os valores de enum completos documentados aqui (LIVENESS_RESULT_LIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, etc.) — o prefixo é omitido por brevidade.
| Campo | Capacidade | Valores possíveis |
|---|---|---|
authenticationId | — | Identificador único desta tentativa de autenticação. |
livenessResult | Prova de Vida | LIVENESS_RESULT_LIVE, LIVENESS_RESULT_NOT_LIVE, LIVENESS_RESULT_UNSPECIFIED |
authenticationResult | Verificação de Identidade | AUTHENTICATION_RESULT_POSITIVE, AUTHENTICATION_RESULT_NEGATIVE, AUTHENTICATION_RESULT_INCONCLUSIVE, AUTHENTICATION_RESULT_UNSPECIFIED |
identityFraudstersResult | Classificação de Risco de Fraude | TRUST_RESULT_YES, TRUST_RESULT_INCONCLUSIVE, TRUST_RESULT_UNSPECIFIED |
bioTokenEngineResult | Validação 1:1 | BIO_TOKEN_ENGINE_RESULT_POSITIVE, BIO_TOKEN_ENGINE_RESULT_NEGATIVE, BIO_TOKEN_ENGINE_RESULT_UNSPECIFIED |
smartRevalidationResult | Revalidação Inteligente | SMART_REVALIDATION_RESULT_POSITIVE, SMART_REVALIDATION_RESULT_NEGATIVE, SMART_REVALIDATION_RESULT_UNSPECIFIED |
idAgeResult | Verificação de Idade | ID_AGE_RESULT_POSITIVE, ID_AGE_RESULT_NEGATIVE, ID_AGE_RESULT_INCONCLUSIVE, ID_AGE_RESULT_UNSPECIFIED |
scoreEngineResult.scoreEnabled | Score de Risco | SCORE_ENABLED_TRUE, SCORE_ENABLED_FALSE, SCORE_ENABLED_UNSPECIFIED |
scoreEngineResult.score | Score de Risco | Número de -100 a +100. Presente quando authenticationResult = AUTHENTICATION_RESULT_INCONCLUSIVE e o Score de Risco está habilitado. |
serproResult.score | Semelhança do Serpro | 0–100 (semelhança); -1 (nenhuma face registrada para este CPF); -2 (erro de integração). |
deviceMetadata | Metadados do Dispositivo | Objeto com status (found, not_found, unavailable) e os dados do dispositivo. Ausente quando a capacidade não está habilitada no fluxo. |
services contém um item por módulo concluído no processo: a execução concluída mais recente de cada módulo, e só enquanto o processo está PROCESS_STATE_FINISHED ou PROCESS_STATE_AWAITING_FOR_DOCUMENT. Processos criados somente pela API trazem o item de documento em qualquer estado. Um item de captura de documentos traz documents e consent_granted. Um item de assinatura eletrônica traz envelope_id e document_ids. Os itens não têm campo de tipo e a ordem deles não é estável: identifique cada um pelas suas chaves, não pela posição, e ignore os itens que você não reconhecer. As chaves são snake_case, exceto as de doc.data, que seguem o schema do documento (ex.: nomeCivil).
| Campo | Tipo | Descrição |
|---|---|---|
consent_granted | boolean | Item de captura de documentos. Se o usuário concedeu consentimento para compartilhar os documentos com a sua empresa. |
documents | array | Item de captura de documentos. Documentos capturados com dados de OCR e resultados de validação. |
documents[].doc_id | string | Identificador do documento. |
documents[].share_id | string | Identificador do compartilhamento que o usuário concedeu à sua empresa para este processo. |
documents[].typified | boolean | Se o tipo de documento foi identificado. |
documents[].cpf_match | boolean | Somente Brasil. Se o CPF no documento corresponde ao CPF enviado na criação. Sempre presente para empresas com país definido como Brasil; omitido para outros países e para empresas sem país definido. |
documents[].validate_doc | boolean | Somente Brasil. Se o documento passou na validação de documentos da Unico. Sempre presente para empresas com país definido como Brasil (false quando a validação não foi executada); omitido para outros países e para empresas sem país definido. |
documents[].face_match | boolean ou null | Se a selfie corresponde à foto do documento. null significa que a verificação não foi executada — não é um resultado negativo. |
documents[].verified | boolean ou null | true somente quando o tipo de documento é conhecido, o documento não foi excluído, face_match é true e o documento passou nas verificações de qualidade. false caso contrário, inclusive quando face_match não foi executado. null quando o processo não passou pelo módulo de documentos. |
documents[].reused_doc | boolean | Se este documento foi reutilizado de um processo anterior. |
documents[].signed_url | string | URL assinada de curta duração para download da imagem do documento. Ela expira: não a armazene nem conte com um tempo de validade fixo, e chame este endpoint novamente para obter uma nova. |
documents[].doc.version | integer | Versão do dicionário do tipo de documento (ex.: 2 para unico.moja.dictionary.br.cnh.v2.Cnh). |
documents[].doc.code | string | Tipo de documento, como código curto (ex.: CNH) ou como tipo completo do dicionário (ex.: unico.moja.dictionary.br.cnh.v2.Cnh). Documentos processados pelo módulo de documentos carregam o código curto. Trate ambos. Veja Tipos de documento e campos de OCR para todos os valores e como o código é derivado. |
documents[].doc.data | object | Campos de OCR extraídos. O conteúdo varia por tipo de documento — veja a referência completa de campos para o catálogo completo. Os nomes dos campos seguem o schema do documento: português para documentos brasileiros (ex.: nomeCivil, dataNascimento), espanhol para documentos mexicanos e inglês para o schema unificado. |
envelope_id | string (UUID) | Item de assinatura eletrônica. Identificador do envelope assinado. |
document_ids | array de strings | Item de assinatura eletrônica. IDs dos documentos no envelope. |
Em um processo criado somente pela API, o item de documento vem da chamada à API, e não do módulo de documentos da Unico, e alguns valores diferem da tabela acima:
consent_grantedé semprefalse: a sua empresa coleta o consentimento, e a Unico não o acompanha.share_idesigned_urlvêm vazios.face_matché sempretrueoufalse, nuncanull.verifiedé semprenull.doc.versioné0.doc.codecostuma carregar o tipo completo do dicionário (ex.:unico.moja.dictionary.br.cnh.v2.Cnh), mas pode carregar um código curto.doc.datavemnullquando os dados de OCR não puderam ser lidos.
Códigos de Erro
- 400 Bad Request
- 401 Unauthorized
- 404 Not Found
- 429 Too Many Requests
- 500 Internal Server Error
| Código | Mensagem | Descrição |
|---|---|---|
3 | process id is invalid | Quando o ID do processo é inválido. |
| Código | Mensagem | Descrição |
|---|---|---|
| — | Jwt header is an invalid JSON | Quando o access token utilizado contém caracteres incorretos. |
| — | Jwt is expired | Quando o access token utilizado expirou. |
| Código | Mensagem | Descrição |
|---|---|---|
5 | error getting process: rpc error: code = NotFound desc = process not found | Quando o ID do processo não foi encontrado. |
Limite de taxa atingido. Quando seu sistema recebe um erro HTTP 429, você deve implementar mecanismos para prevenir falhas em cascata e evitar o agravamento da restrição.
Boas práticas:
- Período de resfriamento (backoff): Interrompa ou reduza imediatamente as requisições subsequentes do seu sistema. Não reenvie continuamente requisições com falha em um loop curto.
- Filas e limitação (Queueing & throttling): Armazene em buffer ou enfileire as requisições de saída do seu lado para controlar o fluxo de tráfego antes de reenviá-las.
- Backoff exponencial com jitter: Ao retentar, aumente o tempo de espera exponencialmente entre as tentativas (por exemplo, 1 s, 2 s, 4 s, 8 s) e adicione um pequeno atraso aleatório ("jitter") para evitar um efeito de manada onde todas as requisições enfileiradas retentam exatamente no mesmo milissegundo.
Enviar requisições continuamente a um endpoint com limite de taxa sem aplicar backoff pode prolongar o período de restrição e impactar severamente a capacidade operacional do seu sistema. Limitar adequadamente as requisições do seu lado garante uma integração mais suave e resiliente.
Para limites padrão, aumento de requisições e detalhes adicionais, consulte Limites de taxa.
| Código | Mensagem | Descrição |
|---|---|---|
99999 | Internal failure! Try again later | Quando ocorre um erro interno. |
Polling vs. webhook
Você pode fazer polling deste endpoint para verificar o progresso, mas o padrão recomendado é assinar um webhook e chamar este endpoint apenas como fallback. Veja Webhooks e Eventos.
Próximos passos
- Para a selfie capturada, veja Obter Selfie.
- Para o pacote de auditoria de evidências, veja Obter Conjunto de Evidências.