Individual Bureau Online

This endpoint queries the registration data of a CPF (the Brazilian individual taxpayer number) in real time, straight at the source, and also returns the registration status of the CPF at the Brazilian Federal Revenue Service.

It is the online version of the Individual Bureau. Both deliver the same envelope and the same identification fields; the difference is where the data comes from and the status field, which only exists here.

Which one to use

	Individual Bureau	Individual Bureau Online
Route	/bureau/natural-person/{CPF}	/bureau-pf-online/{CPF}
Source of the data	Database queried by our infrastructure	Lookup performed on the spot, at the source
status field	Not returned	Returned
Version in the URL	Accepts /bureau/v2/natural-person/{CPF}	Does not accept a version in the URL
Query parameters	Accepted	None — any of them returns 422
Permission	nextid.bureaus.naturalPersonBureau	nextid.bureaus.naturalPersonBureau.online
Billing	Own key	Own key, separate

Use the Individual Bureau Online when you need the registration status of the CPF, or when the data has to reflect the state at the source at the moment of the call. For the other identification lookups, the Individual Bureau does the job at a lower cost.

🚧 This query is billed separately

The real-time lookup has its own cost and is recorded under a billing key separate from the one used by the Individual Bureau. See Billing.

Request

GET /bureau-pf-online/{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>

This endpoint does not accept query parameters

Unlike the Individual Bureau, here any query parameter returns 422 — including an unknown name, typed by mistake.

GET /bureau-pf-online/12345678909?legacy=true   → 422
GET /bureau-pf-online/12345678909?anything=1    → 422

The refusal is deliberate: each one of the parameters accepted by the Individual Bureau would divert the call to a path that does not perform the real-time lookup, and it would still be billed as online.

There is no version in the URL

/bureau-pf-online/v2/{CPF} does not exist and returns 404. The version field of the body still answers v2, because it describes the format of the payload delivered, not the version of the route.

Example request

curl -i 'https://api.nxcd.app/bureau-pf-online/12345678909' \
  --header 'Authorization: ApiKey YOUR_API_KEY'

Response

Field	Description	Type
id	Unique identifier of the request	String
version	Format of the payload delivered. Always v2	String
data	Object with the result of the lookup	Object
data.federalRevenueNumber	CPF queried, without the mask	String
data.name	Name of the person	String
data.mothersName	Mother's name	String
data.birthdate	Date of birth, in the YYYYMMDD format	Number
data.status	Registration status of the CPF	String
metadata	Metadata of the request	Object
metadata.timeSpent	Processing time of the request, in milliseconds	Number

data.status

This is the field that sets this endpoint apart from the Individual Bureau: it carries the registration status of the CPF at the Federal Revenue Service, as it stands at the moment of the lookup.

The value observed in production for a registration in good standing is "REGULAR".

🚧 The other values are not documented yet

REGULAR is the only value we have confirmed so far. The Federal Revenue Service uses other registration statuses, and they may show up in this field — the full list will be published on this page as soon as it is confirmed.

In the meantime, do not write code that depends on the list of values. Treat "REGULAR" as the good-standing case and any other value as a status to be checked, instead of comparing against a closed list.

JSON example

Status Code: 200

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

When the CPF is not found

data comes back empty. The response is still 200.

Status Code: 200

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

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.

This endpoint applies the masking always — there is no way to turn it off.

Status Code: 200

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

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.online permission.
404 Not Found	A version was used in the URL, such as /bureau-pf-online/v2/{CPF}. This route has no version.
422 Unprocessable Entity	CPF that fails the check-digit validation, or any query parameter in the URL.
500 Internal Server Error	Unexpected failure during processing.

‼️ The Individual Bureau permission does not apply here

nextid.bureaus.naturalPersonBureau.online is a permission of its own. Anyone holding only nextid.bureaus.naturalPersonBureau gets 401 on this endpoint, even while being able to call the Individual Bureau normally.

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.