Skip to navigation
API ReferenceInvoices

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.

Authentication

AuthorizationBearer
OAuth2 authentication flows. Auth server URLs will vary by environment

Headers

X-Api-KeystringRequired
API key for authentication
X-API-VersionstringOptional

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

Idempotency-KeystringOptionalformat: "^[A-Za-z0-9._\-+=/]{1,128}$"<=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>=1 character
A mandatory unique identifier for creating an invoice.
ottimate_location_idintegerRequired
The ID of the location for this invoice.
erp_vendor_idstringOptional>=1 character
The ERP ID of the vendor for this invoice.
invoice_numberstringOptional>=1 character
invoice_datestringOptionalformat: "date"
due_datestringOptionalformat: "date"
posting_datestringOptionalformat: "date"
total_amountdoubleOptional
total_taxdoubleOptional
purchase_orderstringOptional>=1 character
notesstringOptional1-1024 characters
currencystringOptional1-3 characters
typeenumOptional
Type of document.
Allowed values:
dimensionsmap from strings to strings 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_fieldsmap from strings to any 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

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, write-only. Marks an already-processed invoice as approved + exported, skipping Ottimate’s approval workflow. archived: already paid — filed as historical/inactive, excluded from billpay/autopay. verified: not paid — stays active and payable via billpay/autopay. Choose carefully: sending verified for an already-paid invoice risks double payment. 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
422
Unprocessable Entity Error
500
Internal Server Error