# Upload an incoming invoice

Required scopes: incoming-invoice:write

Creates a new incoming invoice document and optionally attaches an uploaded file.
When a file is uploaded and file_was_preprocessed is not set (or false), the
system will automatically run OCR to extract invoice data from the document.
Fields explicitly provided in the request always take precedence over OCR results.
Optionally, cost-center bookings can be created inline.

Endpoint: POST /incoming-invoices
Version: v1
Security: http, oauth2

## Request fields (multipart/form-data):

  - `external_id` (string,null)
    Can be used to add an identifier from an external system, must be unique within integration

  - `external_origin` (string)
    If not set, integration's slug will be used as default

  - `title` (string,null)

  - `type` (string,null)
    Invoice or Credit
    Enum: "Invoice", "Credit"

  - `invoice_number` (string,null)
    External invoice number

  - `notes` (string,null)
    Free-text notes / annotations

  - `date_of_invoice` (string,null)

  - `due_date` (string,null)

  - `date_of_start` (string,null)

  - `date_of_end` (string,null)

  - `net_value` (number,null)

  - `vat_value` (number,null)

  - `supplier_id` (string,null)

  - `editor_id` (string,null)

  - `payment_account_id` (string,null)
    Obfuscated payment account ID

  - `file_was_preprocessed` (boolean,null)
    When true, the internal OCR workflow is skipped. Use this when the
calling system has already extracted invoice data from the document.

  - `file` (string)
    PDF or image file to upload - Max: 15MB

  - `tags` (array,null)

  - `vats` (array,null)
    VAT breakdown lines

  - `vats.vat` (number, required)
    VAT rate in percent
    Example: 20

  - `vats.value` (number, required)
    Calculated VAT amount for this rate

## Response 200 fields (application/json):

  - `id` (string, required)

  - `external_id` (string,null, required)

  - `external_origin` (string,null, required)

  - `type` (string, required)
    | |
|---|
| Invoice  Standard incoming invoice |
| Credit  Credit note |
    Enum: "Invoice", "Credit"

  - `title` (string, required)

  - `status` (string, required)

  - `payment_status` (string, required)

  - `invoice_number` (string,null, required)

  - `notes` (string,null, required)

  - `sum_net` (number, required)

  - `sum_tax` (number, required)

  - `sum_gross` (number, required)

  - `vats` (array, required)
    VAT breakdown

  - `vats.vat` (number, required)
    VAT rate in percent

  - `vats.value` (number, required)
    Calculated VAT amount

  - `supplier` (any, required)

  - `payment_account` (any, required)

  - `date_of_invoice` (string,null, required)

  - `due_date` (string,null, required)

  - `date_of_start` (string,null, required)

  - `date_of_end` (string,null, required)

  - `editor` (any, required)

  - `bookings` (array)
    Chart of account bookings

  - `bookings.type` (string, required)

  - `bookings.value` (number, required)

  - `bookings.chart_of_account_id` (string,null, required)

  - `bookings.position_id` (string,null, required)

  - `bookings.project_id` (string,null, required)

  - `bookings.client_id` (string,null, required)

  - `bookings.chart_of_account` (any, required)

  - `bookings.outgoing_invoice` (any, required)

  - `bookings.created_at` (string, required)

  - `bookings.updated_at` (string,null, required)

  - `payments` (array)
    Payments

  - `payments.payment_type` (string,null, required)

  - `payments.payment_account_id` (string,null, required)

  - `payments.account` (any, required)

  - `payments.date` (string,null, required)

## Response 401 fields (application/json):

  - `message` (string, required)
    Error overview.

## Response 422 fields (application/json):

  - `message` (string, required)
    Errors overview.

  - `errors` (object, required)
    A detailed description of each field that failed validation.