Skip to main content

Upload Bill Invoice for Reading

POST 

/api/bills/ocr/upload

Upload a vendor invoice to be read into a draft expense bill (a bill with no purchase order, warehouse transfer or inbound shipment). Reading runs in the background; the response returns the extraction to poll.

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Body (multipart/form-data):

  • file (required) - the invoice. PDF or an image: pdf, jpg, jpeg, png, tif, tiff, bmp, webp. Max 20 MB.
  • supplier_id (optional, integer, nullable) - an existing supplier, when you already know who sent the invoice. Otherwise the reader proposes one.

After upload: poll GET /api/landed-cost-invoices/ocr/{extraction} until the extraction is read, then review it and create the bill with POST /api/landed-cost-invoices/ocr/{extraction}/apply. An apply with no targets creates one expense bill; pass duplicate_acknowledged: true on the apply to save an invoice whose number the supplier already has. Use Suggest Bill Line Accounts to propose an expense account for each read line.

Duplicate files: a file whose content matches one already kept with a bill, an invoice still being read or reviewed, or a provider bill under review is refused with 422 on file, and existing says where the first copy is (type is bill, extraction, provider_bill or upload when the same file is sent twice).

Returns 422 with a message when invoice reading is switched off for the workspace (see Get Bill Invoice Reading Status).

Authentication: Requires Bearer token. Permission: create bills (bills.create). Scope: purchase-orders (read/write).

Request​

Responses​

Created

Response Headers
    Content-Type