---
title: "Creates a Financial document"
method: POST
path: "/api/2026-10-01/resources/finance/financial_documents"
tags: ["Finance > FinancialDocument"]
---

# Creates a Financial document

`POST /api/2026-10-01/resources/finance/financial_documents`

## Request

- Base URL: `https://api.factorialhr.com`
- URL: `https://api.factorialhr.com/api/2026-10-01/resources/finance/financial_documents`
- 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`

Create a purchase financial document (invoice, credit note or receipt) together with its file. Sent as multipart/form-data. The document is created in draft (pending review) state; the strict required-field set is only enforced when it is validated in the app.

## Request body `multipart/form-data`

- object
  - `company_id` string, required: Company identifier, refers to /api/me endpoint.
  - `document_type` 'invoice' | 'credit_note' | 'receipt', required: Type of the financial document. One of `invoice`, `credit_note`, `receipt`.
  - `vendor_id` string: Vendor identifier (Finance contact).
  - `legal_entity_id` string: Legal entity identifier of the financial document.
  - `invoice_number` string: Document number. Must be unique per vendor for purchases; a duplicate returns a 422 with a machine-readable invoice_number error.
  - `invoice_date` string: Document date.
  - `due_date` string: Due date.
  - `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.
  - `additional_information` string: Free-text internal notes about the financial document.
  - `parent_financial_document_id` string: For credit notes, the referenced original document by internal id (exposed as parent_financial_document_id to match the read contract). Provide this or original_invoice_number.
  - `original_invoice_number` string: For credit notes, the referenced original document by invoice number (resolved together with the vendor).
  - `line_items[]` object[]: Purchase-invoice line items. 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
  - `file` string, binary, required: The document file to upload, the binary file. Required for purchase documents.

## Response `201`

CREATED

- 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/post.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)