Individual addresses

This endpoint returns the known addresses of a CPF (the Brazilian individual taxpayer number): the current address and the previous ones recorded in the database, each one with the year it was last updated.

It is an address lookup endpoint only. It does not return name, mother's name or date of birth — for the identification data, use the Individual Bureau.

Request

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

Parameters

Parameter	Description	Required
CPF	CPF of the person being queried	Yes

The CPF can be sent with or without the mask (123.456.789-09 or 12345678909), always with all 11 digits, including any leading zeros. A CPF that fails the check-digit validation returns 422 before any lookup is performed.

Headers

Authorization: ApiKey <your-api-key>

Query parameters are ignored

This endpoint does not use query parameters. An unknown parameter in the URL does not raise an error here: it is simply ignored, and the response comes back 200 as usual.

Example request

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

Response

🚧 data here is an object, not a list

The list of addresses is in data.addresses. data itself is an object, with the CPF queried next to the list.

Field	Description	Type
id	Unique identifier of the request	String
version	API version that served the call	String
data	Object with the result of the lookup	Object
data.taxId	CPF queried, without the mask	String
data.addresses	List of addresses. Comes back empty when nothing is found.	Object[]
metadata	Metadata of the request	Object
metadata.timeSpent	Processing time of the request, in milliseconds	Number

data.addresses[]

Each item of the list is an address, always with the nine fields below.

Field	Description	Type
address	Street address	String
number	Number	String
complement	Address complement	String
district	District	String
zipCode	ZIP code	String
state	State, as two letters	String
city	City	String
fullAddress	The full address on a single line, as it came from the database	String
updateYear	Year this address was last updated in the database	String

A missing field comes as an empty string, never as null

All nine fields appear on every address. A piece of data the database does not have comes as "". None of them comes as null or goes missing from the object — to find out whether there is a value, test for the empty string.

updateYear is also text, not a number.

{
  "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"
}

Full example

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
  }
}

When nothing is found

taxId comes as an empty string and addresses as an empty list. The response is still 200.

Status Code: 200

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

Response headers

Header	When it appears
Nextid-ReqId	On every response. Carries the request identifier, the same one as the id field of the body.

Errors

Code	When it happens
401 Unauthorized	API key missing, invalid, or without the nextid.bureaus.naturalPersonBureau permission.
404 Not Found	The version informed in the URL does not exist. Only v2 is accepted.
422 Unprocessable Entity	CPF that fails the check-digit validation.
500 Internal Server Error	Unexpected failure during processing.

Example of a response with an invalid CPF:

Status Code: 422

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

The format of the error responses is described in HTTP response codes.

Versions

The only version is v2, and it is the one that answers when the version is omitted from the URL. /bureau/person-addresses/{CPF} and /bureau/v2/person-addresses/{CPF} are equivalent.

Version	Status	What changes
v2	Recommended	The only version. It is what answers when the version is omitted from the URL.

Any other value in place of v2 returns 404.