Exemplos
Em toda esta página, os documentos, ids, nomes e números que aparecem nos exemplos são fictícios. Servem para mostrar o formato.
curl, numa chamada
curl -H "Authorization: Bearer is_SUA_CHAVE" \
https://useisearch.com/api/consulta/cpf/12345678909
Node, em dois passos
const API = 'https://useisearch.com/api'
const H = { Authorization: 'Bearer ' + process.env.ISEARCH_CHAVE, 'content-type': 'application/json' }
async function consulta(tipo, doc, extra) {
const r = await fetch(API + '/consulta', { method: 'POST', headers: H, body: JSON.stringify({ tipo, doc, extra }) })
const pedido = await r.json()
if (!r.ok) throw new Error(pedido.erro + ': ' + pedido.msg)
for (;;) {
await new Promise(ok => setTimeout(ok, 1500))
const j = await (await fetch(API + '/consulta/' + pedido.job, { headers: H })).json()
if (j.estado === 'completed') {
if (j.saida.erro) throw new Error(j.saida.erro)
return j.saida
}
if (j.estado === 'failed' || j.estado === 'cancelled') throw new Error(j.saida?.message || 'falhou')
}
}
Python, em dois passos
import os, time, requests
API = "https://useisearch.com/api"
H = {"Authorization": "Bearer " + os.environ["ISEARCH_CHAVE"]}
def consulta(tipo, doc, extra=None):
corpo = {"tipo": tipo, "doc": doc}
if extra:
corpo["extra"] = extra
r = requests.post(API + "/consulta", json=corpo, headers=H, timeout=30)
pedido = r.json()
if not r.ok:
raise RuntimeError(pedido["erro"] + ": " + pedido["msg"])
while True:
time.sleep(1.5)
j = requests.get(API + "/consulta/" + pedido["job"], headers=H, timeout=30).json()
if j["estado"] == "completed":
if "erro" in j["saida"]:
raise RuntimeError(j["saida"]["erro"])
return j["saida"]
if j["estado"] in ("failed", "cancelled"):
raise RuntimeError((j.get("saida") or {}).get("message", "falhou"))
Rotas
POST/consulta30 por minuto
Pede uma consulta. Valida o documento, debita a cota e põe o job na fila.
| campo | tipo | o que é |
|---|
tipo | texto | Um dos tipos da lista no fim desta página. Obrigatório. |
doc | texto | O documento ou termo da busca, no formato do tipo. Obrigatório, até 300 caracteres. |
extra | texto | Segundo campo, só para os tipos que pedem: pix, cep, nascimento e renda (até 60 caracteres) e os filtros da busca por nome (até 240). |
cedo | booleano | Só no tipo cpf: devolve o dossiê na primeira leitura da fonte. Veja "CPF mais rápido". Opcional. |
// resposta 200
{
"job": "0b6f3c1e-7a52-4a0e-9d7e-2f1c5b8a9e10",
"quota": { "mod": "cpf", "dia": "2026-11-13", "custo": 1, "restaPlano": 742 }
}
restaPlano é quanto ainda sobra daquele tipo hoje. Guarde o job: é com ele que você lê o resultado.
GET/consulta/{job}600 por minuto
Lê o estado de um job seu. Chame a cada 1 ou 2 segundos até o estado virar completed, failed ou cancelled.
// resposta 200
{
"id": "0b6f3c1e-7a52-4a0e-9d7e-2f1c5b8a9e10",
"estado": "completed",
"frente": 0,
"saida": { "cpf": "12345678909", "nome": "NOME COMPLETO", "telefones": [ ... ] }
}
| estado | o que significa |
|---|
created | Na fila. O campo frente diz quantas consultas estão na frente. |
active | Rodando agora. |
retry | Falhou uma vez e vai tentar de novo sozinha. |
completed | Terminou. O resultado está em saida. |
failed | Falhou de vez. O motivo está em saida.message. A cota do dia volta em até 1 minuto. |
cancelled | Cancelada. |
Um job completed nem sempre achou alguma coisa. Quando a fonte não tem o documento, ou recusa a consulta, a saída vem só com o motivo, e a cota é devolvida:
{ "id": "...", "estado": "completed", "frente": 0,
"saida": { "erro": "nenhum dado encontrado pra esse documento (nao encontrado no provedor)" } }
Sempre teste saida.erro antes de usar a saída. O job pode ser lido por 1 hora depois de terminar. Passado esse tempo a rota responde 404 com nao-achado, então guarde o resultado do seu lado.
Fotos que chegam depois
No tipo cpf, o dossiê sai antes das fotos de parentes e dos vizinhos. Enquanto eles estão sendo buscados, a saída traz a chave fotos_pendentes. Se você quer essas partes, continue lendo o mesmo job a cada 2 segundos até a chave sumir, por no máximo 90 segundos. A saída relida já vem completa. Se não quer, ignore a chave.
CPF mais rápido
Mande "cedo": true no corpo do POST /consulta de tipo cpf para receber o dossiê assim que a primeira leitura da fonte chega, em vez de esperar a segunda. O que a segunda leitura acrescenta entra depois no mesmo job, do mesmo jeito das fotos: continue lendo enquanto houver fotos_pendentes. Sem cedo, o job só fecha com as duas leituras prontas.
GET/consulta/{tipo}/{doc}30 por minuto
Pede e espera na mesma chamada, por até 170 segundos. Use um tempo limite de pelo menos 180 segundos no seu cliente.
// terminou
{ "job": "...", "estado": "completed", "saida": { ... }, "quota": { ... } }
// não terminou em 170 s: leia depois em GET /consulta/{job}
{ "job": "...", "estado": "pendente", "msg": "ainda rodando, pega em /api/consulta/..." }
- Não aceita
extra. O tipo pix só funciona pelo POST. - Documento com barra, espaço ou acento precisa ir codificado na URL.
- Se a consulta falhar na fonte, responde
502 com consulta. - Aqui também vale testar
saida.erro.
POST/foto60 por minuto
Busca a foto de um parente ou colega que veio no dossiê sem retrato. Cada pessoa dessas listas traz um foto_token; mande o CPF dela e o token.
// corpo
{ "cpf": "12345678909", "token": "FOTO_TOKEN_DA_PESSOA" }
// achou
{ "cpf": "12345678909", "retrato": "data:image/jpeg;base64,...", "retrato_origem": "base oficial", "retrato_oficial": true, "fotos": [] }
// não tem foto
{ "cpf": "12345678909", "retrato": null, "fotos": [] }
O token vale para a pessoa e a consulta de onde saiu; não reaproveite token de outro dossiê. Sem token a rota não acha foto.
POST/face20 por minuto
Reconhecimento facial: recebe uma foto e devolve as pessoas mais parecidas. Custa 2 unidades e responde na mesma chamada, em até 170 segundos.
| campo | tipo | o que é |
|---|
img | texto | A imagem em base64, sem o prefixo data:. Até cerca de 6 MB de arquivo. |
mime | texto | Tipo da imagem, por exemplo image/jpeg. Opcional. |
// resposta 200, da mais parecida para a menos
{
"achados": [
{ "cpf": "12345678909", "nome": "NOME COMPLETO", "similaridade": 97.4, "confianca": "alta",
"data_nasc": "01/01/1990", "sexo": "M", "nome_mae": "NOME DA MAE", "retrato": "data:image/jpeg;base64,..." }
],
"quota": { "mod": "face", "dia": "2026-11-13", "custo": 2, "restaPlano": 198 }
}
Sem rosto reconhecido responde 404 com nao-achado e devolve a cota.
GET/uso
Mostra o que a chave já gastou hoje e o que ainda pode gastar. O dia vira à meia-noite de Brasília.
{
"modulos": { "cpf": { "usadas": 12, "teto": 3000, "resta": 2988 }, "placa": { "usadas": 0, "teto": 300, "resta": 300 } },
"dia": { "usadas": 12, "teto": 50, "resta": 38 },
"creditos": null,
"custo": { "cpf": 1, "face": 2, "foto": 1 },
"tipos": { "cpf": "cpf", "nome": "nome" }
}
modulos: uso por tipo de consulta. Só aparecem os tipos que o seu acesso inclui.dia: teto geral do dia, quando o acesso é por prazo. Vem null quando não há.creditos: saldo de créditos, quando o acesso é por crédito. Nesse caso o resta de cada tipo nunca passa do saldo.custo e tipos: a tabela de custo e a lista de tipos que a API conhece.
GET/saude
Sem chave. Responde { "ok": true } quando a API está de pé. Não diz se as fontes estão respondendo; para isso, o sinal é o erro manutencao nas consultas.