API Reference - Smart Lists

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108113

← Back to API Reference | Getting Started

Smart Lists

Smart Lists are saved filtered views of site data such as members, leads, reviews, form submissions, and transactions. Each Smart List stores the query parameters and type needed to reproduce a filtered result set in the admin panel, allowing admins to save and reuse common data views.

Model name in URL: smart_lists — DB table: smart_lists

The Smart List Object

FieldTypeDescription
smart_list_idintegerUnique smart list ID (primary key, read-only)
smart_list_namestringDisplay name for this saved list (EG Active Gold Members) required on create
smart_list_typestringThe data category this list targets. One of: members, forms_inbox, leads, reviews, transaction, newsletter required on create
smart_list_query_tokentextBase64-encoded encrypted query string representing the filter criteria for this list
smart_list_modified_byintegerAdmin user ID of the person who last modified this list
smart_list_created_byintegerAdmin user ID of the person who created this list required on create
smart_list_createddatetimeDate and time this smart list was created
smart_list_query_paramstextRaw query string parameters used to filter the list (EG membership_id=2&active=1)
schedulestringRecurrence frequency (e.g., “monthly”)

List Smart Lists

GET /api/v2/smart_lists/get

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/smart_lists/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "smart_list_id": "1",
      "smart_list_name": "Active Gold Members",
      "smart_list_type": "members",
      "smart_list_query_token": "eDBYR0NoM1B1RDF4...",
      "smart_list_modified_by": "1",
      "smart_list_created_by": "1",
      "smart_list_created": "2024-03-15 09:00:00",
      "smart_list_query_params": "membership_id=2&active=1",
      "schedule": "monthly"
    },
    {
      "smart_list_id": "2",
      "smart_list_name": "Recent Leads",
      "smart_list_type": "leads",
      "smart_list_query_token": "aXlLQWx0WGVuUk1...",
      "smart_list_modified_by": "1",
      "smart_list_created_by": "1",
      "smart_list_created": "2024-06-01 14:30:00",
      "smart_list_query_params": "date_from=2024-01-01",
      "schedule": null
    }
  ],
  "total": "5",
  "current_page": 1,
  "total_pages": 1
}

Retrieve a Smart List

GET /api/v2/smart_lists/get/{smart_list_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/smart_lists/get/1" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "smart_list_id": "1",
      "smart_list_name": "Active Gold Members",
      "smart_list_type": "members",
      "smart_list_query_token": "eDBYR0NoM1B1RDF4...",
      "smart_list_modified_by": "1",
      "smart_list_created_by": "1",
      "smart_list_created": "2024-03-15 09:00:00",
      "smart_list_query_params": "membership_id=2&active=1",
      "schedule": "monthly"
    }
  ],
  "total": "1",
  "current_page": 1,
  "total_pages": 1
}

Create a Smart List

POST /api/v2/smart_lists/create

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/smart_lists/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "smart_list_name=Newsletter+Subscribers" \
  -d "smart_list_type=newsletter" \
  -d "smart_list_created_by=1" \
  -d "smart_list_query_params=subscribed%3D1"

Example Response

Copy
{
  "status": "success",
  "message": {
    "smart_list_id": "6",
    "smart_list_name": "Newsletter Subscribers",
    "smart_list_type": "newsletter",
    "smart_list_query_token": null,
    "smart_list_modified_by": null,
    "smart_list_created_by": "1",
    "smart_list_created": null,
    "smart_list_query_params": "subscribed=1",
    "schedule": null
  }
}

Update a Smart List

PUT /api/v2/smart_lists/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/smart_lists/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "smart_list_id=6" \
  -d "smart_list_name=Active+Newsletter+Subscribers" \
  -d "smart_list_modified_by=1"

Example Response

Copy
{
  "status": "success",
  "message": {
    "smart_list_id": "6",
    "smart_list_name": "Active Newsletter Subscribers",
    "smart_list_type": "newsletter",
    "smart_list_query_token": null,
    "smart_list_modified_by": "1",
    "smart_list_created_by": "1",
    "smart_list_created": null,
    "smart_list_query_params": "subscribed=1",
    "schedule": null
  }
}

Delete a Smart List

DELETE /api/v2/smart_lists/delete

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/smart_lists/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "smart_list_id=6"

Example Response

Copy
{
  "status": "success",
  "message": "smart_lists record was deleted"
}