> ## Documentation Index
> Fetch the complete documentation index at: https://docs.id.zapsign.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar validação

> Busca uma validação pelo identificador.

## Acompanhar uma validação hospedada

Nas validações síncronas o resultado já vem na resposta da criação. Na [prova de vida + documento](/validacoes/selfie-documento), que nasce em `pending`, consulte até o `status` mudar; `expires_at` limita a janela de espera.


## OpenAPI

````yaml GET /validations/{id}
openapi: 3.1.0
info:
  title: ID ZapSign
  version: 1.0.0
  description: >-
    API de validações de identidade da ID ZapSign. Crie validações, consulte o
    resultado e gerencie suas chaves de API.
  contact:
    name: Suporte ID ZapSign
    url: https://id.zapsign.com.br
    email: support@zapsign.com.br
servers:
  - url: https://api.id.zapsign.com.br/v1
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: Validações
    description: Criação e consulta de validações.
  - name: Chaves de API
    description: Criação, listagem e revogação de chaves de API.
paths:
  /validations/{id}:
    get:
      tags:
        - Validações
      summary: Consulta uma validação pelo identificador.
      description: >-
        Use nas validações hospedadas para saber quando o titular terminou o
        fluxo e qual foi o resultado.
      operationId: getValidation
      parameters:
        - name: id
          in: path
          required: true
          description: Identificador da validação.
          schema:
            type: string
          example: val_06YGSA9CF0V6RVXT326BS4K1ZA
      responses:
        '200':
          description: Validação encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Validation'
              examples:
                concluida_com_detalhes:
                  summary: Prova de vida concluída, com dados do documento
                  value:
                    object: validation
                    id: val_06YGSA9CF0V6RVXT326BS4K1ZA
                    type: liveness_document_match
                    status: completed
                    result: passed
                    reason_code: null
                    external_id: pedido_12345
                    created_at: '2026-08-07T14:20:00Z'
                    resolved_at: '2026-08-07T14:26:35Z'
                    validation_url: >-
                      https://id.zapsign.com.br/validate/val_06YGSA9CF0V6RVXT326BS4K1ZA
                    expires_at: '2026-08-08T14:20:00Z'
                    details:
                      liveness_document_match:
                        full_name: Maria Aparecida da Silva
                        sex: F
                        cpf: '12345678909'
                        date_of_birth: '1985-03-12'
                        document_type: id_card
                        document_number: '123456789'
                        document_country: BR
                        document_version: null
                        document_issued_at: '2018-06-01'
                        document_expires_at: null
                ainda_pendente:
                  summary: O titular ainda não terminou
                  value:
                    object: validation
                    id: val_06YGSA9CF0V6RVXT326BS4K1ZA
                    type: liveness_document_match
                    status: pending
                    result: null
                    reason_code: null
                    external_id: pedido_12345
                    created_at: '2026-08-07T14:20:00Z'
                    resolved_at: null
                    validation_url: >-
                      https://id.zapsign.com.br/validate/val_06YGSA9CF0V6RVXT326BS4K1ZA
                    expires_at: '2026-08-08T14:20:00Z'
                    details: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    Validation:
      type: object
      description: Resultado de uma validação.
      required:
        - object
        - id
        - type
        - status
        - result
        - reason_code
        - external_id
        - created_at
        - resolved_at
        - validation_url
        - expires_at
        - details
      properties:
        object:
          type: string
          enum:
            - validation
          description: Sempre `validation`.
        id:
          type: string
          description: Identificador único da validação.
          example: val_0NQW3MVYJYQ453E95V3V1T76AV
        type:
          type: string
          enum:
            - liveness_document_match
            - liveness_cpf_match
            - cpf_phone_match
            - sim_swap
            - telco_financial_capacity
          description: >-
            Tipo da validação.


            | Valor | O que é |

            | --- | --- |

            | `cpf_phone_match` | Vínculo entre CPF e telefone |

            | `sim_swap` | Troca de chip |

            | `liveness_document_match` | Prova de vida + documento |

            | `liveness_cpf_match` | Prova de vida + CPF |

            | `telco_financial_capacity` | Capacidade financeira via operadora |


            Os três primeiros têm endpoint de criação. Os outros dois podem
            aparecer em consultas e listagens de contas que os usam por outros
            canais.
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
            - expired
          description: >-
            Estado atual.


            | Valor | O que é |

            | --- | --- |

            | `pending` | Criada, aguardando o titular concluir o fluxo
            hospedado |

            | `completed` | Resolvida; veja `result` |

            | `failed` | Não foi possível concluir |

            | `expired` | A sessão hospedada venceu sem conclusão |
        result:
          description: >-
            Resultado de negócio. É `null` enquanto `status` for `pending`.


            | Valor | Aparece em |

            | --- | --- |

            | `match` / `no_match` | `cpf_phone_match` |

            | `recent_swap` / `no_recent_swap` | `sim_swap` |

            | `passed` / `not_passed` | `liveness_document_match`,
            `liveness_cpf_match` |

            | `high_capacity` / `moderate_capacity` / `low_capacity` |
            `telco_financial_capacity` |

            | `unknown` | Qualquer tipo, quando a fonte não deu uma resposta
            conclusiva. O motivo vem em `reason_code`. |
          anyOf:
            - type: string
              enum:
                - passed
                - not_passed
                - match
                - no_match
                - recent_swap
                - no_recent_swap
                - high_capacity
                - moderate_capacity
                - low_capacity
                - unknown
            - type: 'null'
        reason_code:
          description: >-
            Por que o resultado foi `unknown`. É `null` em qualquer outro caso.


            | Valor | O que é |

            | --- | --- |

            | `liveness_failed` | Prova de vida não confirmada |

            | `face_mismatch` | O rosto não corresponde ao documento |

            | `spoof_detected` | Suspeita de fraude na captura |

            | `document_tampered` | Indícios de adulteração no documento |

            | `document_invalid` | Documento inválido ou não aceito |

            | `document_unreadable` | O documento não pôde ser lido |

            | `cpf_reference_not_found` | CPF não encontrado na base de
            referência |

            | `data_unavailable` | Dados indisponíveis na fonte consultada |

            | `phone_not_covered` | Telefone sem cobertura para a consulta |
          anyOf:
            - type: string
              enum:
                - liveness_failed
                - face_mismatch
                - spoof_detected
                - document_tampered
                - document_invalid
                - document_unreadable
                - cpf_reference_not_found
                - data_unavailable
                - phone_not_covered
            - type: 'null'
        external_id:
          type:
            - string
            - 'null'
          description: A referência de correlação que você enviou na criação.
        created_at:
          type: string
          format: date-time
          description: Data de criação em ISO-8601.
        resolved_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Data de resolução em ISO-8601. É `null` enquanto não resolvida.
        validation_url:
          type:
            - string
            - 'null'
          description: >-
            URL para onde redirecionar o titular. Preenchida nas validações
            hospedadas; `null` nas síncronas.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Quando a sessão hospedada vence, em ISO-8601. Preenchida nas
            validações hospedadas; `null` nas síncronas.
        details:
          description: >-
            Dados extraídos, agrupados pela chave do `type`. Hoje só
            `liveness_document_match` produz detalhes, e só com `status` igual a
            `completed`. Nos demais casos é `null`.
          anyOf:
            - $ref: '#/components/schemas/ValidationDetails'
            - type: 'null'
    ValidationDetails:
      type: object
      description: >-
        Detalhes por tipo. Contém no máximo uma propriedade, cuja chave é o
        `type` do recurso.
      additionalProperties: false
      properties:
        liveness_document_match:
          $ref: '#/components/schemas/LivenessDocumentMatchDetails'
    ErrorEnvelope:
      type: object
      description: >-
        Formato único de erro. Toda falha da API responde neste formato. A lista
        completa de `code` está em [Erros](/erros).
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
            - doc_url
            - request_id
          properties:
            type:
              type: string
              enum:
                - invalid_request
                - authentication_error
                - not_found
                - api_error
                - idempotency_error
                - payment_error
                - rate_limit_error
              description: >-
                Categoria do erro. Serve para tratar famílias inteiras sem
                enumerar cada `code`.
            code:
              type: string
              description: >-
                Código estável do erro. É o que você deve usar para ramificar no
                seu código.
              example: missing_required_param
            message:
              type: string
              description: >-
                Descrição legível, em inglês. É para diagnóstico, não para
                mostrar ao usuário final.
            param:
              type: string
              description: O campo que causou o erro, quando aplicável.
              example: cpf
            doc_url:
              type: string
              description: Link direto para este código nesta documentação.
              example: https://docs.id.zapsign.com.br/missing_required_param
            request_id:
              type: string
              description: Identificador da requisição. Inclua no contato com o suporte.
              example: req_3PK3TA2H0MEMTDSAPREHSY4QC4
    LivenessDocumentMatchDetails:
      type: object
      description: >-
        Dados lidos do documento e da pessoa. Os dez campos vêm sempre, e cada
        um é `null` quando o provedor não conseguiu extraí-lo.
      additionalProperties: false
      required:
        - full_name
        - sex
        - cpf
        - date_of_birth
        - document_type
        - document_number
        - document_country
        - document_version
        - document_issued_at
        - document_expires_at
      properties:
        full_name:
          type:
            - string
            - 'null'
          description: Nome completo como consta no documento.
        sex:
          description: >-
            Sexo como consta no documento. Valores fora de `M` e `F` viram
            `null`.
          anyOf:
            - type: string
              enum:
                - M
                - F
            - type: 'null'
        cpf:
          type:
            - string
            - 'null'
          pattern: ^\d{11}$
          description: CPF lido do documento, só dígitos.
        date_of_birth:
          type:
            - string
            - 'null'
          format: date
          description: Data de nascimento no formato `YYYY-MM-DD`.
        document_type:
          description: >-
            Categoria do documento, independente do país emissor. Tipos que não
            caem no mapa viram `other`.


            | Valor | O que é |

            | --- | --- |

            | `id_card` | Documento de identidade |

            | `drivers_license` | Carteira de motorista |

            | `passport` | Passaporte |

            | `other` | Outro tipo reconhecido pelo provedor |
          anyOf:
            - type: string
              enum:
                - id_card
                - drivers_license
                - passport
                - other
            - type: 'null'
        document_number:
          type:
            - string
            - 'null'
          description: Número como consta no documento.
        document_country:
          type:
            - string
            - 'null'
          description: País emissor em ISO 3166-1 alpha-2, por exemplo `BR`.
        document_version:
          type:
            - string
            - 'null'
          description: Versão ou modelo do documento, segundo o provedor.
        document_issued_at:
          type:
            - string
            - 'null'
          format: date
          description: Data de emissão no formato `YYYY-MM-DD`.
        document_expires_at:
          type:
            - string
            - 'null'
          format: date
          description: >-
            Vencimento do documento no formato `YYYY-MM-DD`, ou `null` se não
            expira. Não confundir com o `expires_at` da raiz, que é o prazo da
            sessão hospedada.
  responses:
    Unauthorized:
      description: Chave de API ausente ou inválida.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              type: authentication_error
              code: invalid_api_key
              message: The API key provided is invalid.
              doc_url: https://docs.id.zapsign.com.br/invalid_api_key
              request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4
    NotFound:
      description: Recurso não encontrado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              type: not_found
              code: not_found
              message: No such resource.
              doc_url: https://docs.id.zapsign.com.br/not_found
              request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4
    TooManyRequests:
      description: Limite de requisições excedido. Veja [Limites de uso](/limites-de-uso).
      headers:
        Retry-After:
          description: Segundos a aguardar antes de tentar de novo. Presente em todo 429.
          schema:
            type: integer
            minimum: 1
        RateLimit-Limit:
          description: Teto de requisições da classe para a conta. Só no 429 de taxa.
          schema:
            type: integer
            minimum: 1
        RateLimit-Remaining:
          description: Requisições restantes na janela atual. Só no 429 de taxa.
          schema:
            type: integer
            minimum: 0
        RateLimit-Reset:
          description: >-
            Segundos até o limite se restabelecer por completo. Só no 429 de
            taxa.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              type: rate_limit_error
              code: rate_limit_exceeded
              message: Too many requests. Please retry after the indicated delay.
              doc_url: https://docs.id.zapsign.com.br/rate_limit_exceeded
              request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4
    InternalError:
      description: Erro interno inesperado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              type: api_error
              code: api_error
              message: An internal error occurred.
              doc_url: https://docs.id.zapsign.com.br/api_error
              request_id: req_3PK3TA2H0MEMTDSAPREHSY4QC4
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Sua chave de API no cabeçalho `Authorization: Bearer sk_...`. Crie e
        revogue chaves no painel ou pelos endpoints de Chaves de API.

````