API
Enviar Documentos
Envie documentos de identificação para análise de autenticidade
POST
/
docs-gateway
/
api
/
v1
/
documents
/
import
Enviar Documentos
curl --request POST \
--url https://api.valid.com/docs-gateway/api/v1/documents/import \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"cpf": "<string>",
"documents": {
"identification.front": "<string>",
"identification.back": "<string>"
},
"selfie": "<string>",
"workflowPresetAlias": "<string>",
"confidenceIdcheck": "<string>"
}
'import requests
url = "https://api.valid.com/docs-gateway/api/v1/documents/import"
payload = {
"cpf": "<string>",
"documents": {
"identification.front": "<string>",
"identification.back": "<string>"
},
"selfie": "<string>",
"workflowPresetAlias": "<string>",
"confidenceIdcheck": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
cpf: '<string>',
documents: {'identification.front': '<string>', 'identification.back': '<string>'},
selfie: '<string>',
workflowPresetAlias: '<string>',
confidenceIdcheck: '<string>'
})
};
fetch('https://api.valid.com/docs-gateway/api/v1/documents/import', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.valid.com/docs-gateway/api/v1/documents/import",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'cpf' => '<string>',
'documents' => [
'identification.front' => '<string>',
'identification.back' => '<string>'
],
'selfie' => '<string>',
'workflowPresetAlias' => '<string>',
'confidenceIdcheck' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.valid.com/docs-gateway/api/v1/documents/import"
payload := strings.NewReader("{\n \"cpf\": \"<string>\",\n \"documents\": {\n \"identification.front\": \"<string>\",\n \"identification.back\": \"<string>\"\n },\n \"selfie\": \"<string>\",\n \"workflowPresetAlias\": \"<string>\",\n \"confidenceIdcheck\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.valid.com/docs-gateway/api/v1/documents/import")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cpf\": \"<string>\",\n \"documents\": {\n \"identification.front\": \"<string>\",\n \"identification.back\": \"<string>\"\n },\n \"selfie\": \"<string>\",\n \"workflowPresetAlias\": \"<string>\",\n \"confidenceIdcheck\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.valid.com/docs-gateway/api/v1/documents/import")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cpf\": \"<string>\",\n \"documents\": {\n \"identification.front\": \"<string>\",\n \"identification.back\": \"<string>\"\n },\n \"selfie\": \"<string>\",\n \"workflowPresetAlias\": \"<string>\",\n \"confidenceIdcheck\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"documentId": "123e4567-e89b-12d3-a456-426614174000",
"batchExternalId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"backofficeBatchId": "229462",
"flexImageResponse": {
"id": "229462",
"status": "created"
}
}
{
"error": "INVALID_WORKFLOW_PRESET",
"message": "workflowPresetAlias inválido ou indisponível para documentoscopia",
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"timestamp": "2026-06-01T12:00:00.000Z"
}
{
"error": "FLEXIMAGE_IMPORT_FAILED",
"message": "Invalid file type for selfie: \"application/pdf\". Allowed types: jpg, jpeg, png",
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"timestamp": "2026-06-01T12:00:00.000Z"
}
{
"error": "FLEXIMAGE_IMPORT_FAILED",
"message": "Unknown error",
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"timestamp": "2026-06-01T12:00:00.000Z"
}
Request Body
string
required
CPF do titular do documento. Aceita 11 dígitos, com ou sem máscara, e os dígitos verificadores precisam ser válidos.Exemplo:
12345678909object
required
Imagens do documento de identificação. As chaves são literais, com ponto no nome.
Show propriedades
Show propriedades
string
required
Frente do documento em data URI base64.Limite de 10 MB. Formatos: JPG, JPEG, PNG e PDF.Exemplo:
data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...string
Verso do documento em data URI base64. Quando informado, frente e verso são unidos em um único PDF antes da análise.Limite de 10 MB. Formatos: JPG, JPEG, PNG e PDF.Exemplo:
data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...string
Selfie do titular em data URI base64, usada na comparação facial com a face do documento.Limite de 10 MB. Formatos: JPG, JPEG e PNG.Exemplo:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...string
Alias do preset de workflow que define o modo de análise e o prazo. Quando omitido, o preset configurado no projeto é aplicado.Consulte os valores disponíveis em Listar Presets de Workflow.Exemplo:
documentoscopia_auto_base_face_15minstring
Nível de confiança esperado na comparação facial. Quando omitido, o valor configurado no projeto é aplicado.Exemplo:
HIGHO tamanho máximo do corpo da requisição não deve ultrapassar 50 MB.
Response
string
Identificador da requisição.Exemplo:
7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0cstring
Identificador do documento criado. Use-o para consultar status, resultado, arquivos e face.Exemplo:
123e4567-e89b-12d3-a456-426614174000string
Identificador externo do lote enviado para análise.Exemplo:
7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0cstring
Identificador do lote gerado no processamento.Exemplo:
229462object
Retorno do serviço de processamento no envio do lote.
{
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"documentId": "123e4567-e89b-12d3-a456-426614174000",
"batchExternalId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"backofficeBatchId": "229462",
"flexImageResponse": {
"id": "229462",
"status": "created"
}
}
{
"error": "INVALID_WORKFLOW_PRESET",
"message": "workflowPresetAlias inválido ou indisponível para documentoscopia",
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"timestamp": "2026-06-01T12:00:00.000Z"
}
{
"error": "FLEXIMAGE_IMPORT_FAILED",
"message": "Invalid file type for selfie: \"application/pdf\". Allowed types: jpg, jpeg, png",
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"timestamp": "2026-06-01T12:00:00.000Z"
}
{
"error": "FLEXIMAGE_IMPORT_FAILED",
"message": "Unknown error",
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"timestamp": "2026-06-01T12:00:00.000Z"
}
Erros
Respostas de erro possíveis neste endpoint:error | HTTP |
|---|---|
UNAUTHORIZED | 401 |
INVALID_WORKFLOW_PRESET | 400 |
FLEXIMAGE_IMPORT_FAILED | 400, 502 |
⌘I
Enviar Documentos
curl --request POST \
--url https://api.valid.com/docs-gateway/api/v1/documents/import \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"cpf": "<string>",
"documents": {
"identification.front": "<string>",
"identification.back": "<string>"
},
"selfie": "<string>",
"workflowPresetAlias": "<string>",
"confidenceIdcheck": "<string>"
}
'import requests
url = "https://api.valid.com/docs-gateway/api/v1/documents/import"
payload = {
"cpf": "<string>",
"documents": {
"identification.front": "<string>",
"identification.back": "<string>"
},
"selfie": "<string>",
"workflowPresetAlias": "<string>",
"confidenceIdcheck": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
cpf: '<string>',
documents: {'identification.front': '<string>', 'identification.back': '<string>'},
selfie: '<string>',
workflowPresetAlias: '<string>',
confidenceIdcheck: '<string>'
})
};
fetch('https://api.valid.com/docs-gateway/api/v1/documents/import', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.valid.com/docs-gateway/api/v1/documents/import",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'cpf' => '<string>',
'documents' => [
'identification.front' => '<string>',
'identification.back' => '<string>'
],
'selfie' => '<string>',
'workflowPresetAlias' => '<string>',
'confidenceIdcheck' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.valid.com/docs-gateway/api/v1/documents/import"
payload := strings.NewReader("{\n \"cpf\": \"<string>\",\n \"documents\": {\n \"identification.front\": \"<string>\",\n \"identification.back\": \"<string>\"\n },\n \"selfie\": \"<string>\",\n \"workflowPresetAlias\": \"<string>\",\n \"confidenceIdcheck\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.valid.com/docs-gateway/api/v1/documents/import")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"cpf\": \"<string>\",\n \"documents\": {\n \"identification.front\": \"<string>\",\n \"identification.back\": \"<string>\"\n },\n \"selfie\": \"<string>\",\n \"workflowPresetAlias\": \"<string>\",\n \"confidenceIdcheck\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.valid.com/docs-gateway/api/v1/documents/import")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"cpf\": \"<string>\",\n \"documents\": {\n \"identification.front\": \"<string>\",\n \"identification.back\": \"<string>\"\n },\n \"selfie\": \"<string>\",\n \"workflowPresetAlias\": \"<string>\",\n \"confidenceIdcheck\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"documentId": "123e4567-e89b-12d3-a456-426614174000",
"batchExternalId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"backofficeBatchId": "229462",
"flexImageResponse": {
"id": "229462",
"status": "created"
}
}
{
"error": "INVALID_WORKFLOW_PRESET",
"message": "workflowPresetAlias inválido ou indisponível para documentoscopia",
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"timestamp": "2026-06-01T12:00:00.000Z"
}
{
"error": "FLEXIMAGE_IMPORT_FAILED",
"message": "Invalid file type for selfie: \"application/pdf\". Allowed types: jpg, jpeg, png",
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"timestamp": "2026-06-01T12:00:00.000Z"
}
{
"error": "FLEXIMAGE_IMPORT_FAILED",
"message": "Unknown error",
"requestId": "7d7a6f2b-8d9f-4f55-9a2d-ec8e7b4f1d0c",
"timestamp": "2026-06-01T12:00:00.000Z"
}