Properties
| Name | Type | Description |
|---|---|---|
| accounts_file | string | CSV with one managed account per row, in the format of `GET /v1/templates/account-import`: UTF-8, header names matched case-insensitively, and `,`, `;` or tab accepted as separator. The header row doe |
| customers_file | string | Optional CSV of customers to apply to **every** account of this import, in the format of `GET /v1/templates/customer-import`. Idempotent by tax id. Its preamble is skipped the same way — it comes out |
| options | object |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-account-import-upload-schema.json",
"title": "AccountImportUpload",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/beel-es-accountimports-api-openapi.yml#/components/schemas/AccountImportUpload",
"type": "object",
"required": [
"accounts_file"
],
"properties": {
"accounts_file": {
"type": "string",
"format": "binary",
"description": "CSV with one managed account per row, in the format of `GET /v1/templates/account-import`: UTF-8, header names matched case-insensitively, and `,`, `;` or tab accepted as separator.\n\nThe header row does not have to be the first line. A spreadsheet almost never starts on it — there is a title, sometimes a blank line — and that preamble travels ahead of the data when the sheet is exported. Everything before the first line carrying the required columns is ignored, within the first 20 lines. Reported `row_number`s still count from the top of the file, so they match what you see when you open it."
},
"customers_file": {
"type": "string",
"format": "binary",
"description": "Optional CSV of customers to apply to **every** account of this import, in the format of `GET /v1/templates/customer-import`. Idempotent by tax id. Its preamble is skipped the same way — it comes out of the same spreadsheet."
},
"options": {
"$ref": "#/$defs/AccountImportOptions"
}
},
"$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"
]
},
"AccountImportOptions": {
"type": "object",
"description": "Settings that apply to **every row** of the file. They live here and not as columns because an agency onboards all of its managed accounts the same way: a column nobody varies is a column everybody mistypes.\n\nTravels as an `application/json` part named `options` inside the multipart body — send it with its own `Content-Type: application/json` (`-F 'options=…;type=application/json'` in curl). Omit the part entirely to take the defaults.",
"properties": {
"access_level": {
"allOf": [
{
"$ref": "#/$defs/AccessLevel"
}
],
"description": "The access you keep over every account of this file. Defaults to `OPERATE` — not to `NONE` as in `POST /v1/accounts`, and the difference is deliberate: a file-driven import is re-run to reconcile what is missing, and reconciling an account's series and customers is a write that `VIEW` cannot do. An account you already manage with less than this is reported `BLOCKED` and skipped: once its holder has claimed it, only they can raise your access again."
},
"series": {
"type": "array",
"maxItems": 8,
"description": "Invoice series every account must end up with, declared once. Each entry is a `CreateSeriesRequest` exactly as `POST /v1/companies/{company_id}/series` takes it, with one addition: the token `{REF}` in `name` and `format` is replaced with the row's `external_ref` **before** the series is created, which is how a single declaration numbers every account distinguishably. `{REF}` is vocabulary of this endpoint only — what reaches the series is a literal format, so nothing downstream has to learn a new variable. A row whose `external_ref` would produce a format outside the series grammar (uppercase letters, digits, `-`, `_`, `/`, `:`) is reported and its series left alone.\n\nLeave it out and each account keeps the default series its activation seeds.",
"items": {
"$ref": "#/$defs/CreateSeriesRequest"
}
},
"apply_customers_to_own_company": {
"type": "boolean",
"default": false,
"description": "Load the shared customers file into **your own** company too, not only into the managed accounts the file describes. Off by default: an import of accounts writes on the accounts it imports, and a file that quietly also wrote on your own customers would be a surprise nobody asked for.\n\n**Your own company is the one in focus for this request** — the same one every company-scoped write of the API uses, and never one this endpoint picks for you. With several NIFs and none in focus the whole import is refused with `403` `ACTIVE_COMPANY_REQUIRED`, decided **before the files are read**: no account is provisioned and nothing is billed. Sending the option without `customers_file` is a `422`, decided in the same place — there is nothing to apply.\n\nWith an API key it needs `customers:write` on top of the `accounts:write` the operation already requires. It writes customers; a key that may not write customers must not get to through an accounts import. A dashboard session is governed by the role's capabilities over the company in focus, as everywhere else.\n\nWhat it did comes back in `own_company_customers`, apart from the per-account counters."
}
}
},
"CounterReset": {
"type": "string",
"enum": [
"NEVER",
"ANNUAL",
"MONTHLY"
],
"description": "Counter reset policy:\n- NEVER: Counter never resets (continuous numbering)\n- ANNUAL: Counter resets yearly\n- MONTHLY: Counter resets monthly\n"
},
"CreateSeriesRequest": {
"type": "object",
"description": "Request to create an invoice series. `document_type` is required: a new series always has\na type, and `UNASSIGNED` is rejected with `422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`.\nCorrective invoices need a series of their own (`CORRECTIVE`).\n",
"required": [
"document_type",
"name",
"code",
"format"
],
"properties": {
"document_type": {
"$ref": "#/$defs/DocumentType"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Descriptive name of the series"
},
"code": {
"$ref": "#/$defs/SeriesCode"
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 1000,
"description": "Optional series description"
},
"format": {
"$ref": "#/$defs/SeriesFormat"
},
"counter_reset": {
"allOf": [
{
"$ref": "#/$defs/CounterReset"
}
],
"default": "ANNUAL",
"description": "When this series' counter resets. Defaults to `ANNUAL` when omitted — so a format\nwithout a year token must come with `counter_reset: NEVER`.\n"
},
"initial_number": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 999999,
"default": 1,
"description": "Initial number for this series counter.\nUseful when migrating from another system and wanting to continue existing numbering.\nFor example, if the last invoices were 2024-0150, you can set initial_number=151.\nDefault value is 1.\nIt applies only to the first period in which the series issues an invoice: with\n`counter_reset: ANNUAL` or `MONTHLY`, every later year or month starts at 1. With\n`NEVER` there is a single period, so numbering simply continues from it.\n"
},
"active": {
"type": "boolean",
"default": true,
"description": "Whether the series is active"
},
"default_series": {
"type": "boolean",
"default": false,
"description": "Whether this is the default series for its document_type.\n\n**Auto-promotion:** the domain guarantees that, while at least one\nseries exists for a given `(document_type, environment)`, exactly one\nof them is the default. So if you create the **first** series of a\n`document_type` (no default exists yet for that type and environment),\nit is marked as default **even if you send `false`** — the response\nwill then return `default_series: true`. Send `true` to also unmark\nthe current default of that type.\n"
}
}
},
"DocumentType": {
"type": "string",
"enum": [
"UNASSIGNED",
"STANDARD",
"SIMPLIFIED",
"CORRECTIVE",
"SIMPLIFIED_CORRECTIVE",
"PROFORMA"
],
"description": "Document type associated with a series. Values mirror `InvoiceType`,\nso the series a document needs is named exactly like the document:\n- UNASSIGNED: Legacy value of series created before types existed. A series numbers only\n documents of its own type, so an `UNASSIGNED` series numbers none\n (`422 SERIES_INCOMPATIBLE_DOC_TYPE`); give it a type to keep using it. No series can be\n created with it or moved to it (`422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`). The live\n ones were given the type they numbered most.\n- STANDARD: Standard invoice\n- SIMPLIFIED: Simplified invoice\n- CORRECTIVE: Corrects or cancels a previous standard invoice (R1–R4)\n- SIMPLIFIED_CORRECTIVE: Corrects a simplified invoice (R5). Spanish law requires R5 to be\n numbered apart from R1–R4, so they have a series type of their own\n- PROFORMA: Proforma (commercial document, non-fiscal numbering)\n"
},
"SeriesCode": {
"type": "string",
"pattern": "^[A-Z0-9\\-_]{1,50}$",
"minLength": 1,
"maxLength": 50,
"description": "Alphanumeric series code (used in {CODIGO} variable).\nAllows uppercase letters, numbers, hyphens and underscores.\n"
},
"SeriesFormat": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"pattern": "^[A-Z0-9\\-_/{}:]*$",
"description": "Format template with available variables (UPPERCASE ONLY):\n- {CODIGO}: Series code (e.g., \"FAC\")\n- {YYYY}: Year with 4 digits (e.g., \"2025\")\n- {YY}: Year with 2 digits (e.g., \"25\")\n- {MM}: Month with 2 digits (e.g., \"01\")\n- {NUM}: Sequential number without padding (e.g., \"1\")\n- {NUM:X}: Sequential number with padding (e.g., {NUM:4} → \"0001\")\n\n**REQUIRED**: Must contain at least {NUM} or {NUM:X}\n**IMPORTANT**: Only uppercase (rejects {yy}, {mm}, {codigo}, etc.)\n\nValid examples:\n- \"{CODIGO}-{YYYY}-{NUM:4}\" → \"FAC-2025-0001\"\n- \"{CODIGO}/{NUM:6}\" → \"FAC/000001\"\n- \"{YYYY}{MM}-{NUM:3}\" → \"202501-001\"\n\nThe generated number is the invoice number sent to the AEAT, which accepts at most 60\nprintable ASCII characters and none of `\"`, `'`, `<`, `>`, `=`. A format whose longest\npossible number breaks that rule is rejected with `422 SERIES_FORMAT_NUMBER_TOO_LONG` or\n`SERIES_FORMAT_INVALID_CHARACTERS`. The counter counts as at least 9 digits, with or without\npadding: `{NUM:X}` is a minimum width, not a maximum.\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.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/beel-es-account-import-upload"
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.