Consulta CPF — Endereços
Last updated
Retorna endereços vinculados ao CPF, com localização, prioridade e coordenadas quando disponíveis.
| Propriedade | Valor |
|---|---|
| Dataset | cpf_enderecos |
| Método e caminho | POST /datasets/cpf_enderecos/queries |
Versão do schema de dados (schema_version) |
1.0.0 |
| Entrada | CPF |
| Consultas em lote | Suportadas, conforme disponibilidade no catálogo |
Requisição
curl --request POST 'https://api.verifica-online.com.br/datasets/cpf_enderecos/queries' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: exemplo-cpf-enderecos-001' \
--data '{"cpf":"52998224725"}'
{
"cpf": "52998224725"
}
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
cpf |
string |
Sim | Exatamente 11 dígitos, sem pontuação ou espaços, com dígitos verificadores válidos. Sequências de um único dígito repetido são rejeitadas. |
O corpo aceita somente cpf; campos adicionais e CPF numérico são rejeitados. Não são aceitos parâmetros de consulta na URL. Validar os dígitos não comprova existência, identidade ou titularidade do documento.
Veja autenticação e requisições, idempotência e cobrança.
Exemplo de data
O CPF é didático e todos os dados de endereço abaixo são sintéticos. O exemplo não representa uma resposta garantida nem comprova residência ou titularidade. Consulte o envelope comum para os campos externos a data.
{
"cpf": "52998224725",
"total": 1,
"addresses": [
{
"street_type": "Rua",
"street": "Exemplo",
"number": "100",
"complement": "Sala de Exemplo",
"district": "Bairro de Exemplo",
"city": "São Paulo",
"state": "SP",
"postal_code": "00000000",
"type": "Residencial",
"full_address": "Rua Exemplo, 100, Sala de Exemplo, Bairro de Exemplo, São Paulo - SP",
"priority": 1,
"latitude": null,
"longitude": null
}
]
}
Contrato de data
data é um objeto ou null. Quando há dados, todas as propriedades do objeto e dos itens estão presentes, sem propriedades adicionais. Campos textuais não anuláveis podem ser "". Textos são retornados sem caracteres de controle. Os limites de texto abaixo usam unidades UTF-16.
| Campo | Tipo | Descrição e limites |
|---|---|---|
cpf |
string |
CPF consultado, com 11 dígitos sem pontuação. |
total |
integer |
Quantidade de endereços efetivamente retornados após seleção e remoção de duplicidades; igual a addresses.length. |
addresses |
array<object> |
Lista de até 1.000 endereços. Em um resultado com dados, contém pelo menos um item. |
addresses[].street_type |
string |
Tipo do logradouro; até 500 unidades. |
addresses[].street |
string |
Nome do logradouro; até 500 unidades. |
addresses[].number |
string |
Número, preservado como texto; até 500 unidades. |
addresses[].complement |
string |
Complemento; até 500 unidades. |
addresses[].district |
string |
Bairro; até 500 unidades. |
addresses[].city |
string |
Município; até 500 unidades. |
addresses[].state |
string |
UF em maiúsculas. Pode ser vazia. |
addresses[].postal_code |
string |
CEP com apenas dígitos, até 500 unidades. Pode estar incompleto. Preserve zeros iniciais. |
addresses[].type |
string |
Classificação do endereço, sem enumeração fixa; até 500 unidades. |
addresses[].full_address |
string |
Endereço completo informado, limitado a 1.000 unidades. Não é montado obrigatoriamente a partir dos demais campos. |
addresses[].priority |
integer ou null |
Prioridade informada; pode ser negativa. null indica ausência ou valor não aproveitável. |
addresses[].latitude |
number ou null |
Latitude entre −90 e 90 graus; null quando ausente ou fora do intervalo. |
addresses[].longitude |
number ou null |
Longitude entre −180 e 180 graus; null quando ausente ou fora do intervalo. |
Um item precisa ter logradouro ou endereço completo aproveitável. A lista contém endereços únicos pela combinação de CEP, logradouro, número, complemento, município e UF, sem distinguir maiúsculas de minúsculas. A ordenação é por prioridade crescente. Ausência de prioridade é tratada como o menor nível de prioridade; a ordem entre itens de mesma prioridade não é garantida. A posição não confirma atualidade nem residência.
Ausência de dados e cobrança
Ausência reconhecida de endereços produz status: "no_data" e data: null, sem cobrança. Uma lista não vazia sem nenhuma entrada aproveitável, uma resposta incoerente ou acima do limite de itens resulta em erro, sem cobrança.
Em uma consulta comum com status: "succeeded", aplica-se o preço efetivo da conta. Consulte GET /datasets para disponibilidade, schema e preço vigentes, e billing para a cobrança da operação. Veja resultados e erros.
Consultas em lote
O dataset aceita POST /datasets/cpf_enderecos/batches quando batch.enabled estiver habilitado no catálogo. Os endereços de cada CPF seguem este contrato. Veja consultas em lote para limites, validação por entrada, reserva, cobrança consolidada, recuperação e webhook.