Orders — intake

API reference

Submit documents or raw e-mails for extraction. All uploads return a request_id immediately; processing runs in the background — continue with the status endpoints. Guide: Submitting documents.

Upload document(s) as one order

POST/order/uploadintegration key

Upload one or more files (PDF, JPG, PNG, TXT, MD) that together form one purchase order. Files are stored and queued; extraction runs in the background.

Provide your own request_id (UUID v4) to make the call idempotent and to correlate the order in your own systems.
Any additional multipart form field is stored as metadata on the order and echoed back by the status endpoints — use it for your own references.
Multiple files are never split into multiple orders on this endpoint. Use /order/raw/upload for e-mails that may contain several orders.

Request body — multipart/form-data

Field	Type	Required	Description
`files`	array of string	yes
`request_id`	string \| null

Responses

Status	Description	Body
`200`	Files accepted and queued	OrderUploadResponse
`400`	Invalid request (malformed UUID, unsupported file, …)	ErrorResponse
`401`	Missing or invalid API key	ErrorResponse
`404`	Resource not found	ErrorResponse
`415`	Unsupported media type	ErrorResponse
`422`	Validation Error	HTTPValidationError
`503`	Tenant not initialised yet (no configuration deployed)	ErrorResponse

curlPython SDKResponse

bash

curl -X POST "https://acme.aiotic.ai/order/upload" -H "X-API-Key: $AIOTIC_API_KEY"

python

up = client.orders.upload(["PO-4711.pdf"], request_id=uuid.uuid4(), metadata={"my_ref": "TICKET-1"})
status = client.orders.wait(up.request_id)

json

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "split": false
}

Upload a raw e-mail (.eml)

POST/order/raw/uploadintegration key

Submit a complete e-mail (.eml). AIOTIC classifies it; if it is a purchase order the attachments and body are extracted. If the tenant has order splitting enabled and the e-mail carries several orders, the response has split: true and one child order per detected order — poll the children, not the source request_id.

A non-purchase-order e-mail is rejected with 400 and a structured detail object (error: not_a_purchase_order, the detected category, …) and is recorded in the rejected-e-mails list so an operator can override the decision.

Request body — multipart/form-data

Field	Type	Required	Description
`file`	string	yes
`request_id`	string \| null

Responses

Status	Description	Body
`200`	Accepted (single order or split children)	OrderUploadResponse
`400`	Invalid file, or the e-mail is not a purchase order (structured `detail`)	RawUploadRejection
`401`	Missing or invalid API key	ErrorResponse
`404`	Resource not found	ErrorResponse
`422`	A split was predicted but no child order could be prepared	ErrorResponse
`503`	Classification not configured on this tenant yet	ErrorResponse

curlPython SDKResponse

bash

curl -X POST "https://acme.aiotic.ai/order/raw/upload" -H "X-API-Key: $AIOTIC_API_KEY"

python

up = client.orders.upload_raw_email("mail.eml")       # AioticValidationError with structured detail for non-orders
for rid in up.request_ids:                             # children when split
    client.orders.wait(rid)

json

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "split": false
}

Classify a raw e-mail without processing it

POST/order/raw/classifyintegration key

Returns the category the classifier would assign (purchase_order, invoice, quotation, …). Nothing is stored or queued.

Request body — multipart/form-data

Field	Type	Required	Description
`file`	string	yes

Responses

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

curlPython SDK

bash

curl -X POST "https://acme.aiotic.ai/order/raw/classify" -H "X-API-Key: $AIOTIC_API_KEY"

python

client.orders.classify_raw_email("mail.eml").category   # 'purchase_order' | 'quotation' | …

Get all orders from one source e-mail

GET/order/group/{email_group_id}integration key

Aggregate view of a split e-mail — the correlation id, the message id and every child order's status.

Parameters

Name	In	Type	Required	Description
`email_group_id`	path	string	yes	Correlation id shared by all child orders of one split e-mail

Responses

Status	Description	Body
`200`	Group with child orders	OrderGroup
`404`	Resource not found	ErrorResponse
`422`	Validation Error	HTTPValidationError

curlPython SDK

bash

curl -X GET "https://acme.aiotic.ai/order/group/<email_group_id>" -H "X-API-Key: $AIOTIC_API_KEY"

python

group = client.orders.group(email_group_id)      # .orders: list[OrderStatus]

Download an order file

GET/order/{request_id}/{filename}integration key

Returns one file belonging to the order: an original upload (by its file name) or a generated artifact such as latest_result.json (the extracted purchase order). The Content-Type follows the file extension.

Parameters

Name	In	Type	Required	Description
`request_id`	path	string	yes	The order's id (UUID) as returned by the upload endpoints
`filename`	path	string	yes	File name as listed in the order's `attachments`, or `latest_result.json`

Responses

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

curlPython SDK

bash

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

python

pdf = client.orders.download_file(request_id, "PO-4711.pdf")
result = client.orders.download_file(request_id, "latest_result.json")

Preview an order file

GET/order/{request_id}/{filename}/previewintegration key

Same as the download endpoint but with an inline Content-Disposition, for showing a PDF or image inside your own review UI.

Parameters

Name	In	Type	Required	Description
`request_id`	path	string	yes	The order's id (UUID) as returned by the upload endpoints
`filename`	path	string	yes	File name as listed in the order's `attachments`, or `latest_result.json`

Responses

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

curlPython SDK

bash

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

python

data = client.orders.download_file(request_id, "PO-4711.pdf", preview=True)

Retry a failed order

POST/order/retry/{request_id}integration key

Re-runs processing for an order in FAILED status by creating a new order with the same files. The original moves to REPROCESSED; the response carries the new request_id — track that one from now on.

Parameters

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

Request body — application/x-www-form-urlencoded

Field	Type	Required	Description
`hil_prompt`	string \| null

Responses

Status	Description	Body
`200`	New order queued	OrderUploadResponse
`400`	Order is not in `FAILED` status, or has no files to retry	ErrorResponse
`401`	Missing or invalid API key	ErrorResponse
`404`	Resource not found	ErrorResponse
`422`	Validation Error	HTTPValidationError

curlPython SDK

bash

curl -X POST "https://acme.aiotic.ai/order/retry/<request_id>" -H "X-API-Key: $AIOTIC_API_KEY"

python

new = client.orders.retry(request_id)            # track new.request_id from now on

Orders — intake ​

Upload document(s) as one order ​

Upload a raw e-mail (.eml) ​

Classify a raw e-mail without processing it ​

Get all orders from one source e-mail ​

Download an order file ​

Preview an order file ​

Retry a failed order ​

Orders — intake

Upload document(s) as one order

Upload a raw e-mail (.eml)

Classify a raw e-mail without processing it

Get all orders from one source e-mail

Download an order file

Preview an order file

Retry a failed order