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.

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Request Body

nifstring

legal_name?string|null

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.

Length1 <= length <= 255

Response Body

application/json

curl -X POST "https://app.beel.es/api/v1/nif/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "nif": "B12345674"
  }'

curl -X POST "https://app.beel.es/api/v1/nif/validate" \  -H "Content-Type: application/json" \  -d '{    "nif": "B12345674"  }'

{
  "success": true,
  "data": {
    "valid": true,
    "status": "VALID",
    "legal_name": "JUAN PEREZ GARCIA",
    "legal_name_verified": true,
    "census_status": "IDENTIFIED",
    "message": "NIF successfully validated in AEAT registry",
    "validated_at": "2025-01-15T10:30:00Z"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Validate a NIF against the AEAT register

Invalid input

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

defaultapplication/json

Valid NIF (individual, name cross-checked)

Valid CIF (legal entity, name NOT cross-checked)

Invalid NIF (not in AEAT registry)

Revoked NIF (in the registry, but revoked by the AEAT)

Deregistered NIF (in the registry, but no longer active)

VeriFactu API unavailable (validation pending)

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json