Recent operations join the axis

5 October 2026 — the operations that reached the API since 21 September were published on flat paths, before the company axis existed. They now live where every other company resource lives, under /v1/companies/{company}/…: the operations of the tables below. This is the same migration as the axis window, applied to what came after it, and it needs no second step.

• No flat alias. A call to the old path answers the standard 404 of a route that does not exist. Use the path in the Now column.
• Nothing else changes by default. Route names (public-api.v1.*), scopes, bodies and responses stay as published, except what the sections below state: eight verbs, a few paths that change more than the prefix, a handful of error statuses and one webhook payload version.
• The company comes from the credential. The {company} segment is validated against the scope of the credential: 403 company_inactive if the tax ID is inactive, and 404 profile_not_found if it is outside the scope, does not exist or belongs to the other environment. The three 404 look the same on purpose.
• Location carries the axis. The creations of POST …/tasks, …/tasks/{task}/duplicate, …/projects, …/task-labels and POST …/verifactu/representation answer /v1/companies/{company}/<resource>/<id>.

Verbs: PUT becomes PATCH

The partial updates of the new families follow the convention of the rest of the API: PATCH changes only the fields you send. PUT stays where the whole resource is replaced by design.

Still PUT, because they replace the whole resource: projects.columns.reorder, tasks.comments.update and tasks.custom_fields.set. A PUT to one of the eight migrated paths answers 405.

Editing a series keeps the same partial body and the same fiscal guards (BR-SER-020, BR-SER-021, 422 with its subcode). On …/series/{series} the 405 series_immutable now carries Allow: GET, PATCH and its message points to PATCH /v1/companies/{company}/series/{id} and to POST …/archive; PUT and DELETE answer 405. The MCP tool update_series is the same tool, described as a partial PATCH; its arguments do not change.

Paths that change more than the prefix

Two visible consequences: the source_url of the scanner responses and the error_report_url of the contact imports now carry the axis. The 101 MB upload limit of the scanner applies to POST /v1/companies/<uuid>/purchase-scans.

Error codes and statuses

409 idempotency_key_in_use (the key is in flight) does not change.

The flat /v1/clients and /v1/suppliers operations and the *_client and *_supplier MCP tools stay retired; contacts replace them under /v1/companies/{company}/contacts. The tool names search_clients, find_client_by_tax_id, create_client and bulk_create_clients keep resolving to the contact tools until 15 November 2026, flagged with _meta["io.factuarea/deprecation"].

Webhook payload version

The payload versions are now 2026-05-22, 2026-10-01 and 2026-10-05 (the latest). 2026-10-01 is the one that introduced the issued vocabulary of invoices; 2026-10-05 adds amounts as decimal strings and paid_recorded_at and paid_date. An endpoint pinned to 2026-10-01 or 2026-05-22 does not change: it keeps numeric amounts, paid_at and paid_on. An endpoint created without an explicit api_version stays on 2026-05-22, unless the request that creates it uses the REST version 2026-10-01, in which case it takes the latest one (2026-10-05). You can move an existing endpoint with PATCH and api_version. The request version Factuarea-Version: 2026-10-01 keeps its date and effect. See Webhook payload versions.

MCP

The tools take no company argument: the company comes from the token or the session. The tools of projects and tasks, notifications, users, agenda, the scanner, the VeriFactu representation, issue_invoice, list_purchase_invoice_expense_categories and the contact imports (get_contact_import, download_contact_import_errors) mirror one to one the routes of the tables below. A domain error of tools/call is now a result with isError: true, the message of the domain and _meta["com.factuarea/error"] (code, subcode, param, with the same status as the REST API).

Other contract changes

• Contact import templates. GET /v1/companies/{company}/contacts/import/template takes format: csv (default, separated by ;) or xlsx, a workbook with the Data, Instructions, Examples and Allowed values sheets. Both come from the same column descriptors as the importer.
• Import reports. The import resource (GET …/contacts/imports/{id} and the response of POST …/contacts/import) adds updated_count, warnings_count, outcome_kind, skip_reasons, first_diagnostics and outcomes_truncated, and each row of outcomes carries a reason. outcome_kind: nothing_changed means the import finished without creating or updating anything: do not present it as a success. The new code mapping_header_not_found is returned by contacts.import and contacts.preview_import.
• Sales documents. Invoices (and their events) publish origin (native or historical_import); quotes and pro-forma invoices publish reference and operation_regime.
• Task import. POST …/projects/{project}/tasks/import and the MCP tool import_project_tasks accept an optional idempotency_key and report warnings_total and warnings_truncated.
• Scanner writes without access. On the writes of the purchase scanner (POST …/purchase-scans, …/retry, PATCH …/review, …/duplicate-resolution, …/convert, DELETE …/{purchase_scan}, …/restore), a key whose creator has no access to the company now answers 404 profile_not_found instead of 403 api_key_creator_not_member. The 403 stays on the download of the original (GET …/source) and on the MCP write tools.
• Payment amounts in the activity. In GET …/invoices/{invoice}/activities (and the tool get_invoice_activities), metadata.amount of the events payment.payment_created and payment.payment_reversed is now a two-decimal string ("50.50"), not a number in euros.

Every operation, by family

Projects and tasks

Tasks, projects, labels, timers and the agenda (75).

Purchase scanner

The purchase scanner and its mailbox (12). Segments are in kebab-case.

Notifications

The notifications of the credential holder (3).

VeriFactu: representation and blocked records

Representation and retry of blocked records (4).

Invoices, contact imports, users, expense categories and series

(7)