beel-es · Schema

AccountImportResult

The outcome of the file, row by row, in one shape for the preview and for the import. Which one produced it is `metadata.is_dry_run`; what it actually wrote is the write counters in `statistics`.

InvoicingSpainFintechSoftware-as-a-Service

Properties

Name Type Description
metadata object
accounts_validation array One entry per data row of the accounts file, in file order and **never filtered**: a row that failed keeps its place and its `row_number`, so the answer lines up with the spreadsheet.
customers_source object The optional customers file, checked **once** for the whole import. Absent when none was sent. What each account did with it is on its own row.
own_company_customers object What the shared customers file did on **your own** company, when `options.apply_customers_to_own_company` asked for it. Absent otherwise. It sits at this level and not among the rows because your comp
statistics object
View JSON Schema on GitHub

JSON Schema

beel-es-account-import-result-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-account-import-result-schema.json",
  "title": "AccountImportResult",
  "description": "The outcome of the file, row by row, in one shape for the preview and for the import. Which one produced it is `metadata.is_dry_run`; what it actually wrote is the write counters in `statistics`.",
  "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/AccountImportResult",
  "type": "object",
  "required": [
    "metadata",
    "accounts_validation",
    "statistics"
  ],
  "properties": {
    "metadata": {
      "$ref": "#/$defs/AccountImportMetadata"
    },
    "accounts_validation": {
      "type": "array",
      "description": "One entry per data row of the accounts file, in file order and **never filtered**: a row that failed keeps its place and its `row_number`, so the answer lines up with the spreadsheet.",
      "items": {
        "$ref": "#/$defs/AccountImportItem"
      }
    },
    "customers_source": {
      "allOf": [
        {
          "$ref": "#/$defs/AccountImportCustomersSource"
        }
      ],
      "description": "The optional customers file, checked **once** for the whole import. Absent when none was sent. What each account did with it is on its own row."
    },
    "own_company_customers": {
      "allOf": [
        {
          "$ref": "#/$defs/AccountImportCustomersOutcome"
        }
      ],
      "description": "What the shared customers file did on **your own** company, when `options.apply_customers_to_own_company` asked for it. Absent otherwise. It sits at this level and not among the rows because your company is not a row of the accounts file: it is not provisioned, not activated and not given series — only its customers are seeded.\n\nSame shape as the per-account outcome, with one difference that `metadata.is_dry_run` settles: in a preview `created` is what **would** be created, since nothing was written; in an import it is what reached the database. `already_existed` is what the company already knew either way — which is what makes re-uploading the file cheap here too.\n\n**It is deliberately not added to `statistics.customers_created`.** That counter is about the accounts you imported, and folding your own copy into it would inflate the number you reconcile your onboarding against.\n\nYour own company also **fails like a row**: if seeding it fails, the managed accounts already seeded stay exactly as they are and the failure is reported here, with its rows counted in `failed`."
    },
    "statistics": {
      "$ref": "#/$defs/AccountImportStatistics"
    }
  },
  "$defs": {
    "AccountImportCustomerRow": {
      "type": "object",
      "required": [
        "row_number",
        "errors"
      ],
      "properties": {
        "row_number": {
          "type": "integer",
          "description": "Row as the spreadsheet counts it (header is row 1)."
        },
        "nif": {
          "type": [
            "string",
            "null"
          ]
        },
        "legal_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "errors": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AccountImportIssue"
          }
        }
      }
    },
    "AccountImportCustomersOutcome": {
      "type": "object",
      "description": "What the shared customers file did on one account. `already_existed` is the number that makes re-uploading cheap: a customer whose tax id the account already knows is counted, not duplicated.",
      "required": [
        "created",
        "already_existed",
        "failed"
      ],
      "properties": {
        "created": {
          "type": "integer"
        },
        "already_existed": {
          "type": "integer"
        },
        "failed": {
          "type": "integer"
        }
      }
    },
    "AccountImportCustomersSource": {
      "type": "object",
      "description": "The shared customers file, checked once for the whole import — it is the same list for every account, so validating it per account would repeat the same census lookups N times over.\n\nDeliberately **not** the shape of `POST /v1/companies/{company_id}/customers/imports/preview`: that one reports duplicates against one company's customers, and here there is no single company to be duplicate of. What is reported here is only what makes a customer unusable everywhere — bad data, or a tax id the AEAT does not know.",
      "required": [
        "total_rows",
        "valid",
        "invalid",
        "rejected"
      ],
      "properties": {
        "total_rows": {
          "type": "integer"
        },
        "valid": {
          "type": "integer",
          "description": "Customers that will be applied to every account."
        },
        "invalid": {
          "type": "integer",
          "description": "Customers that will be applied to none."
        },
        "rejected": {
          "type": "array",
          "description": "The rejected rows, so you can fix the file. Valid rows are counted, not listed.",
          "items": {
            "$ref": "#/$defs/AccountImportCustomerRow"
          }
        }
      }
    },
    "AccountImportIssue": {
      "type": "object",
      "description": "One thing that happened to a row, with a stable `code` to branch on and a `message` already written in the language of the request. Branch on the code; the message is for people.",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "$ref": "#/$defs/AccountImportIssueCode"
        },
        "column": {
          "type": [
            "string",
            "null"
          ],
          "description": "Column of the file involved; `null` when the issue is about the row as a whole."
        },
        "value": {
          "type": [
            "string",
            "null"
          ],
          "description": "The offending value, already normalised."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation, in the language of the request. Issues coming from the customers file are the exception: they carry the wording the customer import itself produced, which is Spanish — the same text `POST /v1/companies/{company_id}/customers/imports/preview` returns. Re-labelling them to translate would collapse every error of a row into one repeated sentence, which is worse than one untranslated one."
        }
      }
    },
    "AccountImportIssueCode": {
      "type": "string",
      "description": "Machine-readable reason for an issue. New values are added as the import learns to explain\nmore; treat an unknown one as a generic problem rather than failing.\n\nRead straight off the row: `REQUIRED_FIELD_MISSING` (the column is there and its **cell** is\nempty — a missing column is a whole-file error, not a row one), `EXTERNAL_REF_DUPLICATED`,\n`ENTITY_TYPE_UNKNOWN`, `NIF_INVALID_FORMAT`, `EMAIL_INVALID`, `POSTAL_CODE_INVALID`,\n`IBAN_INVALID`, `IRPF_NOT_NUMERIC`, `LANGUAGE_UNSUPPORTED`.\n\n`IRPF_NOT_ALLOWED` — the rate is a number but not one of `IrpfPercentage`, or not one the\nrow's NIF can bear: the same check as its invoices (see `WithholdingOptions`), so a\ncompany (`B…`) declaring 15 % is rejected here. It is an **error**, not a warning: letting it through buys a green preview and an\naccount that fails on its first invoice months later, when nobody connects the two.\n\n`POSTAL_CODE_PADDED` — a warning: the postal code was padded with leading zeros, which is\nalmost always the right repair but does change the value, and the first digit picks the\nprovince.\n\nCensus: `NIF_NOT_IN_CENSUS` — the tax id is not in the AEAT register or is no longer active.\nFor an **individual** it also covers a legal name that does not match the one on file; for a\n**legal entity** the name is not checked at all, because the AEAT identifies a company by its\nCIF alone and has no answer that means \"this name is not the one\".\n\nState of the account rather than of the file, and the ones that produce `BLOCKED`:\n`ACCOUNT_ALREADY_EXISTS` (a warning, not a blocker), `ACCESS_LEVEL_INSUFFICIENT`,\n`LIVE_ACTIVATION_NOT_ENTITLED`, `NIF_ALREADY_LIVE_ELSEWHERE`, `NIF_LIMIT_REACHED`,\n`PROVISIONING_EMAIL_ALREADY_REGISTERED`, `PROVISIONING_ACCOUNT_CLAIMED` — each the wire code\nthe equivalent single-account call answers with, so the remedy is the one already documented\nthere.\n\n`NIF_LIMIT_REACHED` — switching this row on in Live would exceed the \"up to N NIFs\" cap of\nyour agreement. The cap is cumulative across the file: rows are counted in order, and only\nrows that would be switched on in Live take a place, so a row whose NIF already invoices in\nLive, or that is blocked for another reason, never does. In the preview, and when the\nimport already knew it before writing, `value` is the cap. If the cap fills up while the\nimport is running (another activation took the last place between planning and writing),\n`value` carries the wire code `NIF_LIMIT_REACHED` instead.\n\nSeries: `SERIES_CODE_TAKEN`, `SERIES_MANUAL_RESOLUTION_REQUIRED` (the declared code and its\n`<code>2` fallback are both taken), `SERIES_CODE_DUPLICATED` (this same import declares the\ncode twice), `SERIES_FORMAT_INVALID` (the format, once `{REF}` is resolved, cannot number —\nno `{NUM}`, or the `external_ref` added characters the grammar rejects) and\n`SERIES_DEFAULT_REPLACED`. The first four leave the account **without** that series, and say\nso.\n\nCustomers file: `CUSTOMER_ROW_REJECTED` — a row of the shared customers file that will not\nload anywhere. One issue per offending column, each with the message the customer import\nwrote for it; a row rejected with no column-level detail carries a single one. The census\ncode above is used here too, but only ever on the `nif` column.\n\nAnything else: `UNEXPECTED_ROW_FAILURE`, with the detail in `value`.\n",
      "enum": [
        "REQUIRED_FIELD_MISSING",
        "EXTERNAL_REF_DUPLICATED",
        "ENTITY_TYPE_UNKNOWN",
        "NIF_INVALID_FORMAT",
        "NIF_NOT_IN_CENSUS",
        "EMAIL_INVALID",
        "POSTAL_CODE_INVALID",
        "POSTAL_CODE_PADDED",
        "IBAN_INVALID",
        "IRPF_NOT_NUMERIC",
        "IRPF_NOT_ALLOWED",
        "LANGUAGE_UNSUPPORTED",
        "ACCOUNT_ALREADY_EXISTS",
        "ACCESS_LEVEL_INSUFFICIENT",
        "LIVE_ACTIVATION_NOT_ENTITLED",
        "NIF_ALREADY_LIVE_ELSEWHERE",
        "NIF_LIMIT_REACHED",
        "PROVISIONING_EMAIL_ALREADY_REGISTERED",
        "PROVISIONING_ACCOUNT_CLAIMED",
        "SERIES_CODE_TAKEN",
        "SERIES_CODE_DUPLICATED",
        "SERIES_FORMAT_INVALID",
        "SERIES_MANUAL_RESOLUTION_REQUIRED",
        "SERIES_DEFAULT_REPLACED",
        "CUSTOMER_ROW_REJECTED",
        "UNEXPECTED_ROW_FAILURE"
      ]
    },
    "AccountImportItem": {
      "type": "object",
      "description": "One row of the accounts file and everything that happened to it.",
      "required": [
        "row_number",
        "status",
        "errors",
        "warnings",
        "series"
      ],
      "properties": {
        "row_number": {
          "type": "integer",
          "description": "Row number **as the spreadsheet counts it**: the header is row 1, so the first account is row 2. Not an index — the point is that you can open the file and go to that line."
        },
        "external_ref": {
          "type": [
            "string",
            "null"
          ],
          "description": "Your own id for the account; `null` when the row was too malformed to read it."
        },
        "nif": {
          "type": [
            "string",
            "null"
          ],
          "description": "The row's tax id, normalised; `null` when it could not be read."
        },
        "status": {
          "$ref": "#/$defs/AccountImportItemStatus"
        },
        "live_activation_verdict": {
          "allOf": [
            {
              "$ref": "#/$defs/LiveActivationVerdict"
            }
          ],
          "description": "Whether this row's NIF may be switched on in Live, decided exactly as `POST /v1/companies/{company_id}/activations` decides it. Anything other than `ENTITLED` blocks the row: the import never opens a checkout on your behalf. Absent when the row was rejected before reaching that question."
        },
        "account": {
          "allOf": [
            {
              "$ref": "#/$defs/ProvisionAccountResult"
            }
          ],
          "description": "The account this row produced — the same shape `POST /v1/accounts` returns, carrying `account_id`, `company_id` and the single-use `claim_token` / `claim_url` to hand to the holder. Absent in a preview (nothing was provisioned) and on a `BLOCKED` or `ERROR` row. On `ALREADY_EXISTS` it is the account that was already there, and a claim link still valid is kept: `claim_token` is `null` and `claim_link_already_issued` is `true`. **The token is shown once**: store it, or re-issue it with `POST /v1/accounts/{account_id}/claim-tokens`."
        },
        "series": {
          "type": "array",
          "description": "What each declared series did on this account. Empty when the import declares none.",
          "items": {
            "$ref": "#/$defs/AccountImportSeriesOutcome"
          }
        },
        "customers": {
          "allOf": [
            {
              "$ref": "#/$defs/AccountImportCustomersOutcome"
            }
          ],
          "description": "How the shared customers file landed on **this** account. Absent in a preview, and when no customers file was sent: whether a customer is new depends on the account, and that only shows up when the import runs."
        },
        "errors": {
          "type": "array",
          "description": "What stops this row. A row with errors is never executed.",
          "items": {
            "$ref": "#/$defs/AccountImportIssue"
          }
        },
        "warnings": {
          "type": "array",
          "description": "What you should know even though the row goes through.",
          "items": {
            "$ref": "#/$defs/AccountImportIssue"
          }
        }
      }
    },
    "AccountImportItemStatus": {
      "type": "string",
      "description": "Outcome of one row. The same five values are used by the preview and by the import — the\npreview reports what the import would reach — so no value tells you which operation\nproduced the payload; `metadata.is_dry_run` does.\n\n* `VALID` — complete and reachable. Provisioned by the import; would be by a preview.\n* `WARNING` — the same, with non-blocking warnings.\n* `ALREADY_EXISTS` — an account with this `external_ref` is already yours. A documented\n  success, not a collision: provisioning is idempotent by `external_ref`, so nothing is\n  created and nothing is billed again. On an import the row is still reconciled (Live,\n  series, customers), which is what makes re-uploading the same file useful.\n* `BLOCKED` — well formed but not executable. `errors` says why, and it is always something\n  to resolve outside the file.\n* `ERROR` — the row's own data is wrong. `errors` says which column.\n",
      "enum": [
        "VALID",
        "WARNING",
        "ALREADY_EXISTS",
        "BLOCKED",
        "ERROR"
      ]
    },
    "AccountImportMetadata": {
      "type": "object",
      "required": [
        "is_dry_run",
        "total_rows",
        "processing_time_ms",
        "environment"
      ],
      "properties": {
        "is_dry_run": {
          "type": "boolean",
          "description": "`true` for the preview (nothing was written), `false` for the import. It is what tells the two answers apart when they are stored side by side."
        },
        "total_rows": {
          "type": "integer",
          "description": "Data rows found in the accounts file, header excluded."
        },
        "processing_time_ms": {
          "type": "integer",
          "format": "int64"
        },
        "accounts_filename": {
          "type": [
            "string",
            "null"
          ],
          "description": "Name of the uploaded accounts file, as your client sent it."
        },
        "customers_filename": {
          "type": [
            "string",
            "null"
          ],
          "description": "Name of the uploaded customers file; `null` when none was sent."
        },
        "environment": {
          "allOf": [
            {
              "$ref": "#/$defs/Environment"
            }
          ],
          "description": "The mode this import ran in, taken from the credential. Restated because it decides whether the NIFs were switched on against the real AEAT and whether anything was billed."
        }
      }
    },
    "AccountImportSeriesAction": {
      "type": "string",
      "description": "* `ALREADY_EXISTS` — the account already numbers like this. Nothing was touched. A series\n  counts as present when it numbers identically, whether it is written with `{CODIGO}` or\n  with the code spelled out.\n* `CREATED` — the series was created (in a preview: would be).\n* `MANUAL_REVIEW_REQUIRED` — neither the declared code nor its `<code>2` fallback is free,\n  or the resolved format falls outside the series grammar. Inventing a third code would be\n  guessing, and changing the format of a series that has already numbered a document is not\n  something an import may do. Resolve it on the account and re-upload.\n",
      "enum": [
        "ALREADY_EXISTS",
        "CREATED",
        "MANUAL_REVIEW_REQUIRED"
      ]
    },
    "AccountImportSeriesOutcome": {
      "type": "object",
      "description": "What one declared series did on one account.",
      "required": [
        "document_type",
        "action"
      ],
      "properties": {
        "document_type": {
          "$ref": "#/$defs/DocumentType"
        },
        "action": {
          "$ref": "#/$defs/AccountImportSeriesAction"
        },
        "code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Code the series was created under — not necessarily the declared one, when that was already taken by a different numbering."
        },
        "format": {
          "type": [
            "string",
            "null"
          ],
          "description": "Format with `{REF}` already resolved to this row's `external_ref`."
        }
      }
    },
    "AccountImportStatistics": {
      "type": "object",
      "description": "Aggregated outcome. Every field except the write counters classifies rows of the accounts file: each row falls into exactly one of `valid`, `with_warnings`, `already_existed`, `blocked` and `with_errors`, so those five add up to `total_rows`.\n\nThe write counters — `accounts_created`, `live_activations_created`, `series_created`, `customers_created` — are the only fields that count writes, so they are what to read to know whether an import worked. They are all `0` in a preview.",
      "required": [
        "total_rows",
        "valid",
        "with_warnings",
        "already_existed",
        "blocked",
        "with_errors",
        "importable",
        "accounts_created",
        "live_activations_created",
        "live_activations_pending",
        "series_created"
      ],
      "properties": {
        "total_rows": {
          "type": "integer"
        },
        "valid": {
          "type": "integer"
        },
        "with_warnings": {
          "type": "integer"
        },
        "already_existed": {
          "type": "integer"
        },
        "blocked": {
          "type": "integer"
        },
        "with_errors": {
          "type": "integer"
        },
        "importable": {
          "type": "integer",
          "description": "`valid + with_warnings` — rows a real import would provision."
        },
        "accounts_created": {
          "type": "integer",
          "description": "Accounts actually provisioned by this request. Always `0` in a preview."
        },
        "live_activations_created": {
          "type": "integer",
          "description": "NIFs actually switched on by this request. In Live each one adds an item to your subscription, so this is what was billed. Always `0` in a preview."
        },
        "live_activations_pending": {
          "type": "integer",
          "description": "NIFs a real import **would** switch on. In a preview this is the billing forecast — read it before importing; in an import it is what is left, normally `0`."
        },
        "series_created": {
          "type": "integer"
        },
        "customers_created": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Customer rows created across all **managed accounts** of the file. `null` when no customers file was sent, and `0` in a preview. Your own company, when `options.apply_customers_to_own_company` asked for it, is counted apart in `own_company_customers` and never here."
        }
      }
    },
    "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"
    },
    "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"
      ]
    },
    "LiveActivationVerdict": {
      "type": "string",
      "description": "The server's complete answer to \"may THIS actor activate a NIF in Live on this account,\nand if not, why?\". Published so the UI never has to re-derive what the server will decide\nwhen the button is pressed — a screen that computes it on its own ends up disagreeing, and\nthe disagreement shows up as a green button that answers 403.\n\nThe first four values are predicated on the PAYING account (a managed account inherits its\nmanager's entitlement); the last two on the ACTOR and the account in focus.\n\n* `ENTITLED` — live plan/contract or card on file. Activation is immediate.\n* `CHECKOUT_REQUIRED` — no card yet: go through the checkout.\n* `PLAN_ACTIVATION_REQUIRED` — fixed-quota plan on trial: the act is ACTIVATING THE PLAN,\n  not the per-NIF checkout (that one charges for a NIF the quota already includes).\n* `PAYMENT_REQUIRED` — unpaid (payment retries exhausted): no new checkout, regularise the existing one.\n* `NOT_BILLING_SUBJECT` — the actor is not the billing subject. Informative, no action.\n* `BILLING_MANAGED_EXTERNALLY` — an agency handles the billing. Informative, no action.\n* `CONTACT_SALES` — API plan account with two or more active NIFs and no agreed price:\n  going Live (checkout or activation) needs a price agreed with sales first. The\n  activation answers `403 CONTACT_SALES_REQUIRED` with `details.reason =\n  LIVE_WITH_MULTIPLE_NIFS` and `details.salesUrl`.\n",
      "enum": [
        "ENTITLED",
        "CHECKOUT_REQUIRED",
        "PLAN_ACTIVATION_REQUIRED",
        "PAYMENT_REQUIRED",
        "NOT_BILLING_SUBJECT",
        "BILLING_MANAGED_EXTERNALLY",
        "CONTACT_SALES"
      ]
    },
    "ProvisionAccountResult": {
      "type": "object",
      "description": "Result of a successful account provision. `claim_token` is a single-use secret to deliver to the account holder so they can set their password and take ownership. It is returned only once; `null` if the account was already claimed, `null` when the account was provisioned without `email` (there is no holder to hand it to yet), and `null` when a repeated provision found a claim link still valid (`claim_link_already_issued: true`). `claim_url` is the ready-to-use claim link BeeL builds for the current environment; `status` disambiguates a `null` `claim_token` (already claimed) from an error.",
      "required": [
        "account_id",
        "status",
        "claim_link_already_issued"
      ],
      "properties": {
        "person_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "The account holder. `null` when the account was provisioned **without `email`**: it has no person yet, and gains one when a claim token is issued."
        },
        "account_id": {
          "type": "string",
          "format": "uuid"
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/$defs/ProvisioningStatus"
            }
          ],
          "description": "Lifecycle stage of the account right after this call. A newly provisioned account is `PROVISIONED` (not yet claimed). Combined with `claim_token`, it is self-explanatory: a `null` `claim_token` with `status: CLAIMED`/`ACTIVE` means the holder already took ownership (not an error)."
        },
        "claim_token": {
          "type": [
            "string",
            "null"
          ],
          "description": "Single-use claim token (shown once); `null` if the account is already claimed, or if a claim link issued earlier is still valid (see `claim_link_already_issued`)."
        },
        "claim_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "Ready-to-use claim link for the account holder, built by BeeL for the current environment (no need to assemble `/reclamar?token=` yourself). `null` when `claim_token` is `null`."
        },
        "claim_link_already_issued": {
          "type": "boolean",
          "description": "`true` when this call repeated the provision of an unclaimed account that already has a claim link still valid (pending and not expired). That link is **kept working**: nothing is issued or revoked, `claim_token` and `claim_url` come back `null`, and no email is re-sent even with `send_email: true` (there is no token in clear to send). The link you already handed out is the one the holder uses. To replace it on purpose, call `POST /v1/accounts/{account_id}/claim-tokens`, which revokes the previous one. `false` otherwise."
        },
        "company_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "The account's company id (a UUID) — send it in the `BeeL-Active-Company` header to operate on this account. Every account is born with one company: with a `tax_profile` it is ready to invoice; without one it has no NIF yet (the holder registers it on claim), and its issuing readiness reports `COMPANY_HAS_NO_NIF` until then. `null` only when resending an `external_ref` whose account now holds two or more companies."
        }
      }
    },
    "ProvisioningStatus": {
      "type": "string",
      "enum": [
        "PROVISIONED",
        "CLAIMED",
        "ACTIVE"
      ],
      "description": "Lifecycle stage of a provisioned account. The claim gates the stage: `PROVISIONED` (created, not yet claimed — the holder has not set a password / taken ownership, even if a NIF was seeded at provisioning or you invoice on their behalf with `OPERATE`); `CLAIMED` (the holder set their password and took ownership, no NIF yet); `ACTIVE` (claimed and has at least one NIF — can operate under their own ownership)."
    }
  }
}

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-account-import-result"
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.