# Smart Lists Smart Lists are saved filter+sort definitions that can be private to a user or shared across a location. `filters` is an array of clauses; `sort` defines the default ordering. Visibility is determined by the `is_shared` flag plus the `visibleTo` query scope. ## List smart lists `GET /api/smart-lists` Returns smart lists visible to the authenticated user, ordered by `sort_order` then alphabetically by name. ### Example request ```bash curl --request GET \ --get "https://klozzo.com/api/smart-lists" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" ``` ### Response `200` ```json { "data": [ { "id": null, "location_id": null, "user_id": 3765, "name": "aut adipisci", "filters": [ { "field": "contact_type", "operator": "=", "value": "lead" } ], "sort": null, "sort_order": 2, "is_shared": false, "is_default": false, "created_at": null, "updated_at": null }, { "id": null, "location_id": null, "user_id": 3766, "name": "consequatur aut", "filters": [ { "field": "contact_type", "operator": "=", "value": "lead" } ], "sort": null, "sort_order": 7, "is_shared": false, "is_default": false, "created_at": null, "updated_at": null } ] } ``` ## Create a smart list `POST /api/smart-lists` Creates a smart list: a saved question about contacts, not a saved answer. The list stores the filters and the sort; who matches is worked out every time it is opened, so somebody who becomes a hot lead tomorrow is in it tomorrow without anybody touching it. That is the difference from a tag: a tag is something you put on a person, a smart list is a rule that finds them. Set `is_shared` to give the whole team the list; leave it off and it is yours. Only one list per user can be `is_default`, and setting a new one clears the old. ### Body parameters - `name` (string, required) — Display name (max 255). - `filters` (object[], required) — Filter clauses. Each clause: `{field, operator, value}`. Min 1. - `field` (string, required) — Field name. - `operator` (string, required) — Operator (e.g. `eq`, `ne`, `in`, `gt`, `like`). - `value` (string, required) — Value to compare against. A string for most operators, a list for `in`, a date for the date ones — whatever the field takes. - `sort` (object) — Default sort. Shape: `{field, direction}`. - `field` (string) — Field to sort by. - `direction` (string) — Either `asc` or `desc`. - `sort_order` (integer) — Display order in sidebar (low values first). - `is_shared` (boolean) — Share across location. - `is_default` (boolean) — Mark as the user's default list. ### Example request ```bash curl --request POST \ "https://klozzo.com/api/smart-lists" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" \ --data "{ \"name\": \"Hot leads, last 7 days\", \"filters\": [ { \"field\": \"contact_type\", \"operator\": \"eq\", \"value\": \"lead\" } ], \"sort\": { \"field\": \"created_at\", \"direction\": \"desc\" }, \"sort_order\": 0, \"is_shared\": false, \"is_default\": false }" ``` ### Response `200` ```json { "data": { "id": null, "location_id": null, "user_id": 3767, "name": "architecto eius", "filters": [ { "field": "contact_type", "operator": "=", "value": "lead" } ], "sort": null, "sort_order": 0, "is_shared": false, "is_default": false, "created_at": null, "updated_at": null } } ``` ### Response `422` — A list with no rule ```json { "message": "Falta filters.", "errors": { "filters": [ "Falta filters." ] } } ``` ### Response `422` — A clause missing its operator ```json { "message": "Falta filters.0.operator.", "errors": { "filters.0.operator": [ "Falta filters.0.operator." ] } } ``` ## Fetch a smart list `GET /api/smart-lists/{id}` Its filters and sort, not the contacts it matches — to get those, send the same filters to `GET /api/contacts`. A list you cannot see (somebody else's, unshared) answers `404`. ### Path parameters - `id` (integer, required) — Smart list ID. ### Example request ```bash curl --request GET \ --get "https://klozzo.com/api/smart-lists/5" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" ``` ### Response `200` ```json { "data": { "id": null, "location_id": null, "user_id": 3768, "name": "aut adipisci", "filters": [ { "field": "contact_type", "operator": "=", "value": "lead" } ], "sort": null, "sort_order": 2, "is_shared": false, "is_default": false, "created_at": null, "updated_at": null } } ``` ### Response `404` — Does not exist, or belongs to another location ```json { "message": "No query results for model." } ``` ## Update a smart list `PUT /api/smart-lists/{id}` Changes the rule, so it changes who the list finds from the next time anybody opens it — including everybody else's, if the list is shared. There is no version history: the previous filters are gone. Sending `filters` **replaces** them all; there is no way to add one clause without resending the rest. ### Path parameters - `id` (integer, required) — Smart list ID. ### Body parameters - `name` (string) — Display name (max 255). - `filters` (object[]) — Filter clauses; same shape as the create payload. Replaces the existing set. - `field` (string) — This field is required when filters is present. - `operator` (string) — This field is required when filters is present. - `value` (string) — This field is required when filters is present. - `sort` (object) — Default sort `{field, direction}`. - `field` (string) — This field is required when sort is present. - `direction` (string) — This field is required when sort is present. One of: `asc`, `desc`. - `sort_order` (integer) — Display order. - `is_shared` (boolean) — Whether the whole team sees the list. Turning it off hides it from everybody but you. - `is_default` (boolean) — Make it the list you land on. Setting it clears the flag on whichever list had it. ### Example request ```bash curl --request PUT \ "https://klozzo.com/api/smart-lists/5" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" \ --data "{ \"name\": \"Hot leads, last 14 days\", \"filters\": [ { \"field\": \"architecto\", \"operator\": \"architecto\" } ], \"sort\": { \"field\": \"architecto\", \"direction\": \"desc\" }, \"sort_order\": 2, \"is_shared\": true, \"is_default\": false }" ``` ### Response `200` ```json { "data": { "id": null, "location_id": null, "user_id": 3769, "name": "architecto eius", "filters": [ { "field": "contact_type", "operator": "=", "value": "lead" } ], "sort": null, "sort_order": 0, "is_shared": false, "is_default": false, "created_at": null, "updated_at": null } } ``` ## Delete a smart list `DELETE /api/smart-lists/{id}` Deletes a smart list by id, and only the list. **No contact is deleted** — a smart list never owned anybody, it only found them — so this is always safe, and it is the one destructive-looking call in this API that is not. ### Path parameters - `id` (integer, required) — Smart list ID. ### Example request ```bash curl --request DELETE \ "https://klozzo.com/api/smart-lists/5" \ --header "Authorization: Bearer {YOUR_API_TOKEN}" \ --header "Content-Type: application/json" \ --header "Accept: application/json" ``` ### Response `200` ```json { "message": "Smart list deleted." } ```