Reference

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

Returns smart lists visible to the authenticated user, ordered by sort_order then alphabetically by name.

GET /api/smart-lists

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"

const url = new URL(
    "https://klozzo.com/api/smart-lists"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/smart-lists';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/smart-lists'
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.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
        }
    ]
}

data object[]
- id string
- location_id string
- user_id integer
- name string
- filters object[]
  - field string
  - operator string
  - value string
- sort string
- sort_order integer
- is_shared boolean
- is_default boolean
- created_at string
- updated_at string

Create a smart list

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.

POST /api/smart-lists

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).

Example: Hot leads, last 7 days
filters object[] required

Filter clauses. Each clause: {field, operator, value}. Min 1.
- field string required
  
  Field name.
  
  Example: contact_type
- operator string required
  
  Operator (e.g. eq, ne, in, gt, like).
  
  Example: eq
- 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.
  
  Example: lead
sort object

Default sort. Shape: {field, direction}.
- field string
  
  Field to sort by.
  
  Example: created_at
- direction string
  
  Either asc or desc.
  
  Example: desc
sort_order integer

Display order in sidebar (low values first).

Example: 0
is_shared boolean

Share across location.

Example: false
is_default boolean

Mark as the user's default list.

Example: false

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
}"

const url = new URL(
    "https://klozzo.com/api/smart-lists"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "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
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/smart-lists';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            '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,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/smart-lists'
payload = {
    "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
}
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.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
    }
}

data object
- id string
- location_id string
- user_id integer
- name string
- filters object[]
  - field string
  - operator string
  - value string
- sort string
- sort_order integer
- is_shared boolean
- is_default boolean
- created_at string
- updated_at string

{
    "message": "Falta filters.",
    "errors": {
        "filters": [
            "Falta filters."
        ]
    }
}

Every error shares the same shape — message and errors. See Errors.

{
    "message": "Falta filters.0.operator.",
    "errors": {
        "filters.0.operator": [
            "Falta filters.0.operator."
        ]
    }
}

Every error shares the same shape — message and errors. See Errors.

Fetch a smart list

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.

GET /api/smart-lists/{id}

Path parameters

id integer required

Smart list ID.

Example: 5

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"

const url = new URL(
    "https://klozzo.com/api/smart-lists/5"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/smart-lists/5';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/smart-lists/5'
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('GET', url, headers=headers)
response.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
    }
}

data object
- id string
- location_id string
- user_id integer
- name string
- filters object[]
  - field string
  - operator string
  - value string
- sort string
- sort_order integer
- is_shared boolean
- is_default boolean
- created_at string
- updated_at string

{
    "message": "No query results for model."
}

Every error shares the same shape — message and errors. See Errors.

Update a smart list

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.

PUT /api/smart-lists/{id}

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.

Example: 5

Body parameters

name string

Display name (max 255).

Example: Hot leads, last 14 days
filters object[]

Filter clauses; same shape as the create payload. Replaces the existing set.
- field string
  
  This field is required when <code>filters</code> is present.
  
  Example: architecto
- operator string
  
  This field is required when <code>filters</code> is present.
  
  Example: architecto
- value string
  
  This field is required when <code>filters</code> is present.
sort object

Default sort {field, direction}.
- field string
  
  This field is required when <code>sort</code> is present.
  
  Example: architecto
- direction string
  
  This field is required when <code>sort</code> is present.
  
  One of asc, desc
  
  Example: desc
sort_order integer

Display order.

Example: 2
is_shared boolean

Whether the whole team sees the list. Turning it off hides it from everybody but you.

Example: true
is_default boolean

Make it the list you land on. Setting it clears the flag on whichever list had it.

Example: false

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
}"

const url = new URL(
    "https://klozzo.com/api/smart-lists/5"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "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
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/smart-lists/5';
$response = $client->put(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            '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,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/smart-lists/5'
payload = {
    "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
}
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('PUT', url, headers=headers, json=payload)
response.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
    }
}

data object
- id string
- location_id string
- user_id integer
- name string
- filters object[]
  - field string
  - operator string
  - value string
- sort string
- sort_order integer
- is_shared boolean
- is_default boolean
- created_at string
- updated_at string

Delete a smart list

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.

DELETE /api/smart-lists/{id}

Path parameters

id integer required

Smart list ID.

Example: 5

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"

const url = new URL(
    "https://klozzo.com/api/smart-lists/5"
);

const headers = {
    "Authorization": "Bearer {YOUR_API_TOKEN}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

$client = new \GuzzleHttp\Client();
$url = 'https://klozzo.com/api/smart-lists/5';
$response = $client->delete(
    $url,
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_API_TOKEN}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

import requests
import json

url = 'https://klozzo.com/api/smart-lists/5'
headers = {
  'Authorization': 'Bearer {YOUR_API_TOKEN}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('DELETE', url, headers=headers)
response.json()

{
    "message": "Smart list deleted."
}

message string