NIF

Validate a NIF against the AEAT register

Checks a NIF or CIF against the AEAT register through VeriFactu and returns what the register says about it. It only reads the register: it creates nothing and stores no customer.

  • status: distinguishes a NIF found in the register from one that is syntactically correct but absent, and from a check that could not be completed because VeriFactu was unavailable — in which case the NIF is validated automatically once the service is back.
  • valid: true: means different things by holder. For an individual, AEAT matched NIF and name together. For a legal entity the name you sent is not verified at all — AEAT identifies a company by its CIF alone — so it says nothing about your name.
  • legal_name_verified: tells those two cases apart.
  • census_status: says whether an identified NIF is also deregistered or revoked.

Invalid input

  • Bad syntax is an answer, not an error: it comes back 200 with status: INVALID, so a pre-validation flow never has to tell rejections apart by status code.
  • A missing NIF is an error: an absent or empty nif answers 422 FIELD_BLANK, with details.field naming it.
post/v1/nif/validate

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/nif/validate
  • Auth: HTTP bearer

Request body

nifstring required

NIF/CIF to validate against the AEAT census. Must be 9 alphanumeric characters.

legal_namestring nullable

Last name and first name (individual) or business name (legal entity).

Important:

  • REQUIRED for individuals (NIFs starting with a number)
  • OPTIONAL for legal entities (NIFs starting with a letter)

For an individual, AEAT matches NIF and name together: send a name the census does not recognise and the person is not identified, so the status comes back INVALID.

For a legal entity, the name is not verified. AEAT identifies a company by its CIF alone — there is no census answer meaning "this name is wrong", so validation depends only on the CIF and any name you send is accepted. Use the legal_name of the response to contrast your own.

Example request

{
  "nif": "12345678A",
  "legal_name": "JUAN PEREZ GARCIA"
}

Response

Validation result

successboolean required

Example response

{
  "success": true,
  "data": {
    "valid": true,
    "status": "VALID",
    "legal_name": "JUAN PEREZ GARCIA",
    "census_status": "IDENTIFIED",
    "message": "NIF successfully validated against the AEAT census",
    "validated_at": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.