Orders — status & files

API reference

Read processing status and the extracted purchase order, list orders, download files. Guide: Polling & notifications · Order lifecycle.

Get order status and extracted data

GET/order_status/{request_id}integration key

The current lifecycle status of an order plus, once processing finished, the extracted purchase order in result. Also carries erp_ref after a successful ERP send, last_error / retry_count / next_retry_at for transient failures, and the email_group_id / order_label when the order came from a split e-mail.

Parameters

Name	In	Type	Required	Description
request_id	path	string	yes	The order's id (UUID) as returned by the upload endpoints

Responses

Status	Description	Body
200	Order status	OrderStatus
400	Invalid request (malformed UUID, unsupported file, …)	ErrorResponse
401	Missing or invalid API key	ErrorResponse
404	Resource not found	ErrorResponse
422	Validation Error	HTTPValidationError

curl

curl -X GET "https://acme.aiotic.ai/order_status/<request_id>" -H "X-API-Key: $AIOTIC_API_KEY"

Python SDK

status = client.orders.get(request_id)
status.status, status.result, status.erp_ref

Response

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSED",
  "timestamp": "2026-03-14T10:30:00",
  "attachments": {
    "PO-4711.pdf": {
      "size": 125840,
      "mime_type": "application/pdf"
    }
  },
  "metadata": {
    "source": "api",
    "my_reference": "TICKET-8812"
  },
  "result": {
    "order_number": "PO-4711",
    "order_date": "2026-03-14",
    "delivery_date": "2026-03-21",
    "currency": "EUR",
    "total_price": 123.4,
    "supplier": {
      "company": "Acme Supplies BV",
      "contact_person": null,
      "email": null,
      "address": {
        "street": "Industrieweg 5",
        "postal_code": "1234 AB",
        "city": "Amsterdam",
        "country": "NL"
      }
    },
    "customer": {
      "customer_id": "58931",
      "company": "LUMITECH INSTALLATIES",
      "contact_person": "J. de Boer",
      "email": "info@lumitech.example",
      "phone": null,
      "branch": null,
      "vat_id": "NL001234567B01",
      "iban": null,
      "bic": null,
      "address": {
        "street": "Ambachtsweg 12",
        "postal_code": "7327 AA",
        "city": "Apeldoorn",
        "country": "NL"
      }
    },
    "shipping_details": null,
    "items": [
      {
        "article_number": "PROD-001",
        "customer_item_number": "LT-ART-001",
        "description": "LED Driver 48V",
        "quantity": 10,
        "quantity_state": "Valid",
        "unit": "ST",
        "price": 12.34,
        "currency": "EUR",
        "line_total": 123.4
      }
    ],
    "additional_information": null
  },
  "state": null,
  "erp_ref": null,
  "email_group_id": null,
  "order_label": "PO-4711",
  "retry_count": 0,
  "next_retry_at": null,
  "last_error": null
}

List orders (paginated, newest first)

GET/order_status/listintegration key

Paginated list of orders with their status. There is no server-side filter or updated_since parameter today — poll the first page(s) and track transitions locally (the Python SDK's OrderWatcher does exactly this).

Parameters

Name	In	Type	Required	Description
page	query	integer		Page number Default 1. Min 1.
size	query	integer		Items per page Default 100. Min 1. Max 1000.

Responses

Status	Description	Body
200	Successful Response	OrderListResponse
404	Resource not found	ErrorResponse
422	Validation Error	HTTPValidationError

curl

curl -X GET "https://acme.aiotic.ai/order_status/list?page=1&size=100" -H "X-API-Key: $AIOTIC_API_KEY"

Python SDK

page = client.orders.list(page=1, size=100)
for order in client.orders.iter_all(size=200, max_pages=5): ...