BeeL
Get StartedVeriFactuStripeAPI Reference
Companies

Create a company (sub-account)

Creates a new NIF/company under the authenticated account. Invoice series are created automatically with default values.

The environment field decides the creation flow:

  • TEST — created immediately, free. 201 + CompanyData.
  • PROD + owner already PRODUCTION_ACTIVE (production activated, card on file) — created immediately as a production NIF (environment=PROD). Real emission stays blocked by NIF_REPRESENTATION_REQUIRED until the AEAT representation is signed for this (owner, nif). The new NIF is added to the subscription (pay-as-you-go). 201 + CompanyData.
  • PROD + owner SANDBOX_ONLY — rejected with 400 error.code=PRODUCTION_NOT_ACTIVATED. Production must be activated for the account first — a one-time card capture done from the BeeL dashboard: switching to Live mode or creating the first production company there starts the activation checkout automatically. This activation is not part of the public API. Only once the owner is PRODUCTION_ACTIVE can a PROD NIF be created.
Try this endpoint with Claude
Copy the prompt for any assistant, or open it directly in Claude Code (needs it installed).
POST
/v1/companies

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

NIF/CIF of the business

legal_namestring

Legal/fiscal name

entity_typestring

Type of entity

Value in"INDIVIDUAL" | "LEGAL_ENTITY"
address_streetstring
address_number?string
address_postal_codestring
address_citystring
address_provincestring
address_country?string
Default"ES"
legal_form?string

Required for LEGAL_ENTITY

representative_name?string

Required for LEGAL_ENTITY

representative_nif?string

Required for LEGAL_ENTITY

business_display_name?string

Optional display name

tax_type?string
Default"IVA"
tax_percentage?number
Default21
irpf_percentage?number
Default15
environment?string

VeriFactu environment for this company.

  • TEST — Sandbox NIF, invoices reach VeriFactu test (default).
  • PROD — Production NIF; requires the AEAT representation model to be signed (POST /v1/representations/{nif}/sign) before real invoices can be issued. The owner account must already be PRODUCTION_ACTIVE (production activated up-front); otherwise the request is rejected with PRODUCTION_NOT_ACTIVATED.
Default"TEST"
Value in"TEST" | "PROD"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/companies" \  -H "Content-Type: application/json" \  -d '{    "nif": "B12345678",    "legal_name": "Mi Empresa SL",    "entity_type": "INDIVIDUAL",    "address_street": "Calle Mayor",    "address_postal_code": "28001",    "address_city": "Madrid",    "address_province": "Madrid"  }'
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "nif": "string",
    "legal_name": "string",
    "business_display_name": "string",
    "entity_type": "INDIVIDUAL",
    "is_primary": true,
    "verifactu_status": "NOT_CONFIGURED",
    "can_issue_production_invoices": true,
    "environment": "TEST",
    "account_state": "SANDBOX_ONLY",
    "address": {
      "street": "string",
      "number": "string",
      "floor": "string",
      "door": "string",
      "postal_code": "string",
      "city": "string",
      "province": "string",
      "country": "string",
      "country_code": "string"
    },
    "created_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Resource already exists"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Data cannot be processed",
    "details": {
      "field": "Specific error description"
    }
  },
  "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"
  }
}

Cancel representation DELETE

Cancels the current representation process.

Create API key scoped to a company POST

Creates an API key that authenticates directly as this company. The created key cannot have more scopes than the parent key. The optional `environment` field selects the new key's environment. When omitted the key inherits the parent key's environment. A live (PRODUCTION) parent may issue test (SANDBOX) keys, but a test parent cannot issue live keys — that request is rejected with `400` `error.code=ENVIRONMENT_ESCALATION`.