v1

latestOpenAPI 3.1.02026-08-0458234268.6 KB
invoices

Retrieve paginated list of invoices

Returns a paginated list of invoices with comprehensive filtering capabilities.

Filtering Options

  • Date range filtering by creation date (from/to dates)
  • Date range filtering by last modified date (last_modified_date_from/last_modified_date_to)
  • Filter by the user who last modified the invoice (last_modified_user_id)
  • Vendor filtering by name or ID
  • Location filtering by ottimate_location_id
  • Status filtering (processing, needs-attention, pending-approval, ready-for-export, exported, inactive)

Pagination

Results are returned in pages with configurable size (1-100 items per page). Results are ordered by creation date (newest first).

get/invoices

Query parameters

pageinteger

Page number for pagination

limitinteger

Number of items per page

date_fromstring

Filter invoices from this date. Accepted formats: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. All times are interpreted as UTC. When using expand=items, either date_from or last_modified_date_from is required.

date_from_utcstring date-time

UTC filter. Accepts ISO 8601 with optional Z/offset, or YYYY-MM-DD[ HH:MM:SS] (assumed UTC). Takes precedence over the non-_utc variant.

date_tostring

Filter invoices to this date. Accepted formats: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. All times are interpreted as UTC. When using expand=items and omitted, defaults to the current UTC datetime.

date_to_utcstring date-time

UTC filter. Accepts ISO 8601 with optional Z/offset, or YYYY-MM-DD[ HH:MM:SS] (assumed UTC). Takes precedence over the non-_utc variant.

status'processing' | 'needs-attention' | 'pending-approval' | 'ready-for-export' | 'exported' | 'inactive' | 'approved' | 'incomplete' | 'archived'

Filter by invoice status. Supported values: processing, needs-attention, pending-approval, ready-for-export, exported, inactive. Values approved, incomplete, and archived are legacy — use the supported values above instead.

ottimate_location_idsstring

Filter by a comma-separated list of location IDs

payment_status'paid' | 'partial' | 'unpaid'

Filter by payment status

ottimate_vendor_idstring

Filter by specific vendor ID. With X-API-Version: 1.1.0 this is the accounting vendor id (matches the id from GET /vendors); for 1.0.0/unversioned it is the operational vendor id.

erp_vendor_namestring

Filter by ERP vendor name (case-insensitive partial match).

expandstring

Comma-separated list of fields to expand. Options: items. When used, returns full line item details along with catalog entry details. Requires date_from or last_modified_date_from (within a 30-day window); date_to and last_modified_date_to are optional and default to the current datetime if omitted.

invoice_idsstring

Filter by a comma-separated list of invoice IDs

searchstring

Search across multiple invoice fields

custom_fieldsstring

Filter by custom field values. Pass a JSON object where each key is a custom field name and each value is the exact value to match. Multiple keys are ANDed together.

last_modified_date_fromstring

Filter invoices last modified on or after this date. Accepted formats: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. All times are interpreted as UTC. When using expand=items, either last_modified_date_from or date_from is required.

last_modified_date_from_utcstring

UTC filter. Accepts ISO 8601 with optional Z/offset, or YYYY-MM-DD[ HH:MM:SS] (assumed UTC). Takes precedence over the non-_utc variant.

last_modified_date_tostring

Filter invoices last modified on or before this date. Accepted formats: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. All times are interpreted as UTC. When using expand=items and omitted, defaults to the current UTC datetime.

last_modified_date_to_utcstring

UTC filter. Accepts ISO 8601 with optional Z/offset, or YYYY-MM-DD[ HH:MM:SS] (assumed UTC). Takes precedence over the non-_utc variant.

last_modified_user_idinteger

Filter invoices by the ID of the user who last modified them

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.

Response

Successful response with paginated invoice list

versionstring required

API version

countinteger required

Total number of invoices matching the query