Back to top

API Documentation

Contact List

Contact list

A Contact list represents a saved search performed on contacts. User can save this list to access the contacts that match criteria later. Each list is composed of four properties: attribute def, which is id for attribute definition on contact, this is the property that serach will be applied against; operator that can be one of ‘eq’ which stands for equality, ‘gte’ for greather than or equal, ‘lte’ for less than or equal, ‘like’ to perform a simple string search, ‘any’ to test if any of values matches contact attribute, ‘all’ to test if all values match contact attribute. Finally value is the actual value(s) that should be used in performing the search.

For date attributes, _value_ can be a Unix timestamp or { "month": 1..12 }. The latter performs a recurring calendar-month comparison without requiring a year; for example, { "month": 9 } with eq returns contacts whose birthday is in September. between accepts two values of the same precision. Numeric year-1800 values remain supported for legacy month/day filters, but new whole-month filters should use the explicit object form.

Create a contact list

Create a contact list
POST/contacts/lists

Example URI

POST /contacts/lists
Request
HideShow
Body
{
  "filters": [
    {
      "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
      "value": "cool"
    },
    {
      "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
      "value": "great"
    }
  ],
  "args": {
    "q": "Wow"
  },
  "name": "Wow list"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "1776a05e-23f5-49fd-8b0e-aca7e0efebc0",
    "created_at": 1791656419.379474,
    "updated_at": 1791656419.379474,
    "deleted_at": null,
    "created_by": "e89c280c-2615-41f2-9005-40ca7129bebb",
    "updated_by": null,
    "brand": "caeaf7a6-b73a-433d-a345-c9a4aa388a3a",
    "filters": [
      {
        "id": "fd41aeb5-1cae-4c01-9676-e0a2c037dcb9",
        "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
        "operator": "eq",
        "value": "cool",
        "invert": false,
        "type": "contact_list_filter"
      },
      {
        "id": "ea1c0e7c-d191-4720-8d05-761b2f2056cd",
        "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
        "operator": "eq",
        "value": "great",
        "invert": false,
        "type": "contact_list_filter"
      }
    ],
    "query": "Wow",
    "args": {
      "filter_type": "and",
      "q": "Wow",
      "crm_tasks": null,
      "flows": null,
      "assignees": null,
      "type": "contact_list_args"
    },
    "name": "Wow list",
    "is_editable": true,
    "touch_freq": null,
    "member_count": 0,
    "type": "contact_list"
  }
}

Update a contact list

Update a contact list
PUT/contacts/lists/:id

Example URI

PUT /contacts/lists/:id
URI Parameters
HideShow
id
string (required) Example: 1776a05e-23f5-49fd-8b0e-aca7e0efebc0
Request
HideShow
Body
{
  "id": "1776a05e-23f5-49fd-8b0e-aca7e0efebc0",
  "created_at": 1791656419.379474,
  "deleted_at": null,
  "created_by": "e89c280c-2615-41f2-9005-40ca7129bebb",
  "brand": "caeaf7a6-b73a-433d-a345-c9a4aa388a3a",
  "filters": [
    {
      "id": "fd41aeb5-1cae-4c01-9676-e0a2c037dcb9",
      "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
      "operator": "eq",
      "value": "cool",
      "invert": false,
      "type": "contact_list_filter"
    },
    {
      "id": "ea1c0e7c-d191-4720-8d05-761b2f2056cd",
      "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
      "operator": "eq",
      "value": "great",
      "invert": false,
      "type": "contact_list_filter"
    }
  ],
  "args": {
    "q": "OMG",
    "filter_type": "and"
  },
  "name": "Wow list",
  "is_editable": true,
  "touch_freq": null,
  "member_count": 0,
  "type": "contact_list"
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "1776a05e-23f5-49fd-8b0e-aca7e0efebc0",
    "created_at": 1791656419.379474,
    "updated_at": 1791656419.429838,
    "deleted_at": null,
    "created_by": "e89c280c-2615-41f2-9005-40ca7129bebb",
    "updated_by": "e89c280c-2615-41f2-9005-40ca7129bebb",
    "brand": "caeaf7a6-b73a-433d-a345-c9a4aa388a3a",
    "filters": [
      {
        "id": "fd41aeb5-1cae-4c01-9676-e0a2c037dcb9",
        "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
        "operator": "eq",
        "value": "cool",
        "invert": false,
        "type": "contact_list_filter"
      },
      {
        "id": "ea1c0e7c-d191-4720-8d05-761b2f2056cd",
        "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
        "operator": "eq",
        "value": "great",
        "invert": false,
        "type": "contact_list_filter"
      }
    ],
    "query": "OMG",
    "args": {
      "filter_type": "and",
      "q": "OMG",
      "crm_tasks": null,
      "flows": null,
      "assignees": null,
      "type": "contact_list_args"
    },
    "name": "Wow list",
    "is_editable": true,
    "touch_freq": null,
    "member_count": 0,
    "type": "contact_list"
  }
}

List all contact list for current user

List all contact list for current user
GET/contacts/lists

Example URI

GET /contacts/lists
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "c7cdbeda-3a05-4990-9f77-c3fabadafca4",
      "created_at": 1791656419.232644,
      "updated_at": 1791656419.232644,
      "deleted_at": null,
      "created_by": null,
      "updated_by": null,
      "brand": "caeaf7a6-b73a-433d-a345-c9a4aa388a3a",
      "filters": [
        {
          "id": "242870d7-4cf5-4345-9702-a6b74c9c6ac1",
          "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
          "operator": "eq",
          "value": "Warm",
          "invert": false,
          "type": "contact_list_filter"
        }
      ],
      "query": null,
      "args": {
        "filter_type": "and",
        "q": null,
        "crm_tasks": null,
        "flows": null,
        "assignees": null,
        "type": "contact_list_args"
      },
      "name": "Warm",
      "is_editable": true,
      "touch_freq": 60,
      "member_count": 0,
      "type": "contact_list"
    },
    {
      "id": "c6b31562-b94f-4032-a4be-ca7b07321be3",
      "created_at": 1791656419.233291,
      "updated_at": 1791656419.233291,
      "deleted_at": null,
      "created_by": null,
      "updated_by": null,
      "brand": "caeaf7a6-b73a-433d-a345-c9a4aa388a3a",
      "filters": [
        {
          "id": "4d1b8b42-ef34-4107-816c-7bf5fde5a2fa",
          "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
          "operator": "eq",
          "value": "Hot",
          "invert": false,
          "type": "contact_list_filter"
        }
      ],
      "query": null,
      "args": {
        "filter_type": "and",
        "q": null,
        "crm_tasks": null,
        "flows": null,
        "assignees": null,
        "type": "contact_list_args"
      },
      "name": "Hot",
      "is_editable": true,
      "touch_freq": 30,
      "member_count": 0,
      "type": "contact_list"
    },
    {
      "id": "f19f9645-d29d-482a-b7af-501f03a9b596",
      "created_at": 1791656419.233823,
      "updated_at": 1791656419.233823,
      "deleted_at": null,
      "created_by": null,
      "updated_by": null,
      "brand": "caeaf7a6-b73a-433d-a345-c9a4aa388a3a",
      "filters": [
        {
          "id": "c57edbce-a4dd-49b8-b4a9-a6c2727cf8bd",
          "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
          "operator": "eq",
          "value": "Past Client",
          "invert": false,
          "type": "contact_list_filter"
        }
      ],
      "query": null,
      "args": {
        "filter_type": "and",
        "q": null,
        "crm_tasks": null,
        "flows": null,
        "assignees": null,
        "type": "contact_list_args"
      },
      "name": "Past Client",
      "is_editable": true,
      "touch_freq": null,
      "member_count": 0,
      "type": "contact_list"
    },
    {
      "id": "a8ef793d-1414-42a4-9b48-e9584083d883",
      "created_at": 1791656419.234325,
      "updated_at": 1791656419.234325,
      "deleted_at": null,
      "created_by": null,
      "updated_by": null,
      "brand": "caeaf7a6-b73a-433d-a345-c9a4aa388a3a",
      "filters": [
        {
          "id": "dc28e86b-8d9d-438e-9c21-0a9a2d738fd7",
          "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
          "operator": "eq",
          "value": "IOSAddressBook",
          "invert": false,
          "type": "contact_list_filter"
        }
      ],
      "query": null,
      "args": {
        "filter_type": "and",
        "q": null,
        "crm_tasks": null,
        "flows": null,
        "assignees": null,
        "type": "contact_list_args"
      },
      "name": "iOS",
      "is_editable": true,
      "touch_freq": null,
      "member_count": 0,
      "type": "contact_list"
    },
    {
      "id": "1776a05e-23f5-49fd-8b0e-aca7e0efebc0",
      "created_at": 1791656419.379474,
      "updated_at": 1791656419.429838,
      "deleted_at": null,
      "created_by": "e89c280c-2615-41f2-9005-40ca7129bebb",
      "updated_by": "e89c280c-2615-41f2-9005-40ca7129bebb",
      "brand": "caeaf7a6-b73a-433d-a345-c9a4aa388a3a",
      "filters": [
        {
          "id": "fd41aeb5-1cae-4c01-9676-e0a2c037dcb9",
          "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
          "operator": "eq",
          "value": "cool",
          "invert": false,
          "type": "contact_list_filter"
        },
        {
          "id": "ea1c0e7c-d191-4720-8d05-761b2f2056cd",
          "attribute_def": "5b3c994e-7569-4df8-b8db-f37421a684f7",
          "operator": "eq",
          "value": "great",
          "invert": false,
          "type": "contact_list_filter"
        }
      ],
      "query": "OMG",
      "args": {
        "filter_type": "and",
        "q": "OMG",
        "crm_tasks": null,
        "flows": null,
        "assignees": null,
        "type": "contact_list_args"
      },
      "name": "Wow list",
      "is_editable": true,
      "touch_freq": null,
      "member_count": 0,
      "type": "contact_list"
    },
    {
      "id": "73867a5e-28d9-49c1-9717-af6ad4f33388",
      "created_at": 1791656419.409795,
      "updated_at": 1791656419.409795,
      "deleted_at": null,
      "created_by": "e89c280c-2615-41f2-9005-40ca7129bebb",
      "updated_by": null,
      "brand": "caeaf7a6-b73a-433d-a345-c9a4aa388a3a",
      "filters": null,
      "query": null,
      "args": {
        "filter_type": "and",
        "q": null,
        "crm_tasks": null,
        "flows": null,
        "assignees": null,
        "type": "contact_list_args"
      },
      "name": "Empty List",
      "is_editable": true,
      "touch_freq": null,
      "member_count": 0,
      "type": "contact_list"
    }
  ],
  "info": {
    "count": 6,
    "total": 0
  }
}

Delete contact list

Delete contact list
DELETE/contacts/lists/:id

Example URI

DELETE /contacts/lists/:id
URI Parameters
HideShow
id
string (required) Example: 1776a05e-23f5-49fd-8b0e-aca7e0efebc0
Response  204

List all available contact search filters that can be appiled to contacts

List all available contact search filters that can be appiled to contacts
GET/contacts/lists/options

Example URI

GET /contacts/lists/options
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "tag": {
      "values": [],
      "operator": "all"
    }
  }
}

Generated by aglio on 10 Oct 2026