Sign In

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.