API v1 reference
Every endpoint of the REST API with its method, path and required scope, generated from the same OpenAPI document the API serves.
GET https://<workspace>.zmle.com/api/v1/me
Quickstart
- Open an instant demo: a workspace with sample data
- In the demo, go to Admin → Integrations & API and create a key
- Call GET /api/v1/me with the key (below) to see which workspace and person it belongs to
- Add a webhook endpoint and choose events; in a demo, deliveries are logged but never sent
OpenAPI document
The full specification is public; no key is needed to read it: https://zmle.com/api/v1/openapi.json
curl https://<your-demo>.zmle.com/api/v1/me \ -H "Authorization: Bearer $ZMLE_API_KEY"
Base address
Each workspace answers at its own address: https://<workspace>.zmle.com/api/v1 (or its own domain). The API host https://api.zmle.com/v1 finds the workspace from the key.
Authentication
Send the key as Authorization: Bearer <key> (or X-Api-Key). Native and connected apps use OAuth 2.1 with PKCE and short-lived app tokens.
Lists and paging
Lists take page and per (1–100, default 25), q for search and since for changes after a date. The answer carries total and pages, plus Link and X-Total-Count headers.
Errors
Errors are JSON: { error: { code, message } } with the HTTP status. Every answer has an X-Request-Id. POST requests accept an Idempotency-Key header. Each key has a bucket of 300 requests refilled at 5 per second; X-RateLimit-Remaining shows what is left, and 429 comes with Retry-After.
Versions and deprecation
v1 only grows: new routes and fields are added, nothing is removed or renamed inside v1. A route that will go away is marked deprecated at least 12 months before it stops; until then it works unchanged and answers with Deprecation and Sunset headers.
TypeScript client
An official TypeScript client generated from the OpenAPI document is being prepared (typed methods, retries with Retry-After, idempotency keys, paging). Until it is published, any OpenAPI generator works with openapi.json.
Error codes
| Status | Code | Meaning |
|---|---|---|
400 | invalid_json | The body is not valid JSON |
401 | unauthenticated | No key or token was sent |
401 | invalid_key | The key is unknown, revoked or expired, or an MCP token was used on the REST API |
401 | token_expired | The app token has expired: refresh it |
403 | insufficient_scope | The key lacks the scope this route needs |
403 | forbidden | The key's person may not open this area or record |
403 | origin_not_allowed | A browser call from a site that is not on the workspace's allowed origins |
403 | ip_not_allowed | The key's IP allow-list does not include this address |
403 | test_mode_read_only | A test key tried to change data: test keys only read |
404 | not_found | No such record or route in this workspace |
409 | conflict | The request clashes with the current state, for example a duplicate |
422 | validation_failed | Fields failed validation; the answer lists the problems per field |
429 | rate_limited | Too many requests: wait for the seconds in Retry-After |
500 | internal_error | Something failed on our side: retry later and quote the X-Request-Id if you contact us |
The reference below is in English, like the OpenAPI document.
Customers
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/customers | customers:read | List customers |
GET | /api/v1/customers/{id} | customers:read | Read a customer |
POST | /api/v1/customers | customers:write | Create a customer (an existing e-mail / phone returns that customer) |
PATCH | /api/v1/customers/{id} | customers:write | Update a customer's contact details |
Leads
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/inquiries | inquiries:read | List leads |
GET | /api/v1/inquiries/{id} | inquiries:read | Read a lead |
POST | /api/v1/inquiries | inquiries:write | Create a lead (contact, quote request, booking request, call-back) — notifies the team like the website form |
Quotations
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/quotations | quotations:read | List quotations |
GET | /api/v1/quotations/{id} | quotations:read | Read a quotation with its lines |
POST | /api/v1/quotations | quotations:write | Create a DRAFT quotation (tax computed by the workspace's rules) |
Invoices
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/invoices | invoices:read | List invoices |
GET | /api/v1/invoices/{id} | invoices:read | Read an invoice with lines and payments |
POST | /api/v1/invoices | invoices:write | Create a DRAFT invoice (numbered when issued in the back office) |
GET | /api/v1/payments | payments:read | List invoice payments (invoice=<id> to filter) |
GET | /api/v1/payments/{id} | payments:read | Read a payment |
Orders
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/orders | orders:read | List shop orders |
GET | /api/v1/orders/{id} | orders:read | Read a shop order |
Catalog
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/products | products:read | List products with price and stock (catalog:read also allows it) |
GET | /api/v1/products/{id} | products:read | Read a product |
GET | /api/v1/categories | catalog:read | List categories (type=product|service|post|project, locale=…) (hosted workspaces) |
GET | /api/v1/services | catalog:read | List published services (hosted workspaces) |
GET | /api/v1/services/{id} | catalog:read | Read a service (hosted workspaces) |
GET | /api/v1/products/lookup | products:read | Exact barcode / SKU match (GTIN, SKU or an extra product barcode) — for scanners |
Bookings
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/booking-services | catalog:read | List bookable services (online booking on) (hosted workspaces) |
GET | /api/v1/booking-services/{id} | catalog:read | Read a bookable service (hosted workspaces) |
GET | /api/v1/bookings/slots | bookings:read | Free start times of a bookable service on a date (hosted workspaces) |
GET | /api/v1/bookings | bookings:read | List appointments (hosted workspaces) |
GET | /api/v1/bookings/{id} | bookings:read | Read an appointment (hosted workspaces) |
POST | /api/v1/bookings | bookings:write | Book an appointment at a free time (409 when it was taken) (hosted workspaces) |
Webhooks
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/events | webhooks:read | The webhook event catalog |
GET | /api/v1/deliveries | webhooks:read | Webhook delivery log |
GET | /api/v1/deliveries/{id} | webhooks:read | One delivery with its payload |
GET | /api/v1/webhooks | webhooks:read | List webhook endpoints (no secrets) (hosted workspaces) |
POST | /api/v1/webhooks | webhooks:write | Create a webhook endpoint — the signing secret is returned once (hosted workspaces) |
DELETE | /api/v1/webhooks/{id} | webhooks:write | Delete a webhook endpoint (hosted workspaces) |
Account
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/me | (any) | Who is calling: the API key, or the person signed in to the app, with the workspace and the scopes |
Stock
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/warehouses | stock:read | Active stock locations |
GET | /api/v1/stock | stock:read | Stock levels per location (product=<id> for one product, all its rows) |
POST | /api/v1/stock/adjustments | stock:write | Add or remove stock (same rules as the admin: write-off reasons only remove) |
Appointments
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/appointments | appointments:read | List appointments (from / to filter the start time) |
GET | /api/v1/appointments/{id} | appointments:read | Read an appointment |
Point of sale
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/pos-sales | pos:read | List till sales and refunds (since = created since) |
GET | /api/v1/pos-sales/{id} | pos:read | Read a till sale with its lines and payments |
Tasks
| Method | Path | Scope | What it does |
|---|---|---|---|
GET | /api/v1/tasks | tasks:read | List tasks (app sign-in without tasks.manage: only my tasks) |
GET | /api/v1/tasks/{id} | tasks:read | Read a task |
POST | /api/v1/tasks | tasks:write | Create a task (assigned to the signed-in person by default) |
PATCH | /api/v1/tasks/{id} | tasks:write | Update a task or change its status (DONE closes it; recurring tasks schedule the next one) |
Files
| Method | Path | Scope | What it does |
|---|---|---|---|
POST | /api/v1/attachments | attachments:write | Upload a photo or PDF (multipart: file, taskId?, folder?) — images are re-encoded, metadata such as GPS removed |
GET | /api/v1/attachments/{id} | attachments:write | Read an uploaded file's record |
Apps
| Method | Path | Scope | What it does |
|---|---|---|---|
POST | /api/v1/session/handoff | (app) | One-time URL (60 s) that signs the app's web view in to the workspace and opens `next` (app token only) |
GET | /api/v1/devices | (app) | My app installations (app token only) |
POST | /api/v1/devices | (app) | Register an app installation for push (FCM / APNs / Huawei Push Kit token; the same token again returns the same id) (app token only) |
DELETE | /api/v1/devices/{id} | (app) | Remove an app installation (app token only) |
GET | /api/v1/devices/{id} | (app) | One app installation with the alert categories it does not get pushes for (app token only) |
PATCH | /api/v1/devices/{id} | (app) | Alert categories this installation does not get pushes for (tasks, sales, bookings, messages, stock, system) — they still appear in /notifications (app token only) |
GET | /api/v1/account/deletion | (app) | Delete account (apps): which path applies — workspace owner closes the workspace, staff ask the administrators, customers use the website — with links and a pending request (app token only) |
POST | /api/v1/account/deletion | (app) | Delete account (apps): mode request = ask the administrators to delete the staff account and remove the app data; mode app-data = only end every app sign-in and web session and remove devices / push tokens (app token only) |
POST | /api/v1/session/sign-out-all | (app) | Sign out of all devices: ends every app sign-in and web session of the person and removes their app installations (app token only) |
GET | /api/v1/rider/today | (app) | Rider mode: which duties I may start (rider = parcels.ride, tech = field.work, driver = fleet.drive), my duty, today's runs, delivery stops and pickups (app token only) |
POST | /api/v1/rider/duty | (app) | Start duty (returns a duty token that can only post positions / end the duty) or end it; the workspace's live-location setting must be on (app token only) |
POST | /api/v1/rider/positions | (app) | Post a batch of positions while on duty (app token or the duty token fx_dt_…); only the newest valid point is kept (latest position, no trail) and feeds the recipient ETA and the runs map; a driver's batch also moves their vehicle and, when the workspace keeps one, its short trail (app token only) |
GET | /api/v1/apps | (app) | Home screen of the apps: the app grid I may open (name, area, icon as SVG nodes, waiting count), the workspace brand and unread alerts (app token only) |
GET | /api/v1/search | (app) | Search records I may open (customers, invoices, orders, products …), grouped like the admin header search; also suggestion (did you mean), quick (prefilled create links such as a new invoice for a customer) and intent (app token only) |
GET | /api/v1/notifications | (app) | Alerts for me since a time (the desktop app polls this) (app token only) |
Sensors
| Method | Path | Scope | What it does |
|---|---|---|---|
POST | /api/v1/sensors/readings | sensors:write | Upload sensor readings (temperature, humidity, fuel_level, value) — up to 500 per request; the device is the key's own device or the serial in `device`; re-sent readings are skipped; send an Idempotency-Key |
Next: Webhooks
Business events sent to your HTTPS endpoint as they happen: signed, retried on failure and logged.