PlateIQ invoices API

openapi: 3.1.0
info:
  title: API Reference accounts invoices API
  version: 1.0.0
servers:
- url: https://api.ottimate.com/v1
  description: Production
- url: https://sandbox-api.ottimate.com/v1
  description: Sandbox
tags:
- name: invoices
paths:
  /invoices:
    get:
      operationId: get-invoices-root
      summary: Retrieve paginated list of invoices
      description: '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 (approved, incomplete, processing, etc.)


        ### Pagination

        Results are returned in pages with configurable size (1-100 items per page). Results are ordered by creation date (newest first).'
      tags:
      - invoices
      parameters:
      - name: page
        in: query
        description: Page number for pagination
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Number of items per page
        required: false
        schema:
          type: integer
      - name: date_from
        in: query
        description: '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.'
        required: false
        schema:
          type: string
      - name: date_from_utc
        in: query
        description: 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.
        required: false
        schema:
          type: string
          format: date-time
      - name: date_to
        in: query
        description: '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.'
        required: false
        schema:
          type: string
      - name: date_to_utc
        in: query
        description: 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.
        required: false
        schema:
          type: string
          format: date-time
      - name: status
        in: query
        description: Filter by invoice status
        required: false
        schema:
          $ref: '#/components/schemas/InvoicesGetParametersStatus'
      - name: ottimate_location_ids
        in: query
        description: Filter by a comma-separated list of location IDs
        required: false
        schema:
          type: string
      - name: payment_status
        in: query
        description: Filter by payment status
        required: false
        schema:
          $ref: '#/components/schemas/InvoicesGetParametersPaymentStatus'
      - name: ottimate_vendor_id
        in: query
        description: Filter by specific vendor ID
        required: false
        schema:
          type: string
      - name: expand
        in: query
        description: '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.'
        required: false
        schema:
          type: string
      - name: invoice_ids
        in: query
        description: Filter by a comma-separated list of invoice IDs
        required: false
        schema:
          type: string
      - name: search
        in: query
        description: Search across multiple invoice fields
        required: false
        schema:
          type: string
      - name: custom_fields
        in: query
        description: 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.
        required: false
        schema:
          type: string
      - name: last_modified_date_from
        in: query
        description: '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.'
        required: false
        schema:
          type: string
      - name: last_modified_date_from_utc
        in: query
        description: 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.
        required: false
        schema:
          type: string
      - name: last_modified_date_to
        in: query
        description: '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.'
        required: false
        schema:
          type: string
      - name: last_modified_date_to_utc
        in: query
        description: 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.
        required: false
        schema:
          type: string
      - name: last_modified_user_id
        in: query
        description: Filter invoices by the ID of the user who last modified them
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: OAuth2 authentication flows. Auth server URLs will vary by environment
        required: true
        schema:
          type: string
      - name: X-Api-Key
        in: header
        description: API key for authentication
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response with paginated invoice list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoices_get_invoices_root_Response_200'
        '400':
          description: Bad request - Invalid parameters provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Access denied or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Server-side processing error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /invoices/{id}:
    get:
      operationId: get-invoices-id
      summary: Retrieve detailed information for a specific invoice
      description: "Returns **comprehensive details** for a single invoice including all metadata, processing information, and payment status.\n\n## \U0001F4CB What You Get\n\nThis endpoint provides the **complete invoice record** with:\n\n- \U0001F9FE **Full invoice metadata** (dates, amounts, status)\n- \U0001F3E2 **Vendor information** and contact details\n- \U0001F4CD **Location** where invoice was received\n- \U0001F4B3 **Payment information** (when invoice is paid)\n- ⚠️ **Error details** (if invoice has processing issues)\n- \U0001F4E4 **Export tracking** (integration status)\n\n## \U0001F50D Usage Examples\n\n### Basic Retrieval\n```bash\ncurl -H \"X-Api-Key: your-api-key\" \\\n     https://api.acme.com/v1/invoices/550e8400-e29b-41d4-a716-446655440000\n```\n\n### With Version Header\n```bash\ncurl -H \"X-Api-Key: your-api-key\" \\\n     -H \"X-API-Version: 1.0.0\" \\\n     https://api.acme.com/v1/invoices/550e8400-e29b-41d4-a716-446655440000\n```\n\n## ⚡ Performance Notes\n\n- **Response time**: Typically < 100ms\n- **Caching**: Results cached for 5 minutes\n- **Rate limits**: Applies to your overall API quota\n\n> \U0001F4A1 **Tip**: Use this endpoint after getting results from the list endpoint to get full details for specific invoices."
      tags:
      - invoices
      parameters:
      - name: id
        in: path
        description: Invoice UUID - Unique identifier of the invoice to retrieve
        required: true
        schema:
          type: string
      - name: expand
        in: query
        description: 'Comma-separated list of fields to expand. Options: `history`, `gl_splits`. Use `history` to include the full audit log. Use `gl_splits` to include GL account splits (real splits or virtual splits derived from line-item mappings).'
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: OAuth2 authentication flows. Auth server URLs will vary by environment
        required: true
        schema:
          type: string
      - name: X-Api-Key
        in: header
        description: API key for authentication
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response with invoice details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceDetailObject'
        '400':
          description: Bad request - Invalid parameters or request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Access denied or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Server-side processing error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: patch-invoices-id
      summary: Update invoice header, line items, and dimensions
      description: 'Updates an invoice along with its line items and dimensions.


        ### Features

        - Update invoice header fields (date, amount, vendor, notes, etc.)

        - Create new line items (omit `id`)

        - Update existing line items (include `id`)

        - Set, update, or remove header and item-level dimensions

        - Update custom metadata fields at header and item level (requires account-level custom field spec configuration)


        ### Use Cases

        - Invoice corrections

        - Invoice reconciliation with updated line items

        - Adding or updating dimensions after initial invoice creation

        - Multi-field updates in a single request'
      tags:
      - invoices
      parameters:
      - name: id
        in: path
        description: Invoice ID to update
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: OAuth2 authentication flows. Auth server URLs will vary by environment
        required: true
        schema:
          type: string
      - name: X-Api-Key
        in: header
        description: API key for authentication
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Invoice updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceDetailObject'
        '400':
          description: Bad request - Invalid parameters or request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Access denied or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed - concurrent modification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Server-side processing error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Invoice update payload with optional items array
        content:
          application/json:
            schema:
              type: object
              properties:
                ottimate_location_id:
                  type: integer
                  description: The ID of the location for this invoice.
                erp_vendor_id:
                  type: string
                  description: The ERP ID of the vendor for this invoice.
                erp_vendor_name:
                  type: string
                  description: ERP vendor name. Required when creating a new vendor via erp_vendor_id.
                invoice_number:
                  type: string
                invoice_date:
                  type: string
                  format: date
                due_date:
                  type: string
                  format: date
                posting_date:
                  type: string
                  format: date
                total_amount:
                  type: number
                  format: double
                total_tax:
                  type: number
                  format: double
                discount_amount:
                  type: number
                  format: double
                purchase_order:
                  type: string
                notes:
                  type: string
                currency:
                  type: string
                type:
                  $ref: '#/components/schemas/InvoicesIdPatchRequestBodyContentApplicationJsonSchemaType'
                  description: Type of document.
                dimensions:
                  $ref: '#/components/schemas/InvoicesIdPatchRequestBodyContentApplicationJsonSchemaDimensions'
                  description: Header-level dimension mappings. Keys are dimension types (e.g., 'DEPARTMENT') and values are `erp_dimension_id` strings from the `GET /dimensions` endpoint. Replaces all header dimensions with the provided set. Omit the field entirely to preserve existing dimensions. Pass `{}` to clear all header dimensions.
                custom_fields:
                  oneOf:
                  - $ref: '#/components/schemas/InvoicesIdPatchRequestBodyContentApplicationJsonSchemaCustomFields'
                  - type: 'null'
                  description: 'Header-level custom metadata fields. Replaces the stored custom fields with the provided object — any keys not included are reset to their configured default values.


                    **Requirements**: 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**: Omit the field entirely to preserve existing custom fields.'
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/InvoicesIdPatchRequestBodyContentApplicationJsonSchemaItemsItems'
                  description: Line items to create or update. Include `id` to update an existing item, omit `id` to create a new item.
                image_urls:
                  type: array
                  items:
                    type: string
                    format: uri
                  description: 'Replaces all existing invoice images with the provided URLs. Pass an empty array to delete all images. Omit the field entirely to leave existing images unchanged. Supported formats: PDF, JPG, JPEG, PNG.'
                raw_images:
                  type: array
                  items:
                    $ref: '#/components/schemas/InvoicesIdPatchRequestBodyContentApplicationJsonSchemaRawImagesItems'
                  description: 'Replaces all existing invoice images with the provided base64-encoded images. Pass an empty array to delete all images. Omit the field entirely to leave existing images unchanged. Supported formats: PDF, JPG, JPEG, PNG.'
  /invoices/upload:
    post:
      operationId: post-invoices-upload
      summary: Create invoice from file upload or URL download
      description: 'Creates a new invoice by uploading a file directly or downloading from a URL. This endpoint combines file processing, S3 storage, and invoice creation in a single API call.


        ### File Processing

        - Multiple formats supported: PDF, JPG, PNG, TIFF

        - Direct file upload via multipart form data

        - URL-based file download and ingestion

        - Automatic format and size validation

        - Secure S3 storage integration


        ### Invoice Creation Features

        - Single-step upload and creation process

        - Custom metadata support for tracking

        - Location assignment

        - Email sender tracking

        - Integration with existing document processing pipeline


        ### Use Cases

        - Email attachment processing

        - Mobile application file uploads

        - Webhook-based ingestion from vendor portals

        - Programmatic batch processing


        ### Technical Specifications

        - File size limit: 25MB per file

        - Supported formats: PDF, JPG, JPEG, PNG, TIFF

        - Authentication: API key required

        - Access control: Location-level validation

        - Storage: Automatic S3 upload with encryption'
      tags:
      - invoices
      parameters:
      - name: Authorization
        in: header
        description: OAuth2 authentication flows. Auth server URLs will vary by environment
        required: true
        schema:
          type: string
      - name: X-Api-Key
        in: header
        description: API key for authentication
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.'
        required: false
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        description: '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](https://docs.ottimate.com/idempotency) for full details.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Invoice created successfully. Returns the reference ID for the uploaded document. Invoice processing happens asynchronously.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceCreationResponse'
        '400':
          description: Bad request - Invalid request data or file format. Common causes include missing required fields, invalid file format, file too large, or invalid location ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Access denied or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large - File exceeds maximum size limit of 25MB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity - Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Server-side processing error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Invoice creation data - supports both file upload and URL-based ingestion
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                ottimate_location_id:
                  type: integer
                  description: Location ID where invoice should be processed
                file:
                  type: string
                  format: binary
                  description: Invoice file to upload (PDF, JPG, PNG, TIFF) - max 25MB
                filename:
                  type: string
                  description: Original filename (optional, derived from file if not provided)
                metadata:
                  type: string
                  description: JSON string containing additional invoice metadata
                created_email:
                  type: string
                  format: email
                  description: Email address of invoice sender (for tracking)
              required:
              - ottimate_location_id
              - file
  /invoices/mark-exported:
    post:
      operationId: post-invoices-mark-exported
      summary: Mark multiple invoices as exported
      description: ''
      tags:
      - invoices
      parameters:
      - name: Authorization
        in: header
        description: OAuth2 authentication flows. Auth server URLs will vary by environment
        required: true
        schema:
          type: string
      - name: X-Api-Key
        in: header
        description: API key for authentication
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.'
        required: false
        schema:
          type: string
      - name: X-Export-Batch-Id
        in: header
        description: Optional export batch identifier used for logging
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Operation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkInvoiceOperationResponse'
        '400':
          description: Bad request - Invalid parameters or request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Access denied or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Server-side processing error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Bulk export request payload
        content:
          application/json:
            schema:
              type: object
              properties:
                invoices:
                  type: array
                  items:
                    $ref: '#/components/schemas/InvoicesMarkExportedPostRequestBodyContentApplicationJsonSchemaInvoicesItems'
                export_transaction_id:
                  type: string
                  description: Batch-level transaction ID for all invoices
                marked_reason:
                  type: string
                  description: Batch-level reason for all invoices
              required:
              - invoices
  /invoices/mark-unexported:
    post:
      operationId: post-invoices-mark-unexported
      summary: Unexport multiple invoices
      description: ''
      tags:
      - invoices
      parameters:
      - name: Authorization
        in: header
        description: OAuth2 authentication flows. Auth server URLs will vary by environment
        required: true
        schema:
          type: string
      - name: X-Api-Key
        in: header
        description: API key for authentication
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Operation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkInvoiceUnexportOperationResponse'
        '400':
          description: Bad request - Invalid parameters or request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Access denied or insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error - Server-side processing error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Bulk unexport request payload
        content:
          application/json:
            schema:
              type: object
              properties:
                invoices:
                  type: array
                  items:
                    $ref: '#/components/schemas/InvoicesMarkUnexportedPostRequestBodyContentApplicationJsonSchemaInvoicesItems'
                marked_reason:
                  type: string
                  description: Batch-level reason for all invoices
                flag_invoice:
                  type: boolean
                  description: Flag the invoice as unexported
              required:
              - invoices
  /invoices/uploads:
    get:
      operationId: get-invoices-uploads
      summary: Retrieve uploads
      description: Returns a list of uploads that have been uploaded but not yet processed.
      tags:
      - invoices
      parameters:
      - name: ottimate_location_id
        in: query
        description: Filter by a specific location ID
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: OAuth2 authentication flows. Auth server URLs will vary by environment
        required: true
        schema:
          type: string
      - name: X-Api-Key
        in: header
        description: API key for authentication
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response with a list of uploads
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoices_get_invoices_uploads_Response_200'
        '401':
          description: Unauthorized - Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /invoices/{id}/approvers:
    get:
      operationId: get-invoices-id-approvers
      summary: Retrieve list of approvers for a specific invoice
      description: 'Returns a list of all approvers assigned to an invoice, including their approval status.


        ### Features

        - View all assigned approvers for an invoice

        - Check approval status (pending, approved)

        - See approver details (name, email)

        - View policy-based and manual approvers


        ### Use Cases

        - Check who needs to approve an invoice

        - Monitor approval progress

        - Audit approval chain'
      tags:
      - invoices
      parameters:
      - name: id
        in: path
        description: Invoice ID
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: OAuth2 authentication flows. Auth server URLs will vary by environment
        required: true
        schema:
          type: string
      - name: X-Api-Key
        in: header
        description: API key for authentication
        required: true
        schema:
          type: string
      - name: X-API-Version
        in: header
        description: 'API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response with list of approvers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoices_get_invoices_id_approvers_Response_200'
        '401':
          description: Unauthorized - Authentication required or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Access denied or insufficient permissions
          content:
            application/json:
              schema:


# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/plateiq/refs/heads/main/openapi/plateiq-invoices-api-openapi.yml