beel-es · Schema

ProvisionAccountRequest

Request to provision a new account. You retain management access at the level in `access_level` (defaults to `NONE`). There are two ways to integrate and both are supported. **With `email`** the account is born with a holder (a person who can log in) and the response carries a `claim_token` / `claim_url` to hand over. **Without `email`** the account and its NIF are created with **no person at all** — for platforms whose self-employed workers will never use BeeL. themselves — and the response carries no token. Inviting someone to claim it is a deferred, optional step: `POST /v1/accounts/{account_id}/claim-tokens`. Nothing is invented: BeeL. never fabricates a placeholder email.

InvoicingSpainFintechSoftware-as-a-Service

Properties

Name Type Description
email string Optional. Email address of the account holder, used as their login. Omit it to create the account **without a person**: no login, no `person_id` and no `claim_token`. You can add the holder later with
display_name string Human-readable name for the account. Must not be blank.
external_ref string Your own identifier for this account in your system. Used as an idempotency key: re-provisioning with the same `external_ref` returns the existing account (201, not 409).
language object Preferred language for the account holder. Defaults to `es`.
access_level object Optional. The access you retain over this account after provisioning. Defaults to `NONE` (you cover their subscription but cannot access their data). Change it later via PATCH /v1/accounts/{account_id
tax_profile object Optional fiscal identity. When present, the account is created **ready to invoice** in one call: its company record, a default invoice series and VeriFactu config are set up atomically, and the respon
send_email boolean Optional. When `true`, BeeL emails the account holder a claim link (`/reclamar?token=...`) so they can set their password and take ownership. Defaults to `false`: by default you receive the `claim_tok
View JSON Schema on GitHub

JSON Schema

beel-es-provision-account-request-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-provision-account-request-schema.json",
  "title": "ProvisionAccountRequest",
  "description": "Request to provision a new account. You retain management access at the level in `access_level` (defaults to `NONE`).\n\nThere are two ways to integrate and both are supported. **With `email`** the account is born with a holder (a person who can log in) and the response carries a `claim_token` / `claim_url` to hand over. **Without `email`** the account and its NIF are created with **no person at all** — for platforms whose self-employed workers will never use BeeL. themselves — and the response carries no token. Inviting someone to claim it is a deferred, optional step: `POST /v1/accounts/{account_id}/claim-tokens`. Nothing is invented: BeeL. never fabricates a placeholder email.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-accounts-api-openapi.yml#/components/schemas/ProvisionAccountRequest",
  "type": "object",
  "required": [
    "display_name",
    "external_ref"
  ],
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "description": "Optional. Email address of the account holder, used as their login. Omit it to create the account **without a person**: no login, no `person_id` and no `claim_token`. You can add the holder later with `POST /v1/accounts/{account_id}/claim-tokens`. Required when `send_email` is `true` (there is nobody to write to otherwise) — else `422`."
    },
    "display_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Human-readable name for the account. Must not be blank."
    },
    "external_ref": {
      "type": "string",
      "description": "Your own identifier for this account in your system. Used as an idempotency key: re-provisioning with the same `external_ref` returns the existing account (201, not 409)."
    },
    "language": {
      "allOf": [
        {
          "$ref": "#/$defs/Language"
        }
      ],
      "description": "Preferred language for the account holder. Defaults to `es`."
    },
    "access_level": {
      "allOf": [
        {
          "$ref": "#/$defs/AccessLevel"
        }
      ],
      "x-field-extra-annotation": "@com.fasterxml.jackson.annotation.JsonAlias(\"access\")",
      "description": "Optional. The access you retain over this account after provisioning. Defaults to `NONE` (you cover their subscription but cannot access their data). Change it later via PATCH /v1/accounts/{account_id}/access-level. This field was previously named `access`; the old name is still accepted as an alias for backwards compatibility and will be withdrawn in a future major version — send `access_level`."
    },
    "tax_profile": {
      "allOf": [
        {
          "$ref": "#/$defs/ProvisionTaxProfile"
        }
      ],
      "description": "Optional fiscal identity. When present, the account is created **ready to invoice** in one call: its company record, a default invoice series and VeriFactu config are set up atomically, and the response returns `company_id` (the value for the `BeeL-Active-Company` header when issuing invoices). Omit it to create an empty account the holder completes on claim. **Required when `access_level` is `OPERATE`** (issuing on their behalf needs a NIF) — else `422`."
    },
    "send_email": {
      "type": "boolean",
      "default": false,
      "description": "Optional. When `true`, BeeL emails the account holder a claim link (`/reclamar?token=...`) so they can set their password and take ownership. Defaults to `false`: by default you receive the `claim_token` in the response and deliver it yourself. Requires a deliverable `email`: sending `true` without one returns `422`."
    }
  },
  "$defs": {
    "AccessLevel": {
      "type": "string",
      "description": "How much access an actor has to an account or a company. The same three values are used everywhere access is granted or reported — whether the actor is a member of the account or a provisioner managing it on someone's behalf.\n\n`NONE` — no access to the data.\n`VIEW` — read invoices, customers, products, series and fiscal data.\n`OPERATE` — everything in `VIEW`, plus creating and editing them. In Live, issuing invoices for an account you manage additionally requires a signed fiscal representation from the account holder (see `/v1/companies/{company_id}/representation`). In Test you can issue from the start.\n\nAccess level never affects billing: whoever provisioned an account pays for its subscription regardless of the level they keep over it.",
      "enum": [
        "NONE",
        "VIEW",
        "OPERATE"
      ]
    },
    "Address": {
      "description": "Address you send when you create or update a company, a customer or an onboarding.\n\nA required field made only of whitespace passes the length checks below but leaves the\naddress without that part, so it is rejected with `422`: `STREET_EMPTY`,\n`POSTAL_CODE_EMPTY`, `CITY_EMPTY` or `PROVINCE_EMPTY`.\n\nAddresses you read back are described by their own schema.\n",
      "type": "object",
      "required": [
        "street",
        "postal_code",
        "city"
      ],
      "properties": {
        "street": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "Full address (street, number, floor, etc.) - Latin characters only"
        },
        "number": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Street number. Optional: omit it when the address has none, or when `street` already\ncarries the address in full.\n"
        },
        "floor": {
          "type": "string",
          "maxLength": 10,
          "description": "Floor or level"
        },
        "door": {
          "type": "string",
          "maxLength": 10,
          "description": "Door or apartment"
        },
        "postal_code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Postal code (5 digits for Spain, free format for other countries)"
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "City or town - Latin characters only"
        },
        "province": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "Province or state - Latin characters only. Required for an address in Spain\n(`country_code` `ES`, or no country at all); optional elsewhere, where many addresses\nhave none. A Spanish address without it is rejected with a `422`.\n"
        },
        "country": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "Country of the address, as its ISO 3166-1 alpha-2 code (`GB`) or its official name\nin Spanish, English or Catalan (`Reino Unido`, `United Kingdom`, `Regne Unit`;\ncase and accents are ignored). Anything else, such as `UK`, is rejected with\n`422 COUNTRY_CODE_REQUIRED`: send `country_code` instead. If it names a different\ncountry than `country_code`, `422 COUNTRY_CODE_MISMATCH` (`España` alone yields to\na foreign `country_code`: it was the old default). What is stored and\nreturned is always the Spanish name derived from the resulting code, never the\ntext sent. With neither field present, the address is Spanish (`España`).\n"
        },
        "country_code": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "minLength": 2,
          "maxLength": 2,
          "description": "ISO 3166-1 alpha-2 country code: the canonical field that decides the country of\nthe address. It must be a real country code (`GB`, not `UK`); otherwise\n`422 COUNTRY_CODE_REQUIRED`. When it is omitted, the code comes from `country`\n(see there). With neither field present, the address is stored as `ES`.\n"
        }
      }
    },
    "EntityType": {
      "type": "string",
      "description": "Taxpayer type.\nINDIVIDUAL: Natural person (individual self-employed).\nLEGAL_ENTITY: Legal entity (company with legal form: SL, SA, etc.).\n",
      "enum": [
        "INDIVIDUAL",
        "LEGAL_ENTITY"
      ]
    },
    "Language": {
      "type": "string",
      "description": "Supported languages: `es` Spanish, `en` English, `ca` Catalan.\n",
      "enum": [
        "es",
        "en",
        "ca"
      ]
    },
    "LegalRepresentative": {
      "type": "object",
      "required": [
        "full_name",
        "nif",
        "address"
      ],
      "description": "Legal representative data for a legal entity.\nOnly used when entity_type = LEGAL_ENTITY.\n",
      "properties": {
        "full_name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Full name of the legal representative"
        },
        "nif": {
          "type": "string",
          "pattern": "^(\\d{8}[A-Z]|[ABCDEFGHJKLMNPQRSUVW]\\d{7}[A-Z0-9]|[XYZ]\\d{7}[A-Z])$",
          "minLength": 9,
          "maxLength": 9,
          "description": "Tax ID of the legal representative (DNI/CIF/NIE)"
        },
        "address": {
          "allOf": [
            {
              "$ref": "#/$defs/Address"
            },
            {
              "description": "Address of the legal representative"
            }
          ]
        }
      }
    },
    "ProvisionTaxProfile": {
      "type": "object",
      "description": "The account's fiscal identity, to set it up ready to invoice. Same field vocabulary as `POST /v1/accounts/{account_id}/companies` (`CreateCompanyRequest`). Tax rates fall back to system defaults when omitted; the invoice series is always created with system defaults (the holder edits it later).",
      "required": [
        "nif",
        "legal_name",
        "entity_type",
        "address"
      ],
      "properties": {
        "nif": {
          "type": "string",
          "description": "Spanish tax id (NIF/CIF). Validated against the AEAT census; an invalid NIF returns 422."
        },
        "legal_name": {
          "type": "string",
          "description": "Registered fiscal name."
        },
        "entity_type": {
          "$ref": "#/$defs/EntityType"
        },
        "address": {
          "$ref": "#/$defs/Address"
        },
        "legal_form": {
          "type": "string",
          "description": "Legal form (e.g. `SL`). Recommended for `LEGAL_ENTITY`."
        },
        "legal_representative": {
          "$ref": "#/$defs/LegalRepresentative"
        },
        "trade_name": {
          "type": "string",
          "description": "Commercial/trade name shown on invoices (defaults to `legal_name`)."
        },
        "default_main_tax": {
          "$ref": "#/$defs/TaxInfo"
        },
        "default_irpf_rate": {
          "type": "number",
          "description": "Default IRPF withholding percentage (use `0` for exempt). Omit it and the company is created with **no withholding at all** — BeeL never assumes a rate nobody declared. You know your account holder's regime; set it explicitly when they do withhold."
        }
      }
    },
    "RegimeKey": {
      "type": "string",
      "enum": [
        "01",
        "02",
        "03",
        "04",
        "05",
        "06",
        "07",
        "08",
        "09",
        "10",
        "11",
        "14",
        "15",
        "17",
        "18",
        "19",
        "20"
      ],
      "description": "Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies:\n- 01: General regime operation\n- 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`)\n- 03: Used goods, art, antiques (not accepted, see below)\n- 04: Investment gold\n- 05: Travel agencies\n- 06: Group of entities (not accepted, see below)\n- 07: Cash basis\n- 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA\n  on an IGIC line. It is **not** the general regime of IGIC, which is `01`.\n- 09: Mediating agencies\n- 10: Third-party collections\n- 11: Local rental\n- 14: VAT pending in certifications (not accepted, see below)\n- 15: VAT pending successive tract\n- 17: OSS and IOSS\n- 18: Equivalence surcharge\n- 19: REAGYP\n- 20: Simplified regime\n\n**What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on\nIVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with\n`422` and the code in brackets:\n- `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 %\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose\n  recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`,\n  `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`).\n- `11` (IVA): a subject line only at 21 %, and no reverse charge\n  (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them\n  data the invoice does not carry (a cost-based taxable base; an operation date after the\n  issue date and a public-administration recipient).\n- `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice\n  must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The\n  corrective of an invoice that already carried `03` keeps it.\n- `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries\n  the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge,\n  no non-subject reason and, of the exemptions, only art. 20 or `OTRO`\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n`GET /v1/tax-types` only offers the keys that are accepted.\n\n**One exception to \"a key you send is the key you get\":** when the line ends up\ncarrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate`\nor it was inherited from the company's tax configuration — a `01` is rewritten to\n`18`, because a surcharge under the general regime is fiscally incoherent. Send\n`equivalence_surcharge_rate: 0` explicitly to keep `01`. See\n`equivalence_surcharge_rate` in the invoice line for the full rules.\n"
    },
    "TaxInfo": {
      "type": "object",
      "required": [
        "type",
        "percentage"
      ],
      "properties": {
        "type": {
          "$ref": "#/$defs/TaxType"
        },
        "percentage": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Tax percentage"
        },
        "regime_key": {
          "$ref": "#/$defs/RegimeKey"
        }
      },
      "description": "Complete tax information with cross-validations:\n- IVA: real rates 4, 10, 21, and the temporary 2, 5 and 7.5 (see below for 0)\n- IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real \"Tipo Cero\"\n- IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0)\n- OTHER: any percentage between 0 and 100\n\n**0 % under IVA and IPSI is not a rate, it is the exemption sentinel.** It is accepted\non a line, but only together with an `exemption_reason` (exempt or non-subject\noperation); on its own it says nothing and the line is rejected. That is why\n`GET /v1/tax-types` publishes the IVA rates without 0: the legitimate way\nto a 0 % IVA line is through an exemption reason, which the same response also\npublishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and\nneeds no reason.\n\n**IVA 5 %** (the temporary rate applied from 2022 to electricity, gas and certain\nfoodstuffs) is no longer in force for new operations. AEAT only accepts it on operations\ndated from 2022-07-01 to 2024-09-30: send the `operation_date` of that period, because\nwithout one the issue date decides and a line at 5 % is rejected with\n`422 VAT_RATE_NOT_ACCEPTED_ON_DATE`. Its equivalence surcharge pair is 0.5 up to 2022-12-31\nand 0.62 from 2023-01-01. **IVA 2 % and 7.5 %** (temporary rates of the last quarter of 2024)\nare accepted only on operations dated from 2024-10-01 to 2024-12-31, with surcharges 0.26\nand 1.\n\nException: when regime_key = \"17\" (OSS/IOSS) the invoice applies the destination\ncountry VAT instead of the Spanish one, so any percentage in the EU range [0, 27]\nis accepted regardless of the tax type set — including 0 without an exemption reason.\n"
    },
    "TaxType": {
      "type": "string",
      "enum": [
        "IVA",
        "IGIC",
        "IPSI",
        "OTHER"
      ],
      "description": "Tax type by territory:\n- IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period)\n- IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%)\n- IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%)\n- OTHER: Configurable 0%-100%\n\nUnder IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject\nsentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate.\nSee `TaxInfo` for the full rules.\n"
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/beel-es-provision-account-request"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.