---
title: "Get the tax configuration of a company"
method: GET
path: "/v1/companies/{company_id}/tax-configuration"
tags: ["CompanyTaxConfiguration"]
---

# Get the tax configuration of a company

`GET /v1/companies/{company_id}/tax-configuration`

## Request

- Base URL: `https://app.beel.es/api`
- URL: `https://app.beel.es/api/v1/companies/{company_id}/tax-configuration`
- Auth: HTTP bearer

Returns the tax configuration of a company: its default main tax (`IVA`, `IGIC`,
`IPSI` or `OTHER`) with the default percentage and regime key, the default exemption
reason, its IRPF and equivalence surcharge settings, and the default payment method and
payment term.

The catalogue of tax types this configuration draws from is not company data and lives
outside this resource.

## Response `200`

Configuration retrieved successfully

- object: The envelope every successful JSON response of the BeeL. API is wrapped in. There are no bare resources in v1 and none are planned: the payload always hangs off `data`. - A **single resource** is an object in `data`. - A **collection** hangs off a named key inside `data`, together with its `pagination`, also inside `data` — `data: {invoices: [...], pagination: {...}}`. - A collection carries `pagination` unless its operation declares itself a **closed catalogue**: a fixed, bounded list with nothing to page through. The declaration is explicit in the operation; a missing `pagination` is never something to infer. - `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a documented variant of pagination, not another envelope. Putting the array straight into `data` with `pagination` as its sibling is the shape a v2 would adopt; v1 is not being flipped to it.
  - `success` boolean, required
  - `data` object, required: The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1.
    - `default_main_tax` object, required: Convenience **prefill**, not a default the API applies. Includes tax regime type (IVA/IGIC/IPSI/OTHER), percentage and regime key. It seeds the tax fields of a line where a human (or BeeL itself) is composing one: the dashboard invoice editor, onboarding, and the drafts BeeL generates from payment events. The value is written into the line at that moment and is visible and editable from then on. **Never applied to invoice lines created via the API**: omitting `main_tax` on a `NORMAL` line is a validation error (`422 LINE_MAIN_TAX_REQUIRED`), never a silent fallback to this value. Which tax a line bears is a fiscal decision of the issuer, so the API refuses to guess it — the same line body must produce the same invoice regardless of how the account happens to be configured today. (`SUPLIDO` lines carry no main tax at all, so nothing is prefilled there either.) Common examples: - Standard VAT: { type: "IVA", percentage: 21, regime_key: "01" } - Special Reduced IGIC: { type: "IGIC", percentage: 7, regime_key: "01" } - Standard IPSI: { type: "IPSI", percentage: 10, regime_key: "01" }
      - `type` 'IVA' | 'IGIC' | 'IPSI' | 'OTHER', required: Tax type by territory: - IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period) - IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%) - IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%) - OTHER: Configurable 0%-100% Under IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject sentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate. See `TaxInfo` for the full rules.
      - `percentage` number, required: Tax percentage
      - `regime_key` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '14' | '15' | '17' | '18' | '19' | '20': Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies: - 01: General regime operation - 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`) - 03: Used goods, art, antiques (not accepted, see below) - 04: Investment gold - 05: Travel agencies - 06: Group of entities (not accepted, see below) - 07: Cash basis - 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA on an IGIC line. It is **not** the general regime of IGIC, which is `01`. - 09: Mediating agencies - 10: Third-party collections - 11: Local rental - 14: VAT pending in certifications (not accepted, see below) - 15: VAT pending successive tract - 17: OSS and IOSS - 18: Equivalence surcharge - 19: REAGYP - 20: Simplified regime **What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on IVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with `422` and the code in brackets: - `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 % (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`, `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`). - `11` (IVA): a subject line only at 21 %, and no reverse charge (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them data the invoice does not carry (a cost-based taxable base; an operation date after the issue date and a public-administration recipient). - `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The corrective of an invoice that already carried `03` keeps it. - `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge, no non-subject reason and, of the exemptions, only art. 20 or `OTRO` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). `GET /v1/tax-types` only offers the keys that are accepted. **One exception to "a key you send is the key you get":** when the line ends up carrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate` or it was inherited from the company's tax configuration — a `01` is rewritten to `18`, because a surcharge under the general regime is fiscally incoherent. Send `equivalence_surcharge_rate: 0` explicitly to keep `01`. See `equivalence_surcharge_rate` in the invoice line for the full rules.
    - `default_exemption_reason` 'EXENTA_ART_20' | 'EXENTA_ART_21' | 'EXENTA_ART_22' | 'EXENTA_ART_24' | 'EXENTA_ART_25' | 'EXENTA_ART_26' | 'EXENTA_ART_140' | 'NO_SUJETA_ART_7_9' | 'NO_SUJETA_LOCALIZACION' | 'ISP_ART_84_2_A' | 'ISP_ART_84_2_B' | 'ISP_ART_84_2_C' | 'ISP_ART_84_2_D' | 'ISP_ART_84_2_E' | 'ISP_ART_84_2_F' | 'ISP_ART_84_2_G' | 'REGIMEN_ART_129' | 'REGIMEN_ART_135' | 'REGIMEN_ART_141' | 'REGIMEN_ART_154' | 'REGIMEN_ART_163_DECIES' | 'OTRO': Tax exemption reason code per the Spanish VAT Law (Ley 37/1992, LIVA), with the VeriFactu code each one is reported as. - `EXENTA_ART_20`: exempt, art. 20 (domestic operations such as medical, educational, cultural and financial services, or housing rentals). E1. - `EXENTA_ART_21`: exempt, art. 21 (exports of goods). E2. - `EXENTA_ART_22`: exempt, art. 22 (operations treated as exports). E3. - `EXENTA_ART_24`: exempt, art. 24 (free zones, warehouses and customs regimes). E4. - `EXENTA_ART_25`: exempt, art. 25 (intra-community supplies of goods). E5. - `EXENTA_ART_26`: exempt, art. 26 (intra-community acquisitions of goods). It exempts the buyer's acquisition, not a supply the seller invoices, so an invoice line that carries it is rejected with `EXEMPTION_NOT_FOR_ISSUED_INVOICE`; a supply to another Member State is `EXENTA_ART_25`. - `NO_SUJETA_ART_7_9`: not subject under art. 7 (such as the transfer of a business as a going concern, art. 7.1º). N1. - `NO_SUJETA_LOCALIZACION`: not subject by the place-of-supply rules (intra-community or non-EU services, arts. 69 and 70). N2. - `ISP_ART_84_2_A` … `ISP_ART_84_2_F`: reverse charge (the invoice states «inversión del sujeto pasivo»), art. 84.Uno.2.º letters a) (supplier not established in Spain), b) (unwrought or semi-finished gold), c) (scrap, waste and recovery materials, plastic, paper, cardboard, glass and textile waste, and semi-finished non-ferrous metal products), d) (greenhouse gas emission allowances), e) (certain real estate supplies: in insolvency proceedings, with the exemption waived, or enforcing a security) and f) (construction or renovation works). S2. - `ISP_ART_84_2_G`: reverse charge of letter g) (silver, platinum, palladium, mobile phones, consoles, laptops and tablets). The law requires these supplies to be invoiced in a special series, so an invoice line that carries it is rejected with `REVERSE_CHARGE_CASE_NOT_SUPPORTED`. - `EXENTA_ART_140`: investment gold exemption, art. 140 bis (usually with `regime_key` `04`). E6. - `REGIMEN_ART_129` (agriculture, livestock and fishing, arts. 124 to 134 bis), `REGIMEN_ART_135` (second-hand goods, art and antiques), `REGIMEN_ART_141` (travel agencies), `REGIMEN_ART_154` (equivalence surcharge) and `REGIMEN_ART_163_DECIES` (cash basis, arts. 163 decies to 163 sexiesdecies): operations of special regimes, which VeriFactu identifies by the regime key rather than by an exemption code. An invoice line that carries one is rejected with `EXEMPTION_REGIME_NOT_SUPPORTED_IN_VERIFACTU`; declare the regime with `regime_key` instead. - `OTRO`: any other provision. Requires the text in `exemption_reason_text`. E6.
    - `default_exemption_reason_text` string, nullable: Custom exemption text. Only used when `default_exemption_reason` is `OTRO`, where it is mandatory — same rule as in the invoice line.
    - `apply_equivalence_surcharge` boolean, required: Whether the freelancer is under the equivalence surcharge regime. **Business rule**: If `true`, the `default_equivalence_surcharge` field is REQUIRED.
    - `default_equivalence_surcharge` number: Default equivalence surcharge, as the configuration holds it. It is what is stored, not what a request accepts (see `EquivalenceSurchargePercentage`): a configuration saved with the `0.625` surcharge of VAT at 5 %, before it was corrected to 0.62, is returned as `0.625` until it is updated. **Business rule**: REQUIRED if `apply_equivalence_surcharge` is `true`.
    - `apply_irpf` boolean, required: Whether IRPF withholding should be applied to invoices. Defaults to `false`: no withholding is applied until the user declares one (a rate nobody declared is never invented). **Business rule**: If `true` and `irpf_exempt` is `false`, the `default_irpf_rate` field is REQUIRED.
    - `default_irpf_rate` number: Default IRPF for new invoices, as the configuration holds it. It is what is stored, not what a request accepts (see `IrpfPercentage`): a configuration saved with a rate the table no longer has is returned as it is until it is updated. **Business rule**: REQUIRED if `apply_irpf` is `true` and `irpf_exempt` is `false`.
    - `irpf_exempt` boolean: Whether the freelancer is exempt from IRPF withholding (e.g., business start). **Note**: When `true`, any provided `default_irpf_rate` is saved but not applied to invoices. This allows pre-configuring the rate for when the exemption ends.
    - `default_payment_method` 'NONE' | 'BANK_TRANSFER' | 'CARD' | 'CASH' | 'CHECK' | 'DIRECT_DEBIT' | 'BIZUM' | 'OTHER': Payment method shown on invoices and recurring invoices. - `NONE`: no payment information is shown. - `BANK_TRANSFER`: bank transfer to the IBAN of the payment details; the only method that requires an IBAN. - `CARD`: card payment. - `CASH`: cash payment. - `CHECK`: payment by cheque. - `DIRECT_DEBIT`: direct debit from the customer's bank account. - `BIZUM`: payment through Bizum. - `OTHER`: any other method.
    - `payment_term_days` integer, nullable: Default payment term in days (0-365). Null means no default term.
    - `proforma_validity_days` integer, nullable: Default validity term in days for new proformas (0-365). Null means no default: proformas are created without an expiry date. UI-only default: the dashboard uses it to prefill `valid_until` when creating a proforma (issue date + N days, editable). It is never applied server-side, so the public API contract of `valid_until` does not change.
    - `withholding_options` WithholdingOptions: Withholding rates a company can bear, deduced from the first letter of its NIF. Only individuals pay IRPF (Law 35/2006, art. 8), so no entity bears the rates of individuals (1, 2, 7, 15, and 6, 2.8 and 7.6 in Ceuta and Melilla); any rate an entity cannot bear, on its invoices, products, default configuration or recurring templates, is rejected with `IRPF_RATE_NOT_FOR_CORPORATE_ISSUER`. - **Legal person that pays Corporate Income Tax** (NIF starting with `A`, `B`, `C`, `D`, `F`, `G`, `Q`, `R` or `U`) and **permanent establishment of a non-resident entity** (`W`, which bears the Corporate Income Tax withholding regime, Royal Legislative Decree 5/2004, art. 23.1): only `0`, `19` and `24`. Its income bears withholding only when it is one of those listed in the Corporate Income Tax regulation (Royal Decree 634/2015, art. 60: rents of urban property, image rights, director fees, capital income…), at 19 % or, for image rights, 24 % (art. 66); 19 % is halved to 9.5 for rents of urban property in Ceuta and Melilla. An exempt entity bears none on its exempt income. The suggestion is `0`: a provision of services is not in that list. - **Non-resident entity** (`N`): `0`, `19` and `24`, the Non-Residents Income Tax withholding (Royal Legislative Decree 5/2004, arts. 25.1 a) and 31): 24 %, 19 % if it resides in the European Union or the European Economic Area, 0 if the income is exempt or a tax treaty says so. It depends on facts the NIF does not show: no suggestion. - **State, Autonomous Community or local entity** (`S`, `P`): fully exempt, its income bears no withholding (Law 27/2014, art. 9.1; Royal Decree 634/2015, art. 61): only `0`. - **Individual, or entity whose income is attributed to its members** (`E`): every rate of the IRPF regulation, including the Ceuta and Melilla reduced rates (6, 2.8, 7.6), but not the Corporate Income Tax 9.5. Which one applies depends on the activity and its years, which the NIF does not show, so there is no suggestion. - **Any other NIF** (`H`, `J`, `V`): not restricted, no suggestion.
      - `allowed_irpf_rates` IrpfPercentage[], required: The rates this company can use, in ascending order.
      - `suggested_irpf_rate` number, nullable, required: One of `allowed_irpf_rates`. The rate to preselect for this company, or `null` when it depends on facts the NIF does not show and the user has to choose.
  - `meta` ResponseMeta
    - `timestamp` string, date-time
    - `request_id` string

## Other responses

- `400`: The request target could not be read as declared, so nothing was looked up. Three causes, all named in `error.details`: a path or query parameter whose value does not parse as its type (`VALIDATION_ERROR` — a UUID that is not a UUID, an unknown enum value, an empty element in a list such as `status=ISSUED,`), a required parameter that was not sent (`MISSING_PARAMETER`), or a header that is meant to carry an identifier and does not (`ACTIVE_COMPANY_HEADER_INVALID`). A list parameter sent entirely empty (`status=`) is not an error: it is the same as omitting it. The fault is in the target, not in the content — which is what `422` is defined over.
- `401`: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those.
- `403`: Your account does not own or manage this company, or does not hold the required access over it. A NIF that does not exist answers the same way. That case answers `error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`.
- `429`: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because too many went out to that recipient in a short time. Either way, retry after the `Retry-After` seconds. `QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan for the current period (issued invoices, for instance). Retrying does not help until the quota resets or the plan changes. `error.details` carries `feature_code`, `current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until the reset when it is known.
- `500`: Internal server error
- `default`: Any status code the operation does not list above. Every operation declares it, so a generated client always has a branch to fall into and never loses the cause of a failure it did not anticipate. This is where the transport-level answers land — `405`, `406`, `415` and `429` — together with any status a future version of the API starts returning. All of them carry the same error envelope as the codes listed explicitly, so `error.code` is what tells them apart: switching on the status code alone is not enough. See «Transport-level errors» in the API description for when each one is produced. A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active subscription. `error.details` says why and what to do: `current_status` (absent if it never had one), `required_permission` and `action`. A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a dependency of BeeL itself (the database, the email provider) was momentarily unavailable and nothing was done. Retry after those seconds. A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the operation depends on failed or did not answer in time. It is a transient condition — retry with the same `Idempotency-Key` where the operation accepts one. One exception to the envelope: a failure of the network edge that never reaches the application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not BeeL's — it may not even be JSON. Treat those as "no answer", and retry.

---

[API](https://skmtc.dev/beel/apis/beel-public-api.md) · [All operations](https://skmtc.dev/beel/apis/beel-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beel/apis/beel-public-api/revisions/ffbc0ae31f79?raw)