Appearance
Customers
API reference
Your debtors. Keyed on your customer number, which AIOTIC returns as customer.customer_id on orders. Accepts the sync key. Guide: Reference data · Event-driven sync.
List customers
GET/customer/listintegration or sync key
List all customers with pagination.
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 | CustomerListResponse |
404 | Resource not found | ErrorResponse |
422 | Validation Error | HTTPValidationError |
bash
curl -X GET "https://acme.aiotic.ai/customer/list?page=1&size=100" -H "X-API-Key: $AIOTIC_API_KEY"python
for c in client.customers.iter_all(): ...Search customers (semantic)
GET/customer/search/{query}integration or sync key
Fuzzy search over name, address and contact fields, comparable to how AIOTIC matches the sender of an order to your customer records. Handy to check how well your master data resolves.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
query | path | string | yes | Search query text |
top_k | query | integer | Top items by similarity score Default 10. Min 1. Max 1000. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Successful Response | CustomerSearchResponse |
404 | Resource not found | ErrorResponse |
422 | Validation Error | HTTPValidationError |
bash
curl -X GET "https://acme.aiotic.ai/customer/search/<query>?top_k=10" -H "X-API-Key: $AIOTIC_API_KEY"python
client.customers.search("lumitech apeldoorn", top_k=3).itemsGet a customer
GET/customer/{customer_number}integration or sync key
Get a specific customer by ID.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
customer_number | path | string | yes | Unique customer number |
Responses
| Status | Description | Body |
|---|---|---|
200 | Successful Response | Customer |
404 | Resource not found | ErrorResponse |
422 | Validation Error | HTTPValidationError |
bash
curl -X GET "https://acme.aiotic.ai/customer/<customer_number>" -H "X-API-Key: $AIOTIC_API_KEY"python
client.customers.get("58931")Create or update a customer (upsert)
PUT/customer/{customer_number}integration or sync key
Idempotent upsert keyed on your customer (debtor) number. The number is what AIOTIC returns as customer.customer_id on every order it identifies for this customer. Populate as many fields as you have — name, address, VAT, e-mail and phone all improve identification. Response status is 202 Accepted.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
customer_number | path | string | yes | Unique customer number |
Request body — application/json
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 |
Responses
| Status | Description | Body |
|---|---|---|
202 | Successful Response | Customer |
404 | Resource not found | ErrorResponse |
422 | Validation Error | HTTPValidationError |
bash
curl -X PUT "https://acme.aiotic.ai/customer/<customer_number>" -H "X-API-Key: $AIOTIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id":"550e8400-e29b-41d4-a716-446655440000","name":"string","postal_code":"string","city":"string","address":"string","contact_person":"string","phone_number":"string","vat_number":"string","email":"string","coc_number":"string","home_page":"string","similarity":1}'python
client.customers.upsert("58931", {"name": "LUMITECH INSTALLATIES", "city": "Apeldoorn", "vat_number": "NL001234567B01"})
# or, only-when-changed via the sync engine:
engine.apply(ChangeEvent.customer_upsert("58931", name="LUMITECH INSTALLATIES", city="Apeldoorn"))Delete a customer
DELETE/customer/{customer_number}integration or sync key
Remove a customer. Prefer deleting over leaving inactive records — stale records can be matched by mistake. (Renaming a record with a "formerly / do not use" marker archives it instead.)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
customer_number | path | string | yes | Unique customer number |
Responses
| Status | Description | Body |
|---|---|---|
204 | Successful Response | — |
404 | Resource not found | ErrorResponse |
422 | Validation Error | HTTPValidationError |
bash
curl -X DELETE "https://acme.aiotic.ai/customer/<customer_number>" -H "X-API-Key: $AIOTIC_API_KEY"python
client.customers.delete("58931")