Sign in
invoices

Create invoice header and line items

Creates an invoice along with its line items. The invoice header and items are created in separate transactions.

Features

  • Create invoice header fields (date, amount, vendor, notes, etc.)
  • Create new line items.
  • Attach custom metadata fields to invoice header and line items (requires account-level custom field spec configuration).

Use Cases

  • Programmatic invoice creation from external systems.
post/invoices

Headers

Authorizationstring required

OAuth2 authentication flows. Auth server URLs will vary by environment

X-Api-Keystring required

API key for authentication

X-API-Versionstring

API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.

Idempotency-Keystring

Client-generated unique key (UUID/ULID recommended). JSON requests: the first 2xx response is cached for 24h and replayed on a same-key retry with a matching body; a different body returns 422. Non-JSON requests (e.g. file uploads): the key is single-use — any same-key retry returns 422 regardless of body. See Idempotency for full details.

Request body

upload_idstring required

A mandatory unique identifier for creating an invoice.

ottimate_location_idinteger required

The ID of the location for this invoice.

erp_vendor_idstring

The ERP ID of the vendor for this invoice.

invoice_numberstring
invoice_datestring date
due_datestring date
posting_datestring date
total_amountnumber double
total_taxnumber double
purchase_orderstring
notesstring
currencystring
type'invoice' | 'credit_memo'

Type of document.

dimensionsInvoicesPostRequestBodyContentApplicationJsonSchemaDimensions

Header-level dimension mappings. Keys are dimension types (e.g., 'DEPARTMENT', 'CLASS') and values are erp_dimension_id strings from the GET /dimensions endpoint. If omitted, no dimensions are set. Invalid dimension types or IDs return a 400 error.

custom_fieldsInvoicesPostRequestBodyContentApplicationJsonSchemaCustomFields

Header-level custom metadata fields for this invoice. Keys and value types are validated against the custom field spec configured for your account in Ottimate.

Requirements: Custom fields must be configured for your account before use. Sending custom_fields when no spec is configured returns a 400 error. Unrecognised keys return a 400 error.

Behaviour: Omitted keys are filled with their configured default values

image_urlsstring[]

List of HTTPS image URLs to download and attach to the invoice. Supported formats: PDF, JPG, JPEG, PNG.

status'archived' | 'verified'

Optional. Only needed when ingesting invoices that are already fully processed elsewhere (e.g. historical backfills or invoices already coded/posted in your ERP) and should skip Ottimate's normal approval workflow. Omit for standard invoice ingestion. archived creates the invoice already approved, exported, and filed as a historical/inactive record (with relaxed dimension/GL validation appropriate for backfilled data). verified creates the invoice already approved and exported, but keeps it as a normal active invoice. Note: this is a write-only request field, distinct from the status field returned in the response.

Response

Invoice created successfully. Check if 'errors' are present in the response to identify any issues during creation. For 'items' creation errors, the invoice will be created but items may be missing or incomplete. Refer to 'items' for details.

versionstring

The API version of the response.

idstring

The ID of the created invoice.

statusstring

The status of the created invoice (e.g., 'incomplete', 'processing').

conflicting_invoice_idstring

The ID of a conflicting invoice, if one was detected.

errorsstring[]

A list of validation errors or warnings related to the invoice creation.

Changes