Individual Bureau

This endpoint looks up the personal data held by the Brazilian Federal Revenue Service for the CPF (the Brazilian individual taxpayer number) informed.

There is an online version of this query, the Individual Bureau Online, which fetches the data at the source at the moment of the call and also returns the registration status of the CPF. It is billed separately. The comparison between the two is in Which one to use.

Request

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

Parameters

Parameter	Description	Required
CPF	CPF of the person being queried	Yes

TIP

The CPF can be sent with or without the mask (123.456.789-09 or 12345678909) and must be sent with all 11 characters, 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>

Example request

GET /bureau/v2/natural-person/123.456.789-09

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

Response

Field	Description	Type
id	Unique ID of the request	String
version	API version	String
data	Object with the result of the lookup	Object
data.name	Name found	String
data.federalRevenueNumber	CPF found, without the mask	String
data.mothersName	Mother's name found	String
data.birthdate	Date of birth found, in the YYYYMMDD format	Number
metadata	Object with the metadata of the request	Object
metadata.timeSpent	Request time, in milliseconds	Number

This endpoint does not return the registration status

The status field is not part of this response. To get it, use the Individual Bureau Online.

JSON examples

Here are some JSON examples of the response.

1. Example when the CPF is found

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {
    "name": "JOAO DA SILVA",
    "federalRevenueNumber": "12345678909",
    "mothersName": "MARIA DA SILVA",
    "birthdate": 19990201
  },
  "metadata": {
    "timeSpent": 10000
  }
}

2. Example when the CPF is not found

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {},
  "metadata": {
    "timeSpent": 10000
  }
}

3. Example when the CPF belongs to a minor

The personal data comes back masked: name becomes menor de idade ("minor"), and mothersName and birthdate become ****. Watch out for the type: once masked, birthdate comes as text, not as a number.

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {
    "name": "menor de idade",
    "federalRevenueNumber": "12345678909",
    "mothersName": "****",
    "birthdate": "****"
  },
  "metadata": {
    "timeSpent": 10000
  }
}

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/natural-person/{CPF} and /bureau/v2/natural-person/{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 with the message API version not found.

Related endpoint

For the known addresses of this CPF, see Individual addresses.