E-Social

The Registration Qualification Lookup application lets the user check whether the CPF (Cadastro de Pessoa Física, the Brazilian individual taxpayer number) and the NIS (Número de Identificação Social, the Brazilian social identification number — NIT/PIS/PASEP) are fit to be used in eSocial, the Brazilian government's payroll and labor reporting system.

The lookup checks the four pieces of data together — CPF, NIS, name and date of birth — and returns the discrepancy found, when there is one.

🚧 The body is passed through from the provider, with no transformation

The content of data is whatever the provider returns, delivered as is inside the standard envelope. Three practical consequences:

• The field names are in Portuguese, in the provider's vocabulary (nome, mensagem, orientacao), and not in the English camelCase used by the rest of the API.
• Every block is optional. A block only shows up when the provider has data for it. Never assume a key exists: test before accessing it.
• There is no type guarantee. Since there is no conversion along the way, the same field may arrive as a number or as text depending on where the data came from.

Request

GET /esocial-qualificacao-cadastral/v1

Parameters

Parameter	Description	Required
taxId	CPF	Yes
birthdate	Date of birth	Yes
nis	NIS	Yes
name	Name	Yes

All four are required for real: if any one of them is missing, the call is refused with 422 and the message Required params: taxId, birthdate, nis and name, before any lookup is performed.

TIP

The CPF can be sent with or without the mask (12345678909 or 123.456.789-09) and must be sent with all its characters, including any leading zeros.

Only taxId is validated by the API — a CPF that fails the check-digit validation returns 422. birthdate, nis and name are passed on to the provider exactly as they arrived, with no format validation on this side.

Headers

Authorization: ApiKey <your-api-key>

An unknown query parameter is ignored

A parameter that is not one of taxId, birthdate, nis and name does not raise an error: it is simply ignored.

Example request

GET /esocial-qualificacao-cadastral/v1?taxId=12345678909&name=Maria da Silva&birthdate=01/01/2001&nis=00000000000

curl -i -G 'https://api.nxcd.app/esocial-qualificacao-cadastral/v1' \
  --header 'Authorization: ApiKey YOUR_API_KEY' \
  --data-urlencode 'taxId=12345678909' \
  --data-urlencode 'name=Maria da Silva' \
  --data-urlencode 'birthdate=01/01/2001' \
  --data-urlencode 'nis=00000000000'

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.cpf	CPF queried	String
data.eSocialQualificacaoCadastral	Object with the result of the lookup	Object
data.eSocialQualificacaoCadastral.nome	Name of the person queried	String
data.eSocialQualificacaoCadastral.dataNascimento	Date of birth of the person queried	String
data.eSocialQualificacaoCadastral.cpf	CPF of the person queried	String
data.eSocialQualificacaoCadastral.nis	NIS of the person queried	String
data.eSocialQualificacaoCadastral.mensagem	Message returned by the lookup	String
data.eSocialQualificacaoCadastral.orientacao	Guidance returned by the lookup	String
data.eSocialQualificacaoCadastral.urlComprovante	URL of the receipt of the lookup performed	String
metadata	Object with the metadata of the request	Object
metadata.timeSpent	Request time, in milliseconds	Number

The discrepancy comes in mensagem and orientacao

There is no boolean field for "fit" or "not fit". When any of the four pieces of data diverges from the registration, the provider describes the discrepancy in mensagem ("message") and what to do about it in orientacao ("guidance").

JSON examples

Here are some JSON examples of the response.

1. Example when the data is found

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v1",
  "data": {
    "cpf": "12345678909",
    "eSocialQualificacaoCadastral": {
      "nome": "Maria da Silva",
      "dataNascimento": "01/01/2001",
      "cpf": "12345678909",
      "nis": "00000000000",
      "mensagem": "O nome existente no cadastro do CPF é : MARIA DA SILVA SANTOS",
      "orientacao": " Verifique os dados digitados. Se estiverem corretos, dirija-se a uma agência do Banco do Brasil ou Correios, entidades autorizadas pela RFB, para regularização do CPF.",
      "urlComprovante": "https://..."
    }
  },
  "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.eSocial permission.
404 Not Found	The version informed in the URL does not exist. Only v1 is accepted.
422 Unprocessable Entity	taxId, birthdate, nis or name is missing, or the CPF fails the check-digit validation.
500 Internal Server Error	Unexpected failure during processing.

The two causes of 422 have distinct messages, and the missing-parameter check comes first:

Situation	Message
One or more of the four parameters is missing	Required params: taxId, birthdate, nis and name
All four came, but the CPF is invalid	Invalid taxId (CPF)

Example of a response with a missing parameter:

Status Code: 422

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "error": {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Required params: taxId, birthdate, nis and name"
  }
}

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

Versions

The only version is v1, and it is the one that answers when the version is omitted from the URL. /esocial-qualificacao-cadastral and /esocial-qualificacao-cadastral/v1 are equivalent.

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

Any other value in place of v1 returns 404 with the message API version not found.

Related endpoint

To check the name, mother's name and date of birth of a CPF straight at the Federal Revenue Service, see the Individual Bureau.