Endereços da PF

Este endpoint devolve os endereços conhecidos de um CPF: o endereço atual e os anteriores registrados na base, cada um com o ano em que foi atualizado pela última vez.

É um endpoint de consulta de endereço apenas. Ele não devolve nome, nome da mãe nem data de nascimento — para os dados de identificação, use o Bureau PF.

Request

GET /bureau/v2/person-addresses/{CPF}

Parâmetros

Parâmetro	Descrição	Obrigatório
CPF	CPF da pessoa consultada	Sim

O CPF pode ser enviado com ou sem máscara (123.456.789-09 ou 12345678909), sempre com os 11 dígitos, incluindo os zeros à esquerda. Um CPF que não passa na validação do dígito verificador devolve 422 antes de qualquer consulta.

Headers

Authorization: ApiKey <sua-chave-de-api>

Parâmetros de query são ignorados

Este endpoint não usa parâmetros de query. Um parâmetro desconhecido na URL não gera erro aqui: ele é simplesmente ignorado, e a resposta vem 200 normalmente.

Exemplo Request

curl -i 'https://api.nxcd.app/bureau/v2/person-addresses/12345678909' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI'

Response

🚧 O data aqui é um objeto, não uma lista

A lista de endereços fica em data.addresses. O data em si é um objeto, com o CPF consultado ao lado da lista.

Campo	Descrição	Tipo
id	Identificador único da requisição	String
version	Versão da API que atendeu a chamada	String
data	Objeto com o resultado da consulta	Object
data.taxId	CPF consultado, sem máscara	String
data.addresses	Lista de endereços. Vem vazia quando nada foi encontrado.	Object[]
metadata	Metadados da requisição	Object
metadata.timeSpent	Tempo de processamento da requisição, em milissegundos	Number

data.addresses[]

Cada item da lista é um endereço, sempre com os nove campos abaixo.

Campo	Descrição	Tipo
address	Logradouro	String
number	Número	String
complement	Complemento	String
district	Bairro	String
zipCode	CEP	String
state	Unidade federativa, em duas letras	String
city	Cidade	String
fullAddress	O endereço completo em uma única linha, como veio da base	String
updateYear	Ano da última atualização deste endereço na base	String

Campo ausente vem como texto vazio, nunca como null

Todos os nove campos aparecem em todo endereço. Um dado que a base não tem vem como "". Nenhum deles vem null nem some do objeto — para saber se há valor, teste a string vazia.

O updateYear também é texto, não número.

{
  "address": "RUA DAS FLORES",
  "number": "1000",
  "complement": "APTO 51",
  "district": "CENTRO",
  "zipCode": "01010000",
  "state": "SP",
  "city": "SAO PAULO",
  "fullAddress": "RUA DAS FLORES, 1000, APTO 51, CENTRO, SAO PAULO - SP, 01010000",
  "updateYear": "2024"
}

Exemplo completo

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {
    "taxId": "12345678909",
    "addresses": [
      {
        "address": "RUA DAS FLORES",
        "number": "1000",
        "complement": "APTO 51",
        "district": "CENTRO",
        "zipCode": "01010000",
        "state": "SP",
        "city": "SAO PAULO",
        "fullAddress": "RUA DAS FLORES, 1000, APTO 51, CENTRO, SAO PAULO - SP, 01010000",
        "updateYear": "2024"
      },
      {
        "address": "AVENIDA DAS ACACIAS",
        "number": "45",
        "complement": "",
        "district": "JARDIM AMERICA",
        "zipCode": "13030000",
        "state": "SP",
        "city": "CAMPINAS",
        "fullAddress": "AVENIDA DAS ACACIAS, 45, JARDIM AMERICA, CAMPINAS - SP, 13030000",
        "updateYear": "2019"
      }
    ]
  },
  "metadata": {
    "timeSpent": 480
  }
}

Quando nada é encontrado

O taxId vem como texto vazio e addresses como lista vazia. A resposta continua sendo 200.

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {
    "taxId": "",
    "addresses": []
  },
  "metadata": {
    "timeSpent": 210
  }
}

Headers de resposta

Header	Quando aparece
Nextid-ReqId	Em todas as respostas. Traz o identificador da requisição, o mesmo do campo id do corpo.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ausente, inválida, ou sem a permissão nextid.bureaus.naturalPersonBureau.
404 Not Found	A versão informada na URL não existe. Só v2 é aceita.
422 Unprocessable Entity	CPF que não passa na validação do dígito verificador.
500 Internal Server Error	Falha inesperada durante o processamento.

Exemplo de resposta com CPF inválido:

Status Code: 422

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid Federal Revenue Number"
  }
}

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Versões

A única versão é a v2, e ela é a que atende quando a versão é omitida na URL. /bureau/person-addresses/{CPF} e /bureau/v2/person-addresses/{CPF} são equivalentes.

Versão	Situação	O que muda
v2	Recomendada	Única versão. É o que responde quando a versão é omitida na URL.

Qualquer outro valor no lugar de v2 devolve 404.