Skip to content
14-day free trial, no card9 languages176 business types · 50 apps
EN· USD
Try a live demoStart free trial

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

  1. Open an instant demo: a workspace with sample data
  2. In the demo, go to Admin → Integrations & API and create a key
  3. Call GET /api/v1/me with the key (below) to see which workspace and person it belongs to
  4. 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

StatusCodeMeaning
400invalid_jsonThe body is not valid JSON
401unauthenticatedNo key or token was sent
401invalid_keyThe key is unknown, revoked or expired, or an MCP token was used on the REST API
401token_expiredThe app token has expired: refresh it
403insufficient_scopeThe key lacks the scope this route needs
403forbiddenThe key's person may not open this area or record
403origin_not_allowedA browser call from a site that is not on the workspace's allowed origins
403ip_not_allowedThe key's IP allow-list does not include this address
403test_mode_read_onlyA test key tried to change data: test keys only read
404not_foundNo such record or route in this workspace
409conflictThe request clashes with the current state, for example a duplicate
422validation_failedFields failed validation; the answer lists the problems per field
429rate_limitedToo many requests: wait for the seconds in Retry-After
500internal_errorSomething 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

MethodPathScopeWhat it does
GET/api/v1/customerscustomers:readList customers
GET/api/v1/customers/{id}customers:readRead a customer
POST/api/v1/customerscustomers:writeCreate a customer (an existing e-mail / phone returns that customer)
PATCH/api/v1/customers/{id}customers:writeUpdate a customer's contact details

Leads

MethodPathScopeWhat it does
GET/api/v1/inquiriesinquiries:readList leads
GET/api/v1/inquiries/{id}inquiries:readRead a lead
POST/api/v1/inquiriesinquiries:writeCreate a lead (contact, quote request, booking request, call-back) — notifies the team like the website form

Quotations

MethodPathScopeWhat it does
GET/api/v1/quotationsquotations:readList quotations
GET/api/v1/quotations/{id}quotations:readRead a quotation with its lines
POST/api/v1/quotationsquotations:writeCreate a DRAFT quotation (tax computed by the workspace's rules)

Invoices

MethodPathScopeWhat it does
GET/api/v1/invoicesinvoices:readList invoices
GET/api/v1/invoices/{id}invoices:readRead an invoice with lines and payments
POST/api/v1/invoicesinvoices:writeCreate a DRAFT invoice (numbered when issued in the back office)
GET/api/v1/paymentspayments:readList invoice payments (invoice=<id> to filter)
GET/api/v1/payments/{id}payments:readRead a payment

Orders

MethodPathScopeWhat it does
GET/api/v1/ordersorders:readList shop orders
GET/api/v1/orders/{id}orders:readRead a shop order

Catalog

MethodPathScopeWhat it does
GET/api/v1/productsproducts:readList products with price and stock (catalog:read also allows it)
GET/api/v1/products/{id}products:readRead a product
GET/api/v1/categoriescatalog:readList categories (type=product|service|post|project, locale=…) (hosted workspaces)
GET/api/v1/servicescatalog:readList published services (hosted workspaces)
GET/api/v1/services/{id}catalog:readRead a service (hosted workspaces)
GET/api/v1/products/lookupproducts:readExact barcode / SKU match (GTIN, SKU or an extra product barcode) — for scanners

Bookings

MethodPathScopeWhat it does
GET/api/v1/booking-servicescatalog:readList bookable services (online booking on) (hosted workspaces)
GET/api/v1/booking-services/{id}catalog:readRead a bookable service (hosted workspaces)
GET/api/v1/bookings/slotsbookings:readFree start times of a bookable service on a date (hosted workspaces)
GET/api/v1/bookingsbookings:readList appointments (hosted workspaces)
GET/api/v1/bookings/{id}bookings:readRead an appointment (hosted workspaces)
POST/api/v1/bookingsbookings:writeBook an appointment at a free time (409 when it was taken) (hosted workspaces)

Webhooks

MethodPathScopeWhat it does
GET/api/v1/eventswebhooks:readThe webhook event catalog
GET/api/v1/deliverieswebhooks:readWebhook delivery log
GET/api/v1/deliveries/{id}webhooks:readOne delivery with its payload
GET/api/v1/webhookswebhooks:readList webhook endpoints (no secrets) (hosted workspaces)
POST/api/v1/webhookswebhooks:writeCreate a webhook endpoint — the signing secret is returned once (hosted workspaces)
DELETE/api/v1/webhooks/{id}webhooks:writeDelete a webhook endpoint (hosted workspaces)

Account

MethodPathScopeWhat 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

MethodPathScopeWhat it does
GET/api/v1/warehousesstock:readActive stock locations
GET/api/v1/stockstock:readStock levels per location (product=<id> for one product, all its rows)
POST/api/v1/stock/adjustmentsstock:writeAdd or remove stock (same rules as the admin: write-off reasons only remove)

Appointments

MethodPathScopeWhat it does
GET/api/v1/appointmentsappointments:readList appointments (from / to filter the start time)
GET/api/v1/appointments/{id}appointments:readRead an appointment

Point of sale

MethodPathScopeWhat it does
GET/api/v1/pos-salespos:readList till sales and refunds (since = created since)
GET/api/v1/pos-sales/{id}pos:readRead a till sale with its lines and payments

Tasks

MethodPathScopeWhat it does
GET/api/v1/taskstasks:readList tasks (app sign-in without tasks.manage: only my tasks)
GET/api/v1/tasks/{id}tasks:readRead a task
POST/api/v1/taskstasks:writeCreate a task (assigned to the signed-in person by default)
PATCH/api/v1/tasks/{id}tasks:writeUpdate a task or change its status (DONE closes it; recurring tasks schedule the next one)

Files

MethodPathScopeWhat it does
POST/api/v1/attachmentsattachments:writeUpload a photo or PDF (multipart: file, taskId?, folder?) — images are re-encoded, metadata such as GPS removed
GET/api/v1/attachments/{id}attachments:writeRead an uploaded file's record

Apps

MethodPathScopeWhat 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

MethodPathScopeWhat it does
POST/api/v1/sensors/readingssensors:writeUpload 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.

Webhooks