BeeL
Get StartedVeriFactuStripeAPI Reference
NIF Validation

Validate NIF against AEAT registry

Public endpoint to validate a NIF/CIF against the AEAT registry using VeriFactu.

This endpoint is useful for:

  • Pre-validation before registration (proactive feedback)
  • Validating customer NIFs before creating invoices
  • Verifying that a NIF exists in the registry

Behavior:

  • VALID: The NIF exists in the AEAT registry. Returns the fiscal name.
  • INVALID: The NIF has correct format but doesn't exist in the registry.
  • PENDING: VeriFactu API is temporarily unavailable. The NIF has valid syntax but couldn't be verified against the registry.
  • ERROR: Technical error during validation (invalid syntax, timeout, etc.)

Note about PENDING: If you use this endpoint for pre-validation during registration, a PENDING status indicates that the NIF has valid format and the user can continue. The system will validate the NIF automatically when the service becomes available.

Rate limiting:

  • With API Key: 100 requests/hour
  • With Session Cookie: 1000 requests/hour

Authentication: This endpoint accepts both API Keys and Session Cookies.

Try this endpoint with Claude
Copy the prompt for any assistant, or open it directly in Claude Code (needs it installed).
POST
/v1/nif/validate

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

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)

AEAT validates that the provided name matches the one registered in the census. If it doesn't match, validation will return INVALID.

Length1 <= length <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

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

{
  "success": true,
  "data": {
    "valid": true,
    "status": "VALID",
    "legal_name": "JUAN PEREZ GARCIA",
    "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 required"
  },
  "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": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Update user preferred language PUT

Updates the authenticated user's preferred language. This language is used for: - UI translations - Template names and colors in invoice customization - Emails sent to the user **Supported languages:** - `es` - Spanish (default) - `en` - English - `ca` - Catalan

Cancel representation DELETE

Cancels the current representation process.