Sign in
invoices

Bulk import invoices

Asynchronously creates up to 100 invoices in a single request. Each invoice must include a unique upload_id and a valid ottimate_location_id. Processing is queued via backgrund job and returns a batch_id for polling progress and results.

post/invoices/import

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.

dimensionsInvoicesImportPostRequestBodyContentApplicationJsonSchemaItemsDimensions

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_fieldsInvoicesImportPostRequestBodyContentApplicationJsonSchemaItemsCustomFields

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 attach to the invoice. Supported formats: PDF, JPG, JPEG, PNG. raw_images is not supported for bulk import.

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

Bulk import accepted and queued for processing.

statusstring

Always "processing" — indicates the job was queued.

batch_idstring

Unique ID for this batch job. Use with GET /v1/batch/{batch_id}/progress to poll status and GET /v1/batch/{batch_id}/results to fetch per-invoice outcomes.

batch_urlstring

Relative URL to poll for batch progress.

results_urlstring

Relative URL to fetch per-invoice results once the batch completes.

Changes