Consultar validação

Consulta uma validação pelo identificador.

curl --request GET \
  --url https://api.id.zapsign.com.br/v1/validations/{id} \
  --header 'Authorization: Bearer <token>'

const url = 'https://api.id.zapsign.com.br/v1/validations/{id}';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.id.zapsign.com.br/v1/validations/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.id.zapsign.com.br/v1/validations/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.id.zapsign.com.br/v1/validations/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
    }
  }
}

GET

validations

{id}

Consulta uma validação pelo identificador.

curl --request GET \
  --url https://api.id.zapsign.com.br/v1/validations/{id} \
  --header 'Authorization: Bearer <token>'

const url = 'https://api.id.zapsign.com.br/v1/validations/{id}';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.id.zapsign.com.br/v1/validations/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.id.zapsign.com.br/v1/validations/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

require 'uri'
require 'net/http'

url = URI("https://api.id.zapsign.com.br/v1/validations/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
    }
  }
}

Acompanhar uma validação hospedada

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

Authorizations

Authorization

string

header

required

Sua chave de API no cabeçalho Authorization: Bearer sk_.... Crie e revogue chaves no painel ou pelos endpoints de Chaves de API.

Path Parameters

string

required

Identificador da validação.

Response

Validação encontrada.

Resultado de uma validação.

object

enum<string>

required

Sempre validation.

Available options:

validation

string

required

Identificador único da validação.

Example:

"val_0NQW3MVYJYQ453E95V3V1T76AV"

type

enum<string>

required

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.

Available options:

liveness_document_match,

liveness_cpf_match,

cpf_phone_match,

sim_swap,

telco_financial_capacity

status

enum<string>

required

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

Available options:

pending,

completed,

failed,

expired

result

enum<string> | null

required

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

Available options:

passed,

not_passed,

match,

no_match,

recent_swap,

no_recent_swap,

high_capacity,

moderate_capacity,

low_capacity,

unknown

reason_code

enum<string> | null

required

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

Available options:

liveness_failed,

face_mismatch,

spoof_detected,

document_tampered,

document_invalid,

document_unreadable,

cpf_reference_not_found,

data_unavailable,

phone_not_covered

external_id

string | null

required

A referência de correlação que você enviou na criação.

created_at

string<date-time>

required

Data de criação em ISO-8601.

resolved_at

string<date-time> | null

required

Data de resolução em ISO-8601. É null enquanto não resolvida.

validation_url

string | null

required

URL para onde redirecionar o titular. Preenchida nas validações hospedadas; null nas síncronas.

expires_at

string<date-time> | null

required

Quando a sessão hospedada vence, em ISO-8601. Preenchida nas validações hospedadas; null nas síncronas.

details

object | null

required

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.

Show child attributes

⌘I

Referência da API

Validações

Chaves de API

Consultar validação

Acompanhar uma validação hospedada

Authorizations

Path Parameters

Response

​Acompanhar uma validação hospedada

Authorizations

Path Parameters

Response

Acompanhar uma validação hospedada