--- title: "Updates a Financial document" method: PUT path: "/api/2026-10-01/resources/finance/financial_documents/{id}" tags: ["Finance > FinancialDocument"] --- # Updates a Financial document `PUT /api/2026-10-01/resources/finance/financial_documents/{id}` ## Request - Base URL: `https://api.factorialhr.com` - URL: `https://api.factorialhr.com/api/2026-10-01/resources/finance/financial_documents/{id}` - Auth: one of: - OAuth 2 - Authorization code: `https://id.factorialhr.com/oauth/authorize` - Token URL: `https://id.factorialhr.com/api/oauth/token` scopes: `finance` - API key in header `x-api-key` Update a purchase financial document with PUT semantics: read the document, modify it, and send the complete resource back — the fields are replaced as sent. Status transitions are accepted and have their real side effects. Fields required on a validated document are only enforced when the document is validated (validated_at present in the payload), not before. ## Path parameters - `id` string, required ## Request body - object - `company_id` string, required: Company identifier, as returned by the credentials endpoint (`/resources/api_public/credentials`). - `id` string, required: Identifier of the financial document to update. - `currency` string: Document currency (ISO 4217). - `total_amount_cents` integer: Total amount in cents. Ignored when line_items are provided, since the line items own the totals. - `document_number` string: Document number. Must be unique per vendor for purchases; a duplicate returns a 409 with the same machine-readable invoice_number error key as the create endpoint. - `document_date` string: Document date. - `due_date` string: Due date. - `status` 'processing' | 'review' | 'sent_to_pay' | 'paid', required: Status of the document. Transitions have real side effects: `sent_to_pay` enqueues a payment request in Factorial, and `paid` marks the document as paid (manual payment). Once a document is `sent_to_pay`, its payment lifecycle is owned by the payment flow in Factorial — do not set `paid` manually on it; the payment reconciliation does. - `validated_at` string: Validation timestamp, as returned by the read endpoint (e.g. `2020-01-01T00:00:00.000Z`). Setting it on a not-yet-validated document validates it: the strict required-field set (currency, amounts, document number, dates, vendor, legal entity) is enforced on that transition, not before. - `taxes` object[], required: Tax breakdown, as returned by the read endpoint — send back what you read (adjusted to your changes). Replaced as sent; ignored when line_items are provided, since the line items own the totals. - `amount_cents` integer - `percentage` number - `base_amount_cents` integer - `type` 'vat' | 'personal_income' - `tax_type_id` string - `tax_type_name` string - `tax_rates` object[] - `percentage` number, required - `line_items` object[]: Purchase-invoice line items. Rows are addressed by id, never by position: rows carrying an id update the matching line item, rows without an id create new ones, and persisted rows missing from the set are deleted. Send an empty array to remove all line items, or omit the field entirely to leave them untouched. When present they own the document totals. - `id` string - `description` string, required - `quantity` number, required - `unit_price_cents` integer, required - `tax_rate_id` string - `discount_percentage` number - `legal_entity_id` string: Legal entity identifier of the financial document. - `vendor_id` string: Vendor identifier (Finance contact). - `document_type` 'invoice' | 'credit_note' | 'receipt': Type of the financial document. One of `invoice`, `credit_note`, `receipt`. - `parent_financial_document_id` string: For credit notes, the referenced original document by internal id (e.g. `135`). - `additional_information` string: Free-text internal notes about the financial document. Kept unchanged when the field is absent. ## Response `200` OK - FinanceFinancialDocument - `id` string, required: Factorial unique identifier for the financial document. - `net_amount_cents` integer: Sum of the line items before taxes, in cents. Use `total_amount_cents` for what is actually payable. - `total_amount_cents` integer: Total payable on the document, taxes included, in cents. - `document_number` string: Number the issuer printed on the document; for a purchase, the vendor's own invoice number. Not a Factorial identifier: on a purchase it is only unique per vendor, so the same number can legitimately appear on documents from two different vendors. - `currency` string: ISO 4217 code of the currency the document is issued in, such as EUR or USD. Every amount on the document is expressed in it, so comparing amounts across documents without checking this is unsafe. - `status` 'processing' | 'review' | 'sent_to_pay' | 'paid', required: Where the document stands on its way to being paid: `processing` while it is still being prepared, `review` while it awaits review (the value is `review`, never `pending`), `sent_to_pay` once it has been sent for payment, and `paid`. This is not an approval state: a document generated from an employee expense is created already `paid`, because the money left before Factorial ever saw it. - `due_date` string: Date the payment falls due, as stated on the document. - `document_date` string: Date the issuer put on the document. Distinct from `created_at`, which is when it reached Factorial; a document can arrive weeks after it was issued. - `legal_entity_id` string: Factorial unique identifier for the legal entity of the financial document. - `vendor_id` string: Factorial unique identifier for the vendor of the financial document. - `file` object: File attached. - `id` string, required - `filename` string, required - `url` string, required - `size` integer, required - `content_type` string, required - `created_at` string, required - `updated_at` string, required: Updation date. - `taxes` object[], required: Taxes. - `amount_cents` integer - `percentage` number - `base_amount_cents` integer - `type` 'vat' | 'personal_income' - `tax_type_id` string - `tax_type_name` string - `tax_rates` object[] - `percentage` number, required - `fully_reconciled_at` string: When the document was fully matched against bank transactions. Null while any part of it remains unreconciled. - `recorded_at` string: When the document was posted to accounting. Only possible once `validated_at` is set. - `duplicate_financial_document_id` string: Factorial unique identifier for the duplicate financial document. - `validated_at` string: When a person confirmed the document data is correct. Validation is what unlocks recording and payment; it is not an approval decision, and says nothing about whether the spend was authorised. - `validated_by_id` string: Factorial unique identifier of the employee who validated the document. - `document_type` 'invoice' | 'receipt' | 'credit_note', required: One of `invoice`, `receipt` or `credit_note`. A document generated from an expense is typed automatically and can flip between `receipt` and `invoice` when the employee edits the expense. - `parent_financial_document_id` string: Factorial unique identifier for the parent financial document of the financial document. - `taxes_total_amount_cents` integer: Sum of every tax charged on the document, in cents. - `issuer_name` string: Name of the entity issuing the financial document. - `issuer_address_line_1` string: First line of the issuer's address. - `issuer_address_line_2` string: Second line of the issuer's address. - `issuer_city` string: City of the issuer's address. - `issuer_postal_code` string: Postal code of the issuer's address. - `issuer_state` string: State or province of the issuer's address. - `issuer_country_code` string: Country code of the issuer's address. - `issuer_tax_id` string: Tax identification number of the issuer. - `recipient_name` string: Name of the entity receiving the financial document. - `recipient_address_line_1` string: First line of the recipient's address. - `recipient_address_line_2` string: Second line of the recipient's address. - `recipient_city` string: City of the recipient's address. - `recipient_postal_code` string: Postal code of the recipient's address. - `recipient_state` string: State or province of the recipient's address. - `recipient_country_code` string: Country code of the recipient's address. - `recipient_tax_id` string: Tax identification number of the recipient. ## Changes - **2026-11-03** `83ac9aa1de50`: 1 info - endpoint added [Operation history](https://skmtc.dev/factorialhr/apis/factorial-api/changes/api/2026-10-01/resources/finance/financial_documents/:id/put.md) --- [API](https://skmtc.dev/factorialhr/apis/factorial-api.md) - [All operations](https://skmtc.dev/factorialhr/apis/factorial-api/llms.txt) - [OpenAPI document](https://skmtc.dev/factorialhr/apis/factorial-api/revisions/83ac9aa1de50?raw)