Properties
| Name | Type | Description |
|---|---|---|
| success | boolean | |
| data | object | |
| meta | object |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-company-response-schema.json",
"title": "CompanyResponse",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/beel-es-company-api-openapi.yml#/components/schemas/CompanyResponse",
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"$ref": "#/$defs/CompanyData"
},
"meta": {
"$ref": "#/$defs/ResponseMeta"
}
},
"$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"
]
},
"AccountState": {
"type": "string",
"description": "Account lifecycle stage, expressed in the same Test/Live vocabulary as `Environment`.\n`TEST_ONLY` means Live has not been activated for the account (no billing set up), so\nemission to the real AEAT is blocked; `PROD_ACTIVE` means it has.\n",
"enum": [
"TEST_ONLY",
"PROD_ACTIVE"
]
},
"AddressResponse": {
"type": "object",
"description": "An address as stored. Nothing is guaranteed: the address of a company created by signup\nis empty until onboarding fills it in, so every field may be absent. `Address` (the\nrequest shape) does require them — that is a rule of admission, not a fact about what\nis stored.\n",
"properties": {
"street": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Full address (street, number, floor, etc.)"
},
"number": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"description": "Street number. Absent when the stored address has none."
},
"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,
"description": "City or town"
},
"province": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Province or state. Outside Spain an address may have none."
},
"country": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Country name: the Spanish name derived from `country_code`. Addresses stored before\nthe country was validated may hold the name as it was sent.\n"
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"minLength": 2,
"maxLength": 2,
"description": "ISO 3166-1 alpha-2 country code"
}
}
},
"CompanyData": {
"type": "object",
"description": "A company owned by the account.\n\nIts status is described by **two independent axes** — do not conflate them:\n\n* **Mode activation** (`in_test` / `in_prod`) — which modes this NIF is\n activated in, matching the dashboard's Test/Live switch. A company is a\n single env-agnostic record — there is no Test copy and no Live copy of it;\n what is per-mode is the *activation*, and a NIF can be activated in Test, in\n Live, in both, or in neither. It decides where invoices and quota are\n accounted, NOT whether they reach AEAT.\n* **AEAT emission capability** (`account_state`, `verifactu_status`, and the\n `readiness` block requested with `?include=readiness`) — whether invoices are\n submitted to AEAT with a signed VeriFactu representation.\n\nA company can bill in the **Live** mode and still have AEAT emission disabled\n(e.g. before the VeriFactu representation is signed). `TEST_ONLY` /\n`in_prod=false` therefore do **not** mean \"this account cannot invoice\".\n\n**Every field `PATCH /v1/companies/{company_id}` accepts is read back here** — same\nnames, same types as `UpdateCompanyRequest`. A field with no value is absent, which\nmeans \"nothing stored\", never \"hidden from you\": the field set does not depend on who\nasks (owner, member with `VIEW`, API key or the managed twin\n`GET /v1/accounts/{account_id}/companies` all see the same one).\n",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Unique company identifier."
},
"access_level": {
"allOf": [
{
"$ref": "#/$defs/AccessLevel"
}
],
"description": "How much access the signed-in person has to this company, so a dashboard can label it (\"read only\") and hide write actions instead of discovering the answer through a `403`. Read-only and derived from who is asking — never sent.\n**Only present when authenticating with a user session.** With an API key the field is absent: what a key may do is set by its own scopes, which are per resource (`invoices:write`, `customers:read`, …) and cannot be reduced to one of three levels. Absent therefore means \"does not apply here\", never \"no access\"."
},
"nif": {
"type": "string",
"description": "Spanish Tax ID (NIF/CIF). Immutable once set."
},
"legal_name": {
"type": "string",
"description": "Legal/fiscal name of the company. Immutable once set.\n\nIt is the name that was sent when the NIF was registered, not one AEAT\nconfirmed: for a legal entity the census identifies the CIF and the name is\n**not verified**. Validate a NIF (`POST /v1/nif/validate`) to read the\nbusiness name the census actually holds.\n"
},
"trade_name": {
"type": "string",
"description": "Commercial/trade name shown in the UI and on invoices. Editable. Never empty: when no trade name has been set, it carries `legal_name`, so `trade_name == legal_name` means \"no trade name of its own\", not that one was written."
},
"entity_type": {
"allOf": [
{
"$ref": "#/$defs/EntityType"
}
],
"description": "Self-employed individual or legal entity. Immutable once set."
},
"is_primary": {
"type": "boolean",
"description": "True for the account's primary company (the owner's own NIF)."
},
"verifactu_status": {
"type": "string",
"enum": [
"NOT_CONFIGURED",
"PENDING",
"ACTIVE",
"ERROR"
],
"description": "State of the AEAT representation of this NIF, which Live submission to VeriFactu\nrequires. Part of the AEAT-emission axis — independent of `environment`.\n\n- `NOT_CONFIGURED`: no representation document, or the last one was cancelled.\n- `PENDING`: the document is generated and waits to be signed and submitted.\n- `ACTIVE`: the signed representation is in force.\n- `ERROR`: reserved; not currently returned.\n"
},
"environment": {
"allOf": [
{
"$ref": "#/$defs/Environment"
}
],
"deprecated": true,
"description": "**Deprecated** — use `in_test` / `in_prod` instead.\n\nA company is a single env-agnostic record; what is per-mode is its\n*activation*, and a company can be activated in Test, in Live, in both, or\nin neither. This single scalar cannot express that: it collapses the pair to\none value, so it misreports any company activated in both modes. It is kept\nfor backwards compatibility and will be removed in a future version.\n\n**How the collapse is decided** — the same rule wherever this field appears\n(the single company, the account's list of companies, any of their aliases):\nthe environment of the credential you are calling with, *if* the company is\nactivated there; otherwise the environment it is really activated in. A\ncompany activated only in Test therefore reads `TEST` even to a live key: the\nscalar is never re-labelled to the environment you are looking from.\n\nThis is the data/billing axis, NOT a measure of AEAT capability.\n"
},
"in_prod": {
"type": "boolean",
"description": "Whether this company is **activated in Live** (production), regardless\nof whether the AEAT representation is already signed. Derived from the real\nactivation fact — NOT from the stamped `environment` scalar — so it stays true\neven for a NIF registered in production but not yet signed. Drives the UI's\n\"already in production\" state (no spurious \"add NIF\" prompt when the\naccount switches to Live).\n"
},
"in_test": {
"type": "boolean",
"description": "Whether this company is **activated in Test** (sandbox). Symmetric to\n`in_prod` and derived from the same activation fact: activation is independent\nper mode, so a company may be activated in Test only, in Live only, in both, or\nin neither. A company that is not activated in the mode you are working in is\nshown *switched off* in the dashboard (visible and labelled, but not selectable)\nrather than hidden.\n"
},
"aeat_environment": {
"allOf": [
{
"$ref": "#/$defs/Environment"
}
],
"deprecated": true,
"description": "**Deprecated** — use the activation pair `in_test` / `in_prod`, together with\n`verifactu_status`, instead.\n\nAEAT/VeriFactu environment this NIF is registered against. It is derived, never\nstored: a single scalar cannot express a NIF activated in both modes, nor one\nactivated in neither. It is `null` whenever no registration can be asserted —\nno mode activated, or `verifactu_status: NOT_CONFIGURED` — and it is kept for\nbackwards compatibility only.\n"
},
"account_state": {
"allOf": [
{
"$ref": "#/$defs/AccountState"
}
],
"description": "Account-level lifecycle, identical for every company of the account. AEAT emission in\nLive additionally requires the per-NIF representation to be signed.\n"
},
"address": {
"type": [
"object",
"null"
],
"description": "Fiscal address of the company, as set via `POST /v1/accounts/{account_id}/companies` and\n`PATCH /v1/accounts/{account_id}/companies/{company_id}`. All fields are optional — a company\nmay have a partial address — and the object is `null` when no address\nhas been set.\n",
"properties": {
"street": {
"type": "string",
"description": "Street of the fiscal address."
},
"number": {
"type": "string",
"description": "Street number."
},
"floor": {
"type": "string",
"description": "Floor or level."
},
"door": {
"type": "string",
"description": "Door or apartment."
},
"postal_code": {
"type": "string",
"description": "Postal code."
},
"city": {
"type": "string",
"description": "City or town."
},
"province": {
"type": "string",
"description": "Province."
},
"country": {
"type": "string",
"description": "Country name."
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code."
}
}
},
"legal_form": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 100,
"description": "Legal form (SL, SA, ...). Only for `entity_type: LEGAL_ENTITY`, immutable once set.\nThe field `UpdateCompanyRequest.legal_form` writes.\n"
},
"legal_representative": {
"allOf": [
{
"$ref": "#/$defs/LegalRepresentativeResponse"
}
],
"description": "Legal representative of the company, as stored — the field\n`UpdateCompanyRequest.legal_representative` writes. Only for\n`entity_type: LEGAL_ENTITY`; absent when none is recorded.\n"
},
"phone": {
"allOf": [
{
"$ref": "#/$defs/Phone"
}
],
"description": "Contact phone. The field `UpdateCompanyRequest.phone` writes."
},
"email": {
"allOf": [
{
"$ref": "#/$defs/Email"
}
],
"description": "Contact email. The field `UpdateCompanyRequest.email` writes."
},
"website": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 500,
"description": "Website. The field `UpdateCompanyRequest.website` writes."
},
"logo_url": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 500,
"description": "Public URL of the logo printed on the invoice. The field `UpdateCompanyRequest.logo_url`\nwrites. Also returned by `GET /v1/companies/{company_id}/invoice-customization` and as\n`issuer.logo_url` of an invoice, always as the same absolute, fetchable URL.\n"
},
"additional_info": {
"type": [
"string",
"null"
],
"maxLength": 500,
"description": "Free note printed on the invoice — the field\n`UpdateCompanyRequest.additional_info` writes.\n"
},
"default_iban": {
"allOf": [
{
"$ref": "#/$defs/IBAN"
}
],
"description": "Default IBAN shown on the invoice. The field `UpdateCompanyRequest.default_iban`\nwrites.\n"
},
"default_swift": {
"allOf": [
{
"$ref": "#/$defs/SWIFT"
}
],
"description": "Default SWIFT/BIC. The field `UpdateCompanyRequest.default_swift` writes.\n"
},
"account_holder": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 255,
"description": "Bank account holder. The field `UpdateCompanyRequest.account_holder` writes.\n"
},
"iae": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 20,
"description": "IAE code. The field `UpdateCompanyRequest.iae` writes."
},
"activity_start_date": {
"type": [
"string",
"null"
],
"format": "date",
"description": "Activity start date. The field `UpdateCompanyRequest.activity_start_date` writes.\n"
},
"default_payment_term": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 365,
"description": "Default payment term in days. The field\n`UpdateCompanyRequest.default_payment_term` writes.\n"
},
"invoice_template_type": {
"allOf": [
{
"$ref": "#/$defs/InvoiceTemplateType"
}
],
"description": "Invoice PDF template type. The field\n`UpdateCompanyRequest.invoice_template_type` writes. Also returned by\n`GET /v1/companies/{company_id}/invoice-customization`.\n"
},
"invoice_accent_color": {
"type": [
"string",
"null"
],
"pattern": "^#[0-9A-Fa-f]{6}$",
"description": "Invoice PDF accent color (`#RRGGBB`). The field\n`UpdateCompanyRequest.invoice_accent_color` writes. Also returned by\n`GET /v1/companies/{company_id}/invoice-customization`.\n"
},
"invoice_language": {
"allOf": [
{
"$ref": "#/$defs/Language"
}
],
"description": "Language used to render invoice PDFs. The field\n`UpdateCompanyRequest.invoice_language` writes. Also returned by\n`GET /v1/companies/{company_id}/invoice-customization`.\n"
},
"email_language": {
"allOf": [
{
"$ref": "#/$defs/Language"
}
],
"description": "Language used for emails. The field `UpdateCompanyRequest.email_language`\nwrites. Also returned by `GET /v1/companies/{company_id}/invoice-customization`.\n"
},
"default_irpf_rate": {
"type": [
"number",
"null"
],
"description": "Default IRPF withholding rate applied to this company's invoices — the same number\n`POST /v1/accounts/{account_id}/companies` accepts and\n`GET`/`PUT /v1/companies/{company_id}/tax-configuration` manages, read back\nwhere you wrote it.\n\n**Absent means no rate was ever declared**, which is not the same as `0`. A company\ncreated without `default_irpf_rate` withholds nothing *because nobody said what to\nwithhold*; a company with `0` withholds nothing *because its owner declared so*. Both\ninvoice the same, only one is a declaration — so do not fill the absent case in with a\nzero. Exemption is a declaration too and reads as `0`.\n\nRead-only here. Change it with `PUT /v1/companies/{company_id}/tax-configuration`;\nthis resource does not accept it on `PATCH`.\n\nAbsent from the `201` of `POST /v1/accounts/{account_id}/companies` (that response describes the company just\ncreated, not its resolved tax configuration) — read it back with `GET`.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the company was created (ISO 8601)."
},
"readiness": {
"allOf": [
{
"$ref": "#/$defs/IssuingReadinessData"
}
],
"description": "Issuing-readiness status of this company. Present ONLY when the request\nasks for it via `?include=readiness`; otherwise omitted/null. Same shape as\n`GET /v1/companies/{company_id}/issuing-readiness`.\n"
}
}
},
"Email": {
"type": "string",
"format": "email",
"minLength": 5,
"maxLength": 255,
"description": "Email address (minimum valid email is 5 chars, e.g. a@b.co)"
},
"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"
]
},
"Environment": {
"type": "string",
"description": "Mode a record lives in — its Test/Live twin. It decides where invoices, customers and\nquota are accounted.\n\nFor a company it also decides which AEAT its NIF is registered against: switching a\ncompany on in `PROD` is what registers it with the real AEAT, so `aeat_environment`\nis that same mode and uses this same enum.\n",
"enum": [
"TEST",
"PROD"
]
},
"IBAN": {
"type": "string",
"pattern": "^[A-Z]{2}\\d{2}[A-Z0-9]{1,30}$",
"minLength": 15,
"maxLength": 34,
"description": "IBAN (International Bank Account Number).\nRequired when payment method is BANK_TRANSFER.\n"
},
"InvoiceTemplateType": {
"type": "string",
"description": "Invoice PDF template. `MODERN_TABLE` is a structured table layout for\nproduct/service lines; `PROFESSIONAL_SERVICE` is a text-based layout.\n",
"enum": [
"MODERN_TABLE",
"PROFESSIONAL_SERVICE"
]
},
"IssuingReadinessData": {
"type": "object",
"description": "Issuing-readiness of a company: whether it can issue its STANDARD invoice\nright now, in this environment, and — if not — exactly what is missing. `ready`\nis true only when `blockers` is empty. Issuing any fiscal document requires the\ncompany to be activated in that environment (`COMPANY_NOT_ACTIVATED` otherwise),\nwhether or not it goes to VeriFactu. The VeriFactu capability chain (census,\nsignature) is only demanded on top of that when the company is under the VeriFactu\nregime in this environment — the same fact that decides, at issue time, whether its\ninvoices are registered. With VeriFactu off, a NIF, a default series and a live\nactivation are enough to be ready.\n",
"properties": {
"ready": {
"type": "boolean",
"description": "true if the company can issue invoices (no blockers)."
},
"blockers": {
"type": "array",
"description": "Reasons the company cannot issue yet (empty when ready). Each one names what is\nmissing and how to clear it:\n\n- `COMPANY_HAS_NO_NIF`: the company has no NIF. Set `nif` with\n `PATCH /v1/companies/{company_id}`; once set it cannot be changed.\n- `SERIES_DEFAULT_NOT_FOUND`: there is no default `STANDARD` invoice series in this\n environment. The `SIMPLIFIED` and `CORRECTIVE` ones are created on first use.\n `PUT /v1/companies/{company_id}/series/defaults` creates the missing ones, or mark an\n existing series with `PUT /v1/companies/{company_id}/series/{series_id}/default`.\n- `PROFILE_INCOMPLETE`: the fiscal identity is not complete enough to write an invoice\n header: entity type, legal name or full fiscal address is missing. Complete\n `entity_type`, `legal_name` and `address` with `PATCH /v1/companies/{company_id}`. A\n missing NIF is reported as `COMPANY_HAS_NO_NIF` instead, never as both.\n- `COMPANY_NOT_ACTIVATED`: the company is not activated in the environment of the\n request, and it is not under the VeriFactu regime. Activate it with\n `POST /v1/companies/{company_id}/activations` for that environment.\n- `ENV_MISMATCH`: the same missing activation, for a company under the VeriFactu\n regime. Activate it as above, or call with a credential of the environment where it\n is already activated. The first stage of the VeriFactu chain.\n- `NIF_NOT_REGISTERED`: the NIF is not registered for VeriFactu submission in this\n environment. Turning VeriFactu on\n (`PUT /v1/companies/{company_id}/verifactu-configuration` with `enabled: true`)\n registers it; in Live that call needs the signed representation first. Never reported\n in Test, where the NIF is registered with its first submission.\n- `NIF_REPRESENTATION_REQUIRED`: the NIF is registered, but there is no signed AEAT\n representation in force. Generate it with\n `POST /v1/companies/{company_id}/representation`, sign it digitally and send it with\n `POST /v1/companies/{company_id}/representation/submit`. Live only.\n",
"items": {
"type": "string",
"enum": [
"COMPANY_HAS_NO_NIF",
"SERIES_DEFAULT_NOT_FOUND",
"PROFILE_INCOMPLETE",
"COMPANY_NOT_ACTIVATED",
"ENV_MISMATCH",
"NIF_NOT_REGISTERED",
"NIF_REPRESENTATION_REQUIRED"
]
}
},
"verifactu": {
"type": "object",
"description": "The compliance question, separate from the operational `ready` above: would\nthis NIF pass a VeriFactu emission right now? Relevant before putting the company\nunder the VeriFactu regime. For a company already under the regime,\n`verifactu.ready` coincides with `ready` (same evaluation).\n",
"properties": {
"ready": {
"type": "boolean",
"description": "true only when the company is operationally `ready` AND its VeriFactu\ncapability chain is clean. An operational blocker (missing NIF, default\nseries, or an incomplete fiscal identity) makes this false even if the\nchain itself is complete — and, since those are not chain stages, it does\nso with an EMPTY `blockers` list here. The reason is in the top-level\n`blockers`, which is where operational blockers are reported.\n"
},
"blockers": {
"type": "array",
"description": "ONLY the incremental VeriFactu capability stages, in order and mutually\nexclusive — one reason at a time, without repeating the operational\nblockers (NIF/series/fiscal identity) listed above. The stages, and how to\nclear each one, are the same as in the top-level `blockers`:\n\n- `ENV_MISMATCH`: the company is not activated in the environment of the request.\n- `NIF_NOT_REGISTERED`: the NIF is not registered for VeriFactu submission in\n this environment; turning VeriFactu on registers it.\n- `NIF_REPRESENTATION_REQUIRED`: no signed AEAT representation in force. Only\n appears where a signed representation is actually demanded (Live).\n",
"items": {
"type": "string",
"enum": [
"ENV_MISMATCH",
"NIF_NOT_REGISTERED",
"NIF_REPRESENTATION_REQUIRED"
]
}
}
}
}
}
},
"Language": {
"type": "string",
"description": "Supported languages: `es` Spanish, `en` English, `ca` Catalan.\n",
"enum": [
"es",
"en",
"ca"
]
},
"LegalRepresentativeResponse": {
"type": "object",
"required": [
"full_name",
"nif",
"address"
],
"description": "Legal representative of a legal entity, as stored.\nOnly present 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",
"minLength": 9,
"maxLength": 9,
"description": "Tax ID of the legal representative (DNI/CIF/NIE)"
},
"address": {
"allOf": [
{
"$ref": "#/$defs/AddressResponse"
},
{
"description": "Address of the legal representative"
}
]
}
}
},
"Phone": {
"type": "string",
"maxLength": 20,
"description": "A phone number, as the record holds it: digits, spaces, dashes, parentheses and an\noptional leading `+`, up to 20 characters.\n\nThis is the schema a **response** carries, and the length above is the only rule it\nstates. It deliberately does not repeat the character rule, because a number can reach a\nrecord through a path that predates that rule or never passed through this API at all —\na payment provider's customer data, a bulk import. Read the field defensively and do not\nassume it parses.\n\nWhat a **request** has to satisfy is `PhoneInput`, which adds the rules this API enforces\non the way in.\n"
},
"ResponseMeta": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time"
},
"request_id": {
"type": "string"
}
}
},
"SWIFT": {
"type": "string",
"pattern": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$",
"minLength": 8,
"maxLength": 11,
"description": "SWIFT/BIC code"
}
}
}
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.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/beel-es-company-response"
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.