Bulk import of managed accounts

The bulk import loads many clients at once from a CSV file. Each row is one of two things, chosen by its mode column: a managed account, a separate account that you provision for a client, or an own tax ID, a tax ID that you add to your own account as an additional tax ID (the app shows it as "Tax ID in my account"). You first send the file to a preview, which classifies and prices every row without writing or charging anything, and then you send the same file to apply it. This guide is written for the account that provisions, the provider of managed accounts. It covers the three operations, the file and its columns, how the parser reads it, the limits, the row statuses, the preview and its cost, what a second import of the same file does, the customers you can load along with it, the apply and its idempotency, and what a test key does.

The import is declarative and not atomic: the file says what should exist, every row that can be applied is applied on its own, and a row that fails never undoes the others. It has no MCP tool and no option for document series, as the end of this guide explains.

The three operations

accounts:read and accounts:write are privileged scopes: * does not cover them, and only an account to which we granted the provider privilege can use them. Without the privilege, or when the person who issued the key is no longer an owner or admin of your account, the answer is 403 privileged_scope_required. The preview needs accounts:write too, although it writes nothing. None of the three routes has an {account} segment: the provider is always the account of the key and the environment is the one of the key, and neither goes in the request.

The usual order is: download the template, fill it in, send it to the preview, fix the rows that come out BLOCKED or ERROR and preview again, and then apply the same files.

The request

Preview and apply take the same multipart/form-data body.

Both files are CSV, preferably in UTF-8, separated by commas, semicolons or tabs, and up to 5 MB each. The parser is more tolerant than the template. To preview the file of the example below, send only the accounts file:

curl -X POST https://api.factuarea.com/v1/accounts/imports/preview \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -F "accounts_file=@accounts.csv"

Do not set Content-Type yourself: your HTTP client adds the multipart/form-data header with its boundary. To apply, send the same fields to POST /v1/accounts/imports with an Idempotency-Key.

Options

options goes as nested form fields (options[send_email]=true) or as one JSON field (options={"send_email":true}), which is how an OpenAPI client serializes an object in multipart/form-data. A boolean accepts true, false, 1, 0, on, off, yes and no. Any other key answers 422 invalid_param_value, so a misspelled option is never ignored in silence.

The accounts file

The accounts file has a header row and one row per managed account or per own tax ID, up to 100. A row carries one tax ID, and a tax ID appears once in the file.

The template

GET /v1/accounts/imports/template returns text/csv as an attachment named plantilla-importacion-cuentas.csv. It is the same for every provider and reads nothing from your account. The file is UTF-8 with a byte order mark (BOM), ; as the separator and CRLF line endings, which is what a spreadsheet in Spanish opens correctly. It holds the header row and one example row:

mode;external_ref;plan;tax_id;legal_name;address;postal_code;city;province;country_code;owner_email;display_name;language;access_level
# ejemplo: managed_account;CLIENTE-0001;empresario;B12345674;Cliente Ejemplo SL;Calle Mayor 1;28013;Madrid;Madrid;ES;titular@example.com;Cliente Ejemplo;es;operate

The first cell of the example row starts with # ejemplo, and the import always ignores a row that does. Without that marker it would be a valid managed_account row, so remove it only when you mean it. The set of columns is closed: a column that is not in the template makes every row ERROR in that column, and so does a column that appears twice.

Columns

mode, plan, access_level and language are read in lower case, and every value is trimmed. A cell you leave empty counts as absent. owner_email, language and access_level are checked for their form in every row, even when the mode does not use them.

How the parser reads the file

The parser reads what a spreadsheet exports, so it is more tolerant than the template. It decides the type of the file by its content and never by its name or extension.

What it does not read: a spreadsheet (.xlsx or .xls), a PDF, an image, an archive or any binary file is 422 import_file_invalid even when it is named .csv, and so is a file with no header row after the preamble, with an unbalanced double quote or with control characters. Save the sheet as CSV before you upload it.

Limits

Size and rows are checked before any row is read, so when one of them fails nothing is classified, written or charged. Rows are counted without the header, the blank lines and the example row. To load more than 100 clients, split the file and send the parts one after another: every part reconciles by external_ref, so you can send a part again.

Row statuses

The preview and the apply classify every row with the same rules and give it one of five statuses. Only the first three are applied.

The code of a WARNING says what did not change:

Rows are classified in the order of the file, so the valid rows before one use up the caps that it would need: a file with more new live accounts than your cap leaves the last ones BLOCKED. The code of a row is a reason of the import report and not always a code of the error catalog: the ones that have a page link to it.

Errors by column

A row that is wrong comes out ERROR with code null and an errors object. Its key is the column, or row for an error of the whole row, and its value is a message in Spanish. The object is always there, and it is {} when the row has nothing wrong. A row fails when:

• a required column is empty: mode, tax_id and legal_name, and external_ref and plan in a managed account;
• mode is not own_nif or managed_account;
• tax_id is not a valid NIF, CIF or NIE;
• plan is not emprendedor, empresario or integral (enterprise is BLOCKED, not an error), or an own_nif row carries one;
• language is not es, en or ca, access_level is not none, view or operate, or owner_email is not an email address;
• a text is longer than its maximum, or a legal_name or display_name of a managed account is shorter than 2 characters;
• external_ref or tax_id already appeared in an earlier row of the file: the error goes on the second row and the following ones;
• tax_id differs from the one of the managed account that the external_ref already names;
• a new live managed account has no owner_email;
• the header has a column that is not in the template or repeats one (the error goes on that column, in every row), or a row has more values than the header has columns (the error goes on row).

A value that the account or the tax ID rejects while the row is being applied is also an ERROR, with code null and its message in errors.row. A failure of the execution itself, such as a database or payment provider error, is an ERROR with code row_apply_failed. Neither stops the rest of the import.

Codes of the errors

Every entry of errors has its stable code in error_codes, an object with the same keys: {column: code}. The message of errors is in Spanish and may be reworded; the code is not translated and does not change, so react to the code, or translate it, and show the message only to a person. Like errors, it is always there and it is {} when the row has nothing wrong, and so it is in an import created before the field existed. A BLOCKED row comes out with both objects empty: its reason is the code of the row. The field is additive: errors does not change.

The preview

POST /v1/accounts/imports/preview classifies and prices the files without any effect: it writes nothing, provisions no account and charges nothing. To price the rows it only queries Stripe, for the end of your billing period and, for every confirmed plan change, the prorated amount of that change, so it has its own limit of 10 per minute. It needs no Idempotency-Key: it is a query that uses POST because it uploads files.

Take this accounts file:

mode;external_ref;plan;tax_id;legal_name;address;postal_code;city;province;country_code;owner_email;display_name;language;access_level
managed_account;cliente-0042;empresario;B12345674;Talleres García SL;Calle Mayor 1;28013;Madrid;Madrid;ES;laura@talleresgarcia.example;Talleres García;es;operate
own_nif;;;B87654323;Distribuciones Norte SL;;;;;;;;;
managed_account;cliente-0043;emprendedor;A58818501;Panadería Sol SA;;;;;;marta@panaderiasol.example;;es;
managed_account;cliente-0044;emprendedor;;Gráficas Levante SL;;;;;;ivan@graficaslevante.example;;;

It has four rows: a managed account, an own tax ID, a second managed account that does not fit in your cap and one that forgot its tax ID. The preview answers 200:

{
  "data": {
    "object": "managed_account_import_preview",
    "rows": [
      {
        "line": 2,
        "mode": "managed_account",
        "external_ref": "cliente-0042",
        "tax_id": "B12345674",
        "status": "VALID",
        "code": null,
        "errors": {},
        "error_codes": {},
        "plan": "empresario",
        "monthly_amount_cents": 3500,
        "proration_amount_cents": 1750,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null
      },
      {
        "line": 3,
        "mode": "own_nif",
        "external_ref": null,
        "tax_id": "B87654323",
        "status": "VALID",
        "code": null,
        "errors": {},
        "error_codes": {},
        "plan": null,
        "monthly_amount_cents": 1500,
        "proration_amount_cents": 750,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null
      },
      {
        "line": 4,
        "mode": "managed_account",
        "external_ref": "cliente-0043",
        "tax_id": "A58818501",
        "status": "BLOCKED",
        "code": "managed_accounts_limit_reached",
        "errors": {},
        "error_codes": {},
        "plan": "emprendedor",
        "monthly_amount_cents": 0,
        "proration_amount_cents": 0,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null
      },
      {
        "line": 5,
        "mode": "managed_account",
        "external_ref": "cliente-0044",
        "tax_id": null,
        "status": "ERROR",
        "code": null,
        "errors": {
          "tax_id": "La columna tax_id es obligatoria: cada fila da de alta un NIF."
        },
        "error_codes": {
          "tax_id": "required"
        },
        "plan": null,
        "monthly_amount_cents": 0,
        "proration_amount_cents": 0,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null
      }
    ],
    "totals": {
      "total_rows": 4,
      "valid": 2,
      "warning": 0,
      "already_exists": 0,
      "blocked": 1,
      "error": 1
    },
    "cost": {
      "currency": "EUR",
      "managed_account": {
        "monthly_amount_cents": 3500,
        "proration_amount_cents": 1750
      },
      "own_nif": {
        "monthly_amount_cents": 1500,
        "proration_amount_cents": 750
      },
      "total": {
        "monthly_amount_cents": 5000,
        "proration_amount_cents": 2500
      }
    },
    "own_company_customers": null
  }
}

The body has these fields:

And every row has these:

What the import costs

Every row carries monthly_amount_cents, the monthly amount it adds to your subscription, and proration_amount_cents, what applying it charges at once for what is left of your current billing period. cost adds them up for the managed_account rows, for the own_nif rows and in total, with the currency. Amounts are integer cents of taxable base, without VAT: the name of the key says the unit.

In the example, the two VALID rows add 3500 and 1500 cents a month, 50.00 EUR, and applying the file charges 2500 cents, 25.00 EUR, at once. The proration is half of the monthly amount, as when half of your billing period is left. The BLOCKED and the ERROR rows add nothing.

• Only what is charged counts. Only new rows that are VALID add a monthly amount: the new managed accounts, charged on the managed-accounts subscription of your account, and the new own tax IDs, charged as additional tax IDs. A row that already exists adds 0.
• A confirmed plan change adds only its proration. With confirm_plan_changes, the row of an existing account has no monthly amount but the proration that a single plan change would charge. An upgrade is charged at once. A downgrade takes effect at the end of your period and adds 0 now.
• Some imports cost 0. It is 0 for a test import, while your account is in its trial and when your account is not charged.
• The apply charges what the preview announced. The proration announced for a file is what applying the same files charges. The apply classifies the file again at the moment you send it, with the state of your account then, so a preview you made hours ago can differ.

Rows that come out BLOCKED

The code of a BLOCKED row is the reason. A row that is BLOCKED changes nothing, neither fields nor plan.

A row that the domain rejects while it is being applied, for example a cap that filled up between the preview and the apply, is also BLOCKED, with the public code of that rejection. Treat a code you do not know as the reason of a BLOCKED row.

An own_nif row also needs companies:write on the key, besides accounts:write: without it the row is ERROR with code insufficient_scope. If the key is limited to some tax IDs, each tax ID that the import registers is added to that limit, as when you register a tax ID with a single call.

Importing the same file again

Applying the same file again never duplicates an account and never charges twice. The external_ref of a managed_account row identifies the account, and the tax_id identifies an own_nif row. A row that names something that already exists comes out ALREADY_EXISTS, or WARNING or BLOCKED when what it asks for cannot be applied.

What a second import updates

Only a list of fields is updated, and only while the account is not claimed: display_name (the visible name, which is also the name of the account and of its tax ID), language, legal_name, address, postal_code, city, province and country_code. A field changes only when its cell has a value, and a value equal to the current one is not rewritten. Everything else is out of reach:

• The tax ID of an existing account cannot change: a different tax_id is an ERROR.
• The access level never changes. A lower level in the file is a WARNING and a higher one is BLOCKED.
• The plan changes only as the next paragraph says.

A row that asks for a different plan on an existing account is WARNING plan_change_not_confirmed and changes nothing, unless you send confirm_plan_changes. With it, the change is applied when you still pay for the account, your level on it is operate and it is not under an enterprise contract. If not, the row is BLOCKED with plan_change_not_paid_by_provider, plan_change_requires_operate or managed_account_plan_not_self_serve. The change is priced like a single plan change. If the profile was updated and the plan change fails afterwards, the row is WARNING with the reason in errors.plan.

Customers

customers_file loads the customers of each account and tax ID in the same import. It has a header row with the column account_ref and, in the other columns, the columns of the contacts import of a company: the header of the template of GET /v1/companies/{company}/contacts/import/template. Each customer goes to a row of the accounts file through its account_ref:

With the accounts file above, this customers file sends three customers to cliente-0042:

account_ref;name;kind;tax_id;email
cliente-0042;Bar La Plaza SL;company;B22222228;compras@barlaplaza.example
cliente-0042;Ferretería Ortiz SL;company;B33333337;info@ferreteriaortiz.example
cliente-0042;Hotel Mirador SA;company;A44444446;reservas@hotelmirador.example

The customers go through the contacts importer that already exists, with the role customer and the conflict strategy reject: a customer that clashes with an existing contact is rejected and the existing one stays as it is. Export and import explains what that importer accepts. The customers are queued: customers_queued counts what was queued, and the contacts are created afterwards, so the count is not proof that they already exist.

A row's customers are imported only into a tax ID that the row applied and where you can write. The state of each row is in customers_status, which is none (the row has no customers), queued or blocked, and in the second case customers_code says why:

With a key, accounts:write is not enough for the customers: the key needs contacts:write too.

Customers without an account: apply_customers_to_own_company

The customers that have no account_ref go nowhere, unless you send apply_customers_to_own_company. With it, they are imported into your own company in focus: the only tax ID in the scope of the key, or the only tax ID of your account. The destination is always a real tax ID of your own account, never one that another account granted to you. The key needs contacts:write, and the outcome is in own_company_customers:

own_company_customers has status (VALID, BLOCKED or ERROR), code, customers_queued and unmatched_customers, which counts the customers whose account_ref matches no row of the accounts file: they are imported nowhere, and this way they are not lost in silence.

Apply the import

POST /v1/accounts/imports takes the body of the request and applies it. It applies every row that is VALID, WARNING or ALREADY_EXISTS on its own, in the order of the file: a row that fails comes out BLOCKED or ERROR and the rest go on. It never opens a checkout: it charges your existing subscription, and a row that cannot be charged comes out BLOCKED with its reason.

curl -X POST https://api.factuarea.com/v1/accounts/imports \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "accounts_file=@accounts.csv" \
  -F "customers_file=@customers.csv" \
  -F "options[confirm_plan_changes]=false"

The application is synchronous: the answer arrives when the last row is done, and it can take a few minutes with a full file, so allow at least 5 minutes in your client. Suppose you took out the two rows that came out BLOCKED and ERROR and you send the customers file above. The answer is 201 Created:

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-8a8b8c8d8e8f",
    "object": "managed_account_import",
    "status": "completed",
    "stats": {
      "total_rows": 2,
      "valid": 2,
      "warning": 0,
      "already_exists": 0,
      "blocked": 0,
      "error": 0,
      "created": 2,
      "reconciled": 0,
      "customers_queued": 3,
      "monthly_amount_cents": 5000,
      "proration_amount_cents": 2500
    },
    "rows": [
      {
        "line": 2,
        "mode": "managed_account",
        "external_ref": "cliente-0042",
        "tax_id": "B12345674",
        "status": "VALID",
        "code": null,
        "errors": {},
        "error_codes": {},
        "plan": "empresario",
        "monthly_amount_cents": 3500,
        "proration_amount_cents": 1750,
        "account_id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
        "customers_status": "queued",
        "customers_queued": 3,
        "customers_code": null,
        "claim_token": "e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3",
        "claim_url": "https://app.factuarea.com/account-claims/accept?token=e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3"
      },
      {
        "line": 3,
        "mode": "own_nif",
        "external_ref": null,
        "tax_id": "B87654323",
        "status": "VALID",
        "code": null,
        "errors": {},
        "error_codes": {},
        "plan": null,
        "monthly_amount_cents": 1500,
        "proration_amount_cents": 750,
        "account_id": null,
        "customers_status": "none",
        "customers_queued": 0,
        "customers_code": null,
        "claim_token": null,
        "claim_url": null
      }
    ],
    "own_company_customers": null
  }
}

The amounts of stats and of each row are what the apply charged: the proration that the preview announced, calculated again at that moment. In the example, the managed account of line 2 returns its claim_token and claim_url, and the own tax ID returns null, because it has no voucher.

The voucher of every new live managed_account row comes back once, in this response. A replay of the same request returns it as null, and so does a row when send_email is true, because the link went by email, and every row of a test import. If you lose one, reissue it. The response has no Location header, because an execution has no public read operation. The app keeps the history and the report of every import, under Client accounts, Import, Import history, and when an import ends we publish account.import_completed to the account webhooks of your account, with the id of the execution and its stats.

Idempotency-Key and one import at a time

The apply cannot be taken back, so it requires an Idempotency-Key: without it the answer is 422 idempotency_key_required before anything is read. The preview does not need one. What each protection does:

After a 409, wait for the running import to end and send the same files again with a new Idempotency-Key: the rows the first one already applied come back ALREADY_EXISTS, never duplicated and never charged twice. An import that never finished stops blocking after 15 minutes. A 429 applies nothing: wait what Retry-After says and send the request again.

With a test key

With a fact_test_ key the import works on your test accounts, and nothing is charged:

• managed_account rows create or reconcile test accounts: no charge, no Stripe and no voucher, so claim_token and claim_url are null. A test account does not count against max_managed_accounts.
• own_nif rows come out ERROR with code live_credential_required and add 0 to the total: the tax IDs of your own account are only registered in live mode. The same goes for the customers that apply_customers_to_own_company would load into your own company.
• The environment is the key's. A test import only sees your test accounts: an external_ref that belongs to a live account comes out BLOCKED with managed_account_external_ref_in_other_environment, and the reverse.
• The cost is 0, in every row and in the totals.

The whole flow with a test key is in test managed accounts.

Two things the import does not do, by design

• No MCP tool. The three operations are privileged and the import reads two uploaded files, which the MCP server does not carry. The alternative is the REST API, or the import of the app. From an agent, provision the accounts one at a time with the tool provision_managed_account, which mirrors POST /v1/accounts: see from the MCP server.
• No series. The file has no column or option for document series: it registers accounts and tax IDs, not their numbering. Create or change the series of an imported tax ID with the operations of the company axis, for example POST /v1/companies/{company}/series/bootstrap, which creates the missing default series in one call and needs series:write. issuing-readiness tells you whether a tax ID still lacks one: no_default_series is one of its blockers, as what blocks a tax ID from issuing explains. The {company} of an imported tax ID is in companies[].id of GET /v1/accounts/{account} for a managed account, whose {account} is the account_id of the row, and in GET /v1/accounts/{account}/companies for your own tax IDs.

Errors

The rules that would reject a single provisioning reject a row here, never the request: they come in the 201 or the 200, in the status and code of the row. These are the errors of the request:

A 429 without a code of this table is a limit of the import: a preview over 10 per minute, or an apply over 5 per minute or over 20 per day. Wait what Retry-After says.

Next steps