Schemas

API reference

Every object in the public API. Fields typed … | null are always present in responses and may be null.

Address

Field	Type	Required	Description
street	string	yes	Street and house number.
postal_code	string	yes	Postal code.
city	string	yes	City.
country	string | null		Country code as printed, usually ISO 3166-1 alpha-2.

ClassifiedEmail

An e-mail that was classified as something other than a purchase order.

Field	Type	Required	Description
request_id	string	yes	Unique identifier for the request/email Format: uuid.
email_type	string	yes	The classified type of the email
sender	string	yes	Email address of the sender
from_name	string	yes	Display name of the sender
subject	string	yes	Email subject
timestamp	string	yes	When the email was received and classified Format: date-time.
metadata	object		Additional metadata about the email
message_id	string | null		RFC 5322 Message-ID (dedup key)
classification_reason	string | null		Why the classifier chose the type
rejection_status	string | null		Rejected-email triage: None (handled) | pending | overridden
original_email_type	string | null		Classifier's original type, preserved on operator override

Customer

A customer (debtor) record as stored in AIOTIC.

Field	Type	Required	Description
number	string	yes	Your customer (debtor) number — the key of this record.
id	string		Internal identifier, generated by AIOTIC. Format: uuid.
name	string | null		Company name
postal_code	string | null		Postal code
city	string | null		City
address	string | null		Address
contact_person	string | null		Contact person
phone_number	string | null		Phone number
vat_number	string | null		BTW (VAT) number
email	string | null		Customer email
coc_number	string | null		Chamber of Commerce number
home_page	string | null		Company website URL
similarity	number | null		Match score, only populated in search results.
archived_at	string | null		Set when the record is archived because its name carries a legacy or closure marker (e.g. "formerly", "do not use"). Archived customers are never chosen by identification but still resolve when explicitly referenced.
superseded_by	string | null		Customer number this record redirects to, derived from a "see customer N" marker in the name (e.g. *** ZIE 12306 ***). Orders matched to this record are filed under the successor.

CustomerListResponse

A page of customers.

Field	Type	Required	Description
items	array of Customer	yes	List of customer objects
total	integer	yes	Total number of customers in the system
limit	integer	yes	Maximum number of customers returned in this response
offset	integer	yes	Number of customers skipped in this response

CustomerProduct

A mapping from a customer's own article code to one of your articles.

Field	Type	Required	Description
customer_number	string	yes	Customer identifier referencing the customers table
customer_item_number	string	yes	Customer's own item number for this product
item_number	string	yes	Supplier product item number
language_code	string	yes	Product language code
created_at	string	yes	When this mapping was created in AIOTIC Format: date-time.

CustomerProductListResponse

A page of customer item mappings.

Field	Type	Required	Description
items	array of CustomerProduct	yes
total	integer	yes
limit	integer	yes
offset	integer	yes

CustomerProductUpsert

Fields accepted when creating or updating a customer item mapping.

Field	Type	Required	Description
item_number	string	yes	Supplier product item number
language_code	string	yes	Product language code
created_at	string		When this mapping was created in AIOTIC Format: date-time.

CustomerSearchResponse

Customers matching a search, best match first.

Field	Type	Required	Description
items	array of Customer	yes	List of customer objects with similarity scores
total	integer	yes	Total number of customers in the system
limit	integer	yes	Maximum number of customers returned in this response

CustomerUpsert

Fields accepted when creating or updating a customer. All optional; the more you fill, the better identification works.

Field	Type	Required	Description
id	string | null		Unique customer identifier (UUID, auto-generated if not provided)
name	string | null		Company name
postal_code	string | null		Postal code
city	string | null		City
address	string | null		Address
contact_person	string | null		Contact person
phone_number	string | null		Phone number
vat_number	string | null		BTW (VAT) number
email	string | null		Customer email
coc_number	string | null		Chamber of Commerce number
home_page	string | null		Company website URL
similarity	number | null		Similarity score

EmailClassificationResponse

The category an uploaded e-mail would be classified as.

Field	Type	Required	Description
category	enum	yes	The category of the email Values: purchase_order, order_confirmation, invoice, delivery_note, quotation, receipt, credit_note, unknown.

ErpAddress

Postal address in the ERP hand-off payload (all keys present, values may be null).

Field	Type	Required	Description
street	string | null	yes	Street and house number.
postal_code	string | null	yes	Postal code as printed or as stored in your master record.
city	string | null	yes	City.
country	string | null	yes	Country code as printed, usually ISO 3166-1 alpha-2.

ErpCustomer

Field	Type	Required	Description
customer_id	string | null	yes	Your customer (debtor) number as synced via PUT /customer/{number}. null only when an operator explicitly sent an unidentified order.
company	string | null	yes	Customer company name.
contact_person	string | null	yes	Person who placed this order, as printed on the document (document-authoritative, not the master record).
email	string | null	yes	Customer e-mail address.
phone	string | null	yes	Customer phone number.
iban	string | null	yes	Bank account when printed on the order; usually null.
bic	string | null	yes	Bank identifier when printed on the order; usually null.
vat_id	string | null	yes	VAT registration number.
address	ErpAddress	yes	Customer (bill-to) postal address.

ErpOrderItem

One order line in the ERP hand-off payload (a fixed subset of OrderItem).

Field	Type	Required	Description
article_number	string | null	yes	Your article number (SKU) after resolution through your catalog and customer item mappings. null only on an explicit override send of an unresolved line.
description	string | null	yes	Line description as printed by the customer.
quantity	integer | null	yes	Ordered quantity in whole units. null only when the quantity was unreadable and an operator overrode the review.
unit	string | null	yes	Unit of measure as printed (ST, PCS, Stk, m, KG, …) — map it to your ERP's codes.
price	number | null	yes	Unit price as stated by the customer, or null.
currency	string | null	yes	Line currency, normally equal to the header currency.
line_total	number | null	yes	Line amount as printed (quantity × price), or null.

ErpPurchaseOrder

The purchase order as delivered to your ERP receive endpoint — the reviewed values with operator corrections applied. Keys are always present (null when unknown).

Field	Type	Required	Description
order_number	string	yes	The customer's purchase-order number as printed, with / replaced by -. Map it to the "your reference" / external document number of the sales order.
order_date	string | null	yes	Order date as an ISO YYYY-MM-DD string where the document allowed it; otherwise as printed.
delivery_date	string | null	yes	Requested delivery date (YYYY-MM-DD) or null. When the document stated a window it is already collapsed to a single date.
currency	string | null	yes	Currency code as printed on the document (e.g. EUR) or null.
total_price	number | null	yes	The document's printed total, which may include VAT, or the recalculated net sum when e-mail instructions changed lines. Informational — let your ERP compute totals.
additional_information	string | null	yes	Free text from the document and e-mail plus notes AIOTIC appends (e.g. the original printed total after a recalculation).
supplier	Supplier | null	yes	Your own company as configured for the tenant — identical on every order, never read from the document. Safe to ignore.
customer	ErpCustomer	yes	The identified customer (debtor). customer_id is your customer number; the address block is canonicalised from your master record on a confident match.
shipping_details	ErpShippingDetails	yes	Ship-to recipient and delivery instructions. Filled from the customer block when the document has no explicit delivery address.
items	array of ErpOrderItem	yes	One entry per order line, in document order. Lines without an ordered quantity (assortment listings) are already dropped.

ErpReceiveRequest

Body AIOTIC POSTs to your ERP receive endpoint.

Field	Type	Required	Description
request_id	string	yes	AIOTIC's order id (UUID). Stable across retries of the same send — use it as the idempotency key and store it on your sales order as external reference. Format: uuid.
purchase_order	ErpPurchaseOrder	yes	The reviewed purchase order with operator corrections applied. Every key below is always present; unknown values are null.

ErpReceiveResponse

Body your ERP receive endpoint must return. success is authoritative — AIOTIC ignores the HTTP status for the business outcome (a 500 with success: false and a success: true with 200 are both handled correctly; a non-JSON body is treated as a server error).

Field	Type	Required	Description
success	boolean	yes
order_number	string		Your ERP's reference for the created order; stored as erp_ref and shown to operators
error	string		Human-readable reason when success is false; shown to operators

ErpRecipient

Ship-to block in the ERP hand-off payload.

Field	Type	Required	Description
company	string | null	yes	Ship-to company name.
department	string | null	yes	Department or address line 2.
contact_person	string | null	yes	Ship-to contact for the carrier.
email	string | null	yes	Ship-to e-mail.
phone	string | null	yes	Ship-to phone.
address	ErpAddress	yes	Delivery address.

ErpSendResponse

Field	Type	Required	Description
success	boolean	yes
request_id	string	yes	Format: uuid.
data	ErpReceiveResponse	yes	The JSON body your ERP receive endpoint returned, verbatim.

ErpShippingDetails

Shipping section of the ERP hand-off payload.

Field	Type	Required	Description
recipient	ErpRecipient	yes	The ship-to block.
special_instructions	string | null	yes	Free-text delivery instructions ("deliver before noon", dock number).

ErrorResponse

Standard error body. detail is usually a string; a few endpoints return a structured object (documented per endpoint).

Field	Type	Required	Description
detail	string | object	yes

FetchAllEmailsResponse

Result of a manual mailbox fetch.

Field	Type	Required	Description
status	string	yes
emails_queued	integer	yes
emails_total	integer	yes
message	string	yes

HTTPValidationError

Request validation error (malformed parameters).

Field	Type	Required	Description
detail	array of ValidationError

OrderCustomer

The identified customer (debtor). customer_id is your customer number and is set only when AIOTIC resolved the customer with confidence.

Field	Type	Required	Description
customer_id	string | null
company	string	yes
contact_person	string | null
email	string | null
phone	string | null
branch	string | null		Issuing branch / location named on the document, when any
vat_id	string | null
iban	string | null
bic	string | null
address	Address	yes

OrderGroup

Field	Type	Required	Description
email_group_id	string	yes	Format: uuid.
message_id	string | null
order_count	integer	yes
orders	array of OrderStatus	yes

OrderItem

One order line as stored on the order (result.items[]).

Field	Type	Required	Description
article_number	string | null		Your (supplier-side) article number, resolved through the catalog and customer mappings where possible
customer_item_number	string | null		The customer's own article number as printed, when present
description	string | null
quantity	integer | null		Ordered quantity in whole units; null when unreadable (see quantity_state)
quantity_state	string | null		What the quantity column literally showed. Unrecognised rows keep an empty quantity and put the order in ATTENTION. Values: Valid, Empty, Zero, Unrecognised.
unit	string | null		Unit of measure as printed (e.g. ST, PCS, KG)
price	number | null		Unit price
currency	string | null
line_total	number | null

OrderListResponse

A page of orders, newest first.

Field	Type	Required	Description
items	array of OrderStatus	yes	List of order status objects
total	integer	yes	Total number of orders in the system
limit	integer	yes	Maximum number of orders returned in this response
offset	integer	yes	Number of orders skipped in this response

OrderRef

Reference to one child order of a split e-mail.

Field	Type	Required	Description
request_id	string	yes	Unique identifier for the child order Format: uuid.
status	OrderStatusValue	yes
order_label	string | null		Splitter-assigned label for the order

OrderRetryBody

Field	Type	Required	Description
hil_prompt	string | null

OrderStatus

The processing status of one order, with the extracted purchase order once available.

Field	Type	Required	Description
request_id	string	yes	Unique identifier for the request Format: uuid.
attachments	object		File names of the order with size and MIME type.
metadata	object		Extra form fields supplied at upload, plus source.
timestamp	string	yes	When this status was recorded Format: date-time.
status	OrderStatusValue	yes
result	PurchaseOrder | null		The extracted purchase order once processing finished; null before that and for failed orders.
state	object | null		Free-form processing details used by the AIOTIC app (validation notes, flags). Informational.
erp_ref	string | null		ERP-assigned order reference returned on successful send
email_group_id	string | null		Correlates orders from the same source email
order_label	string | null		Human-readable label, e.g. 'PO-12345' or 'Order 1 of 2'
retry_count	integer		Number of retry attempts for transient failures Default: 0.
next_retry_at	string | null		When to attempt next retry
last_error	string | null		Last error message from transient failure

OrderStatusValue

Order lifecycle status.

Values: QUEUED, PROCESSING, ATTENTION, PROCESSED, FAILED, RETRY_PENDING, MODIFIED, REPROCESSED, SENDING, SENT, CANCELED

OrderUploadBody

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

OrderUploadResponse

Result of an upload. When split is true, poll the child orders[] instead of request_id.

Field	Type	Required	Description
request_id	string	yes	Unique identifier for the uploaded document Format: uuid.
split	boolean		True when the upload was split into multiple orders; poll orders[] rather than request_id Default: false.
email_group_id	string | null		Correlation id for child orders when the email was split into multiple orders
orders	array of OrderRef | null		Child order references when the email was split into multiple orders

ProcessingWebhookRequest

Body of the optional processing webhook, sent when extraction completes (before any human review).

Field	Type	Required	Description
request_id	string	yes	Format: uuid.
purchase_order	PurchaseOrder	yes

Product

An article record (one per article number and language).

Field	Type	Required	Description
item_number	string	yes	Unique identifier for the product
language_code	string	yes	Language code for the product description
description	string | null		Product description
remark	string | null		Additional remarks about the product
created_at	string	yes	When this product was created in AIOTIC Format: date-time.

ProductListResponse

A page of products.

Field	Type	Required	Description
items	array of Product	yes
total	integer	yes
limit	integer	yes
offset	integer	yes

ProductUpsert

Fields accepted when creating or updating a product.

Field	Type	Required	Description
description	string	yes	Product description
remark	string | null		Additional remarks about the product
created_at	string		When this product was created in AIOTIC Format: date-time.

PurchaseOrder

The extracted purchase order as returned in OrderStatus.result. Every field is always present; optional fields are null, never omitted.

Field	Type	Required	Description
order_number	string	yes	Customer's PO number. / is replaced by -.
order_date	string	yes	ISO 8601 date (YYYY-MM-DD) where the document allowed it
delivery_date	string | null		Single requested delivery date (resolved from a window per tenant preference)
delivery_date_from	string | null		Lower bound when the document states a delivery window
delivery_date_to	string | null		Upper bound when the document states a delivery window
supplier	Supplier	yes
customer	OrderCustomer | null
shipping_details	ShippingDetails | null
items	array of OrderItem	yes
total_price	number | null
currency	string | null
additional_information	string | null		Free text from the document / e-mail, plus audit notes AIOTIC appends (e.g. original document total)

RawEmailClassifyBody

Field	Type	Required	Description
file	string	yes

RawEmailUploadBody

Field	Type	Required	Description
file	string	yes
request_id	string | null

RawUploadRejection

Field	Type	Required	Description
detail	string | object	yes

RejectedEmailListResponse

A page of rejected e-mails.

Field	Type	Required	Description
items	array of ClassifiedEmail		Rejected emails on this page
total	integer	yes	Total rejected emails matching the rejection_status filter
limit	integer	yes	Page size
offset	integer	yes	Pagination offset

ReprocessResponse

Result of forcing a rejected e-mail through order processing.

Field	Type	Required	Description
request_id	string	yes	The request being reprocessed (reuses the original id) Format: uuid.
status	string	yes	Outcome, e.g. 'reprocessing'

ShippingDetails

Field	Type	Required	Description
recipient	ShippingRecipient	yes	The ship-to block.
special_instructions	string | null		Free-text delivery instructions.

ShippingRecipient

Field	Type	Required	Description
company	string	yes	Ship-to company name.
contact_person	string | null		Ship-to contact for the carrier.
department	string | null		Department or address line 2.
email	string | null		Ship-to e-mail.
phone	string | null		Ship-to phone.
address	Address	yes	Delivery address.

Supplier

The receiving company — your company. Pinned from tenant configuration, not extracted per document.

Field	Type	Required	Description
company	string	yes	Your company name as configured for the tenant.
contact_person	string | null		Contact person configured for the tenant, if any.
email	string | null		Order intake e-mail address of the tenant.
address	Address	yes	Your company address as configured.

SystemStatus

Field	Type	Required	Description
status	enum	yes	Values: operational, degraded, unknown.
message	string | null
updated_at	string | null		Format: date-time.

ValidationError

One request validation problem.

Field	Type	Required	Description
loc	array of string | integer	yes
msg	string	yes
type	string	yes
input	object
ctx	object