FAfactorialhr
Finance > FinancialDocument

Updates a Financial document

Changed on

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.

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
    • 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

Path parameters

idstring required

Identifier of the financial document to update.

Request body

company_idstring required

Company identifier, as returned by the credentials endpoint (/resources/api_public/credentials).

idstring required

Identifier of the financial document to update.

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.

document_numberstring

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_datestring

Document date.

due_datestring

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_atstring

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.

legal_entity_idstring

Legal entity identifier of the financial document.

vendor_idstring

Vendor identifier (Finance contact).

document_type'invoice' | 'credit_note' | 'receipt'

Type of the financial document. One of invoice, credit_note, receipt.

parent_financial_document_idstring

For credit notes, the referenced original document by internal id (e.g. 135).

additional_informationstring

Free-text internal notes about the financial document. Kept unchanged when the field is absent.

Example request

{
  "company_id": "1",
  "id": "135",
  "currency": "USD",
  "total_amount_cents": 11210,
  "document_number": "INV-135",
  "document_date": "2020-01-01",
  "due_date": "2020-01-01",
  "status": "review",
  "taxes": [
    {
      "amount_cents": 1210,
      "base_amount_cents": 10000,
      "percentage": 0.21,
      "type": "vat",
      "tax_rates": [
        {
          "percentage": 21
        }
      ]
    }
  ],
  "legal_entity_id": "13",
  "vendor_id": "33",
  "document_type": "invoice",
  "additional_information": "Imported from ERP"
}

Response

OK

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