AccountCompanies

Create a company

Creates a company under the account the request resolves to. The NIF is registered in the name of that account's holder, never in the name of the caller.

  • activate: unless it is false, the company is switched on in aeat_environment and its three default invoice series (ordinary, simplified, corrective) are seeded there. This endpoint never switches an existing company on: that is POST /v1/companies/{company_id}/activations.
  • numbering: decides the code, format, counter reset and starting number those series are born with. Only accepted when the request activates the company.
  • Billing: no charge is ever started here. Creating a production NIF requires being the billing subject of the account (403 otherwise), and an account without billing is rejected with 402; no checkout is opened in either case.
  • Duplicates: a NIF that already exists in the account is rejected with 409, and the response carries the existing error.details.company_id.
  • Addresses: a Spanish postal code (country_code omitted or ES) must have 5 digits, in address and in legal_representative.address; otherwise 422 POSTAL_CODE_INVALID_ES and nothing is created. Other countries' postal codes are free-form.
post/v1/accounts/{account_id}/companies

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/accounts/{account_id}/companies
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

nifstring required

NIF/CIF of the business

legal_namestring required

Legal/fiscal name

entity_type'INDIVIDUAL' | 'LEGAL_ENTITY' required

Taxpayer type. INDIVIDUAL: Natural person (individual self-employed). LEGAL_ENTITY: Legal entity (company with legal form: SL, SA, etc.).

legal_formstring

Legal form (SL, SA, ...). Recommended for LEGAL_ENTITY.

trade_namestring

Commercial/trade name (optional). When omitted or blank, the company is read back with trade_name equal to legal_name: the field always carries the name to display.

default_irpf_ratenumber

Default IRPF retention rate for this company's invoices. Omit it and the company is created with no withholding — BeeL never assumes a rate nobody declared.

aeat_environment'TEST' | 'PROD'

Mode a record lives in — its Test/Live twin. It decides where invoices, customers and quota are accounted.

For a company it also decides which AEAT its NIF is registered against: switching a company on in PROD is what registers it with the real AEAT, so aeat_environment is that same mode and uses this same enum.

activateboolean

Whether to switch the company on in aeat_environment as part of this call.

Creating a company and activating it are two different acts. The company record is free and always creatable; the activation is what seeds the invoice series, registers the NIF and — in PROD — is what gets billed.

  • true (default) — unchanged behaviour: the company is created and switched on in aeat_environment, with its default series seeded there.
  • false — only the company record is created. It is switched on nowhere, has no series and cannot issue yet; aeat_environment is ignored. Activate it later with POST /v1/companies/{company_id}/activations, which is also the only door that opens a Stripe Checkout when the account has no card on file.

Series numbering travels with the activation that seeds it: a request with activate: false and a numbering block that asks for anything is rejected with 422 NUMBERING_REQUIRES_ACTIVATION — the later activation door does not accept numbering, so silently accepting it here would discard it forever. Either drop the numbering block or activate a mode in the same call.

Example request

{
  "nif": "B12345674",
  "legal_name": "Mi Empresa SL",
  "entity_type": "INDIVIDUAL",
  "address": {
    "street": "Calle Mayor, 123",
    "number": "123",
    "floor": "2º A",
    "door": "A",
    "postal_code": "28001",
    "city": "Madrid",
    "province": "Madrid",
    "country": "España",
    "country_code": "ES"
  },
  "legal_form": "SL",
  "legal_representative": {
    "full_name": "María García López",
    "nif": "12345678A",
    "address": {
      "street": "Calle Mayor, 123",
      "number": "123",
      "floor": "2º A",
      "door": "A",
      "postal_code": "28001",
      "city": "Madrid",
      "province": "Madrid",
      "country": "España",
      "country_code": "ES"
    }
  },
  "trade_name": "Mi Empresa",
  "default_main_tax": {
    "type": "IVA",
    "percentage": 21,
    "regime_key": "01"
  },
  "default_irpf_rate": 15,
  "numbering": {
    "code": "FAC",
    "initial_number": 151,
    "format": "{CODIGO}-{YYYY}-{NUM:4}",
    "simplified": {
      "code": "FAC",
      "initial_number": 40,
      "format": "{CODIGO}-{YYYY}-{NUM:4}"
    },
    "corrective": {
      "code": "FAC",
      "initial_number": 40,
      "format": "{CODIGO}-{YYYY}-{NUM:4}"
    }
  },
  "aeat_environment": "PROD"
}

Response

Company created

successboolean

Example response

{
  "data": {
    "entity_type": "INDIVIDUAL",
    "environment": "PROD",
    "aeat_environment": "PROD",
    "account_state": "TEST_ONLY",
    "legal_representative": {
      "full_name": "María García López",
      "nif": "12345678A",
      "address": {
        "street": "Calle Mayor, 123",
        "number": "123",
        "floor": "2º A",
        "door": "A",
        "postal_code": "28001",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España",
        "country_code": "ES"
      }
    },
    "phone": "+34 612 345 678",
    "email": "user@example.com",
    "default_iban": "ES1234567890123456789012",
    "default_swift": "ABCDESMMXXX",
    "invoice_template_type": "MODERN_TABLE",
    "invoice_accent_color": "#fc481d",
    "invoice_language": "es",
    "email_language": "es",
    "series": [
      {
        "name": "Main Series",
        "code": "FAC",
        "description": "Series for standard invoices",
        "format": "{CODIGO}-{YYYY}-{NUM:4}",
        "initial_number": 1
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

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