FAfactorialhr
Finance > FinancialDocument

Creates a Financial document

Changed on

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.

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
    • OAuth 2
      Authorization code: https://id.factorialhr.com/oauth/authorize
      Token URL: https://id.factorialhr.com/api/oauth/token scopes: finance
    • or API key in header x-api-key

Request body multipart/form-data

company_idstring 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_idstring

Vendor identifier (Finance contact).

legal_entity_idstring

Legal entity identifier of the financial document.

invoice_numberstring

Document number. Must be unique per vendor for purchases; a duplicate returns a 422 with a machine-readable invoice_number error.

invoice_datestring

Document date.

due_datestring

Due date.

currencystring

Document currency (ISO 4217).

total_amount_centsinteger

Total amount in cents. Ignored when line_items are provided, since the line items own the totals.

additional_informationstring

Free-text internal notes about the financial document.

parent_financial_document_idstring

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_numberstring

For credit notes, the referenced original document by invoice number (resolved together with the vendor).

filestring binary required

The document file to upload, the binary file. Required for purchase documents.

Example request

{
  "company_id": "1",
  "document_type": "invoice",
  "vendor_id": "33",
  "legal_entity_id": "13",
  "invoice_number": "INV-135",
  "invoice_date": "2020-01-01",
  "due_date": "2020-01-31",
  "currency": "USD",
  "total_amount_cents": 11210,
  "additional_information": "Imported from ERP",
  "parent_financial_document_id": "135",
  "original_invoice_number": "INV-135",
  "line_items[]": [
    {
      "description": "Consulting services",
      "quantity": 2,
      "unit_price_cents": 5000,
      "tax_rate_id": 7
    }
  ],
  "file": "invoice.pdf"
}

Response

CREATED

idstring required

Factorial unique identifier for the financial document.

net_amount_centsinteger

Sum of the line items before taxes, in cents. Use total_amount_cents for what is actually payable.

total_amount_centsinteger

Total payable on the document, taxes included, in cents.

document_numberstring

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.

currencystring

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_datestring

Date the payment falls due, as stated on the document.

document_datestring

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_idstring

Factorial unique identifier for the legal entity of the financial document.

vendor_idstring

Factorial unique identifier for the vendor of the financial document.

updated_atstring required

Updation date.

fully_reconciled_atstring

When the document was fully matched against bank transactions. Null while any part of it remains unreconciled.

recorded_atstring

When the document was posted to accounting. Only possible once validated_at is set.

duplicate_financial_document_idstring

Factorial unique identifier for the duplicate financial document.

validated_atstring

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_idstring

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_idstring

Factorial unique identifier for the parent financial document of the financial document.

taxes_total_amount_centsinteger

Sum of every tax charged on the document, in cents.

issuer_namestring

Name of the entity issuing the financial document.

issuer_address_line_1string

First line of the issuer's address.

issuer_address_line_2string

Second line of the issuer's address.

issuer_citystring

City of the issuer's address.

issuer_postal_codestring

Postal code of the issuer's address.

issuer_statestring

State or province of the issuer's address.

issuer_country_codestring

Country code of the issuer's address.

issuer_tax_idstring

Tax identification number of the issuer.

recipient_namestring

Name of the entity receiving the financial document.

recipient_address_line_1string

First line of the recipient's address.

recipient_address_line_2string

Second line of the recipient's address.

recipient_citystring

City of the recipient's address.

recipient_postal_codestring

Postal code of the recipient's address.

recipient_statestring

State or province of the recipient's address.

recipient_country_codestring

Country code of the recipient's address.

recipient_tax_idstring

Tax identification number of the recipient.

Example response

{
  "id": "135",
  "net_amount_cents": 10000,
  "total_amount_cents": 11210,
  "document_number": "INV-135",
  "currency": "USD",
  "status": "review",
  "due_date": "2020-01-01",
  "document_date": "2020-01-01",
  "legal_entity_id": "13",
  "vendor_id": "33",
  "file": {
    "id": 1,
    "filename": "invoice.pdf",
    "url": "https://factorial.com/invoice.pdf",
    "size": 1024,
    "content_type": "application/pdf",
    "created_at": "2020-01-01T00:00:00.000Z"
  },
  "updated_at": "2020-01-01T00:00:00.000Z",
  "taxes": [
    {
      "amount_cents": 1210,
      "base_amount_cents": 10000,
      "percentage": 0.21,
      "type": "vat",
      "tax_rates": [
        {
          "percentage": 21
        }
      ]
    }
  ],
  "fully_reconciled_at": "2020-01-01T00:00:00.000Z",
  "recorded_at": "2020-01-01T00:00:00.000Z",
  "validated_at": "2020-01-01T00:00:00.000Z",
  "validated_by_id": "31",
  "document_type": "invoice",
  "parent_financial_document_id": "135",
  "taxes_total_amount_cents": 1210,
  "issuer_name": "Acme Corporation",
  "issuer_address_line_1": "123 Main Street",
  "issuer_address_line_2": "Suite 100",
  "issuer_city": "San Francisco",
  "issuer_postal_code": "94105",
  "issuer_state": "California",
  "issuer_country_code": "US",
  "issuer_tax_id": "US123456789",
  "recipient_name": "XYZ Company",
  "recipient_address_line_1": "456 Market Street",
  "recipient_address_line_2": "Floor 5",
  "recipient_city": "New York",
  "recipient_postal_code": "10001",
  "recipient_state": "New York",
  "recipient_country_code": "es",
  "recipient_tax_id": "B66854530"
}

Changes