Create invoice header and line items | Ottimate Developer Documentation

curl -X POST https://api.ottimate.com/v1/invoices \
     -H "X-Api-Key: your-api-key-here" \
     -H "X-API-Version: 1.0.0" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "upload_id": "upload-550e8400-e29b-41d4-a716-446655440000",
  "ottimate_location_id": 123,
  "erp_vendor_id": "456",
  "invoice_number": "INV-2025-11-001",
  "invoice_date": "2025-11-27",
  "total_amount": 250.75,
  "type": "invoice",
  "dimensions": {
    "DEPARTMENT": "erp_dim_dept123",
    "CLASS": "erp_dim_class456"
  },
  "items": [
    {
      "name": "Gluten-Free Bread",
      "quantity": 3,
      "price": 25.25,
      "sku": "GF-BREAD-001",
      "is_taxed": true,
      "dimensions": {
        "DEPARTMENT": "erp_dim_demo2C"
      }
    }
  ]
}'

{
  "version": "1.0.0",
  "id": "1774562",
  "status": "needs-attention",
  "conflicting_invoice_id": "1774691",
  "items": {
    "success": {
      "0": 92810
    },
    "failure": {
      "1": "Missing value for quantity"
    },
    "status": "partial_success"
  },
  "errors": [
    "Other reasons",
    "Line items total doesn't match invoice total amount",
    "It is unclear what the total tax should be. Please review the tax in the invoice header and taxable 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.

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.

Authentication

AuthorizationBearer

OAuth2 authentication flows. Auth server URLs will vary by environment

Headers

Idempotency-KeystringOptionalformat: "^[A-Za-z0-9._\-+=/]{1,128}$"1-128 characters

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

Invoice creation payload with header and optional items array.

upload_idstringRequired

A mandatory unique identifier for creating an invoice.

ottimate_location_idintegerRequired

The ID of the location for this invoice.

erp_vendor_idstringOptional

The ERP ID of the vendor for this invoice.

invoice_numberstringOptional

invoice_datestringOptionalformat: "date"

due_datestringOptionalformat: "date"

posting_datestringOptionalformat: "date"

total_amountdoubleOptional

total_taxdoubleOptional

purchase_orderstringOptional

notesstringOptional

currencystringOptional

typeenumOptional

Type of document.

Allowed values:

dimensionsobject or nullOptional

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_fieldsobject or nullOptional

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

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

itemslist of objectsOptional

Line items to create for the invoice.

image_urlslist of stringsOptional

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

raw_imageslist of objectsOptional

List of base64-encoded images to attach to the invoice. Supported formats: PDF, JPG, JPEG, PNG.

statusenumOptional

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.

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.

Allowed values:

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.

versionstringOptional

The API version of the response.

idstringOptional

The ID of the created invoice.

statusstringOptional

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

conflicting_invoice_idstringOptional

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

itemsobjectOptional

The status of the line item ingestion process.

errorslist of stringsOptional

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

imageslist of objectsOptional

Attached invoice images. Only present if image_urls or raw_images were provided.

image_errorslist of objectsOptional

Errors from individual image uploads. The invoice is still created even if images fail.

Errors

400

Bad Request Error

403

Forbidden Error

500

Internal Server Error