API reference

Clients

People and companies who buy from you, with contact details, preferences (ring size, metal, stones, style) and dates.

Endpoints

GET/api/v1/clientsList, newest first

POST/api/v1/clientsCreate · write key

GET/api/v1/clients/{id}Get one

PATCH/api/v1/clients/{id}Change · write key

DELETE/api/v1/clients/{id}Delete · write key · owners, admins, managers

Fields

Every record also has object = "client". When creating, at least one of first_name, last_name, company_name is required.

Field	Type	Description
`id` read only	uuid	Unique ID.
`brand_id` required on create set on create only	uuid	The brand this belongs to (see GET /brands). Required when creating; cannot be changed.
`first_name`	string, max 100	First name.
`last_name`	string, max 100	Last name.
`company_name`	string, max 200	Company, for business clients.
`email`	email, max 254	Email address.
`phone`	string, max 40	Phone in any format; international (+41…) works best.
`street`	string, max 200	Street.
`house_no`	string, max 20	House number.
`zip`	string, max 20	Postcode.
`city`	string, max 100	Town or city.
`country`	string, max 2	Country as a two-letter code (CH, DE, AE…).
`external_code`	string, max 60	Your own client number, e.g. from Lightspeed or a website.
`ring_size`	string, max 20	Ring size.
`metal`	string, max 60	Preferred metal.
`stones`	string, max 120	Preferred stones.
`style`	string, max 120	Style notes.
`birthday`	date	Birthday (YYYY-MM-DD).
`anniversary`	date	Anniversary (YYYY-MM-DD).
`tags`	list of strings	Up to 30 tags of up to 40 characters.
`notes`	string, max 5000	Free notes.
`created_at` read only	date-time	When it was created (UTC, ISO 8601).
`updated_at` read only	date-time	When it was last changed.

List filters

Add to GET /api/v1/clients as query parameters. Also limit (1–200, default 50) and cursor. See Pagination.

Parameter	Type	Meaning
`brand_id`	uuid	Only this brand.
`email`	email	Exact email address (not case-sensitive).
`external_code`	string	Exact external code.
`q`	text, min. 2 characters	Search in name, company, email and phone.
`created_since`	date-time	Created at or after this time.
`updated_since`	date-time	Changed at or after this time (use for syncing).

List

Terminal

curl "$QUILO_URL/api/v1/clients?limit=20" \
  -H "Authorization: Bearer $QUILO_API_KEY"

JSON

{
  "object": "list",
  "data": [
    {
      "object": "client",
      "id": "6f1c2a90-3b4d-4e5f-8a7b-9c0d1e2f3a4b",
      "brand_id": "0b7e9a52-1c3d-4f6e-9a8b-7c6d5e4f3a2b",
      "first_name": "Elena",
      "last_name": "Marti",
      "company_name": "Example",
      "email": "elena@example.ch",
      "phone": "+41 79 123 45 67",
      "street": null,
      "house_no": null,
      "zip": null,
      "city": null,
      "country": "CH",
      "external_code": null,
      "ring_size": null,
      "metal": null,
      "stones": null,
      "style": null,
      "birthday": "1990-04-12",
      "anniversary": "2026-10-17",
      "tags": [
        "vip",
        "website"
      ],
      "notes": null,
      "created_at": "2026-10-17T09:30:00Z",
      "updated_at": "2026-10-17T09:30:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create

Answers 201 Created with the new client. Send an Idempotency-Key to retry safely.

Terminal

curl -X POST "$QUILO_URL/api/v1/clients" \
  -H "Authorization: Bearer $QUILO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-id-123" \
  -d '{
  "brand_id": "0b7e9a52-1c3d-4f6e-9a8b-7c6d5e4f3a2b",
  "first_name": "Elena",
  "last_name": "Marti",
  "email": "elena@example.ch",
  "phone": "+41 79 123 45 67",
  "country": "CH",
  "birthday": "1990-04-12",
  "tags": [
    "vip",
    "website"
  ]
}'

Get one

Terminal

curl "$QUILO_URL/api/v1/clients/ID" -H "Authorization: Bearer $QUILO_API_KEY"

JSON

{
  "object": "client",
  "id": "6f1c2a90-3b4d-4e5f-8a7b-9c0d1e2f3a4b",
  "brand_id": "0b7e9a52-1c3d-4f6e-9a8b-7c6d5e4f3a2b",
  "first_name": "Elena",
  "last_name": "Marti",
  "company_name": "Example",
  "email": "elena@example.ch",
  "phone": "+41 79 123 45 67",
  "street": null,
  "house_no": null,
  "zip": null,
  "city": null,
  "country": "CH",
  "external_code": null,
  "ring_size": null,
  "metal": null,
  "stones": null,
  "style": null,
  "birthday": "1990-04-12",
  "anniversary": "2026-10-17",
  "tags": [
    "vip",
    "website"
  ],
  "notes": null,
  "created_at": "2026-10-17T09:30:00Z",
  "updated_at": "2026-10-17T09:30:00+00:00"
}

Unknown IDs, IDs from other companies and records you cannot access all answer 404 not_found.

Change

Send only the fields to change. brand_id cannot be changed after creation.

Terminal

curl -X PATCH "$QUILO_URL/api/v1/clients/ID" \
  -H "Authorization: Bearer $QUILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Elena"}'

Delete

Owners, admins and managers only, with a Read and write key. Deleting cannot be undone.

Terminal

curl -X DELETE "$QUILO_URL/api/v1/clients/ID" -H "Authorization: Bearer $QUILO_API_KEY"

JSON

{
  "object": "client",
  "id": "6f1c2a90-3b4d-4e5f-8a7b-9c0d1e2f3a4b",
  "deleted": true
}