---
title: "Bulk import invoices"
method: POST
path: "/invoices/import"
tags: ["invoices"]
---

# Bulk import invoices

`POST /invoices/import`

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.

## Headers

- `Authorization` string, required
- `X-Api-Key` string, required
- `X-API-Version` string
- `Idempotency-Key` string

## Request body

- InvoicesImportPostRequestBodyContentApplicationJsonSchemaItems[]
  - `upload_id` string, required — A mandatory unique identifier for creating an invoice.
  - `ottimate_location_id` integer, required — The ID of the location for this invoice.
  - `erp_vendor_id` string — The ERP ID of the vendor for this invoice.
  - `invoice_number` string
  - `invoice_date` string, date
  - `due_date` string, date
  - `posting_date` string, date
  - `total_amount` number, double
  - `total_tax` number, double
  - `purchase_order` string
  - `notes` string
  - `currency` string
  - `type` 'invoice' | 'credit_memo' — Type of document.
  - `dimensions` InvoicesImportPostRequestBodyContentApplicationJsonSchemaItemsDimensions — 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_fields` InvoicesImportPostRequestBodyContentApplicationJsonSchemaItemsCustomFields — 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_urls` string[] — List of HTTPS image URLs to attach to the invoice. Supported formats: PDF, JPG, JPEG, PNG. raw_images is not supported for bulk import.
  - `items` InvoicesImportPostRequestBodyContentApplicationJsonSchemaItemsItemsItems[] — Line items to create for the invoice.
    - `name` string, required
    - `sku` string
    - `quantity` number, double, required
    - `price` number, double, required
    - `is_taxed` boolean
    - `dimensions` InvoicesImportPostRequestBodyContentApplicationJsonSchemaItemsItemsItemsDimensions — Item-level dimension mappings. Same format as header-level dimensions: keys are dimension types and values are `erp_dimension_id` strings. If omitted, no item-level dimensions are set.
    - `custom_fields` InvoicesImportPostRequestBodyContentApplicationJsonSchemaItemsItemsItemsCustomFields — Item-level custom metadata fields. Keys and value types are validated against the invoice item custom field spec configured for your account in Ottimate. **Requirements**: Invoice item custom fields must be configured for your account before use. Returns a `400` error if no spec is found or if unrecognised keys are sent. **Behaviour**: Omitted keys are filled with their configured default values.
  - `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 `202`

Bulk import accepted and queued for processing.

- InvoicesPostInvoicesImportResponse202
  - `status` string — Always "processing" — indicates the job was queued.
  - `batch_id` string — 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_url` string — Relative URL to poll for batch progress.
  - `results_url` string — Relative URL to fetch per-invoice results once the batch completes.
  - `summary` InvoicesImportPostResponsesContentApplicationJsonSchemaSummary
    - `invoice_count` integer — Number of invoices accepted for processing.

## Other responses

- `400` — Bad request - Invalid parameters or request format
- `403` — Forbidden - Access denied or insufficient permissions

## Changes

- **2026-08-22** `75aab60eedc9` — 2 breaking, 1 warning
  - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `0` to `1`
  - added the pattern `^[A-Za-z0-9._\-+=/]{1,128}$` to the `header` request parameter `Idempotency-Key`
  - for the `header` request parameter `Idempotency-Key`, the maxLength was set to `128`
- **2026-08-19** `c0b5cf6c7a72` — 1 info
  - added the new optional request property `items/status`
- **2026-08-17** `c231509a03cf` — 2 breaking, 1 warning, 4 info
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `400`
  - the `message` response's property type/format changed from `string`/`` to ``/`` for status `403`
  - removed the request property `items/status`
  - the response property `code` became required for the status `400`
  - …3 more
- **2026-08-13** `1f089f3e34d9` — 6 breaking, 1 info
  - the response property `code` became optional for the status `400`
  - the response property `code` became optional for the status `403`
  - the response property `message` became optional for the status `400`
  - the response property `message` became optional for the status `403`
  - …3 more

[Change history](https://skmtc.dev/ottimate/apis/api-reference/changes/invoices/import/post.md)

---

[API](https://skmtc.dev/ottimate/apis/api-reference.md) · [All operations](https://skmtc.dev/ottimate/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ottimate/api-reference/revisions/ba91ff4c6969/schema)