Case Lists

Case lists allow you to save reusable case filters that power campaigns and automations.

List Case Lists

GET/v1/case_lists

Query Parameters

Field	Required	Type	Description
key	false	String	Search term for list name
page	false	Int	Page number (default: 1)
page_size	false	Int	Results per page (default: 25, max: 100)
hide_empty	false	Bool	Only return non-empty lists

Request

curl -X GET 'https://public-api.kayse.ai/v1/case_lists?key=tort' \
-H 'X-API-KEY: your_api_key'

Response

{
  "data": [
    {
      "id": 1,
      "name": "Mass Tort Prospects",
      "description": "Prospects matching tort filters",
      "case_count": 150,
      "origin": "public_api",
      "update_origin": null
    }
  ],
  "page": 1,
  "total": 1
}

Create a Case List

POST/v1/case_lists

Request Body Fields

Field	Required	Type	Description
name	true	String	Case list name
description	false	String	Description shown in UI
external_source	false	String	Origin system name
external_source_id	false	String	ID in origin system
filter	false	Object	Case filter criteria
include_ids	false	Array	Case IDs to include
exclude_ids	false	Array	Case IDs to exclude
is_obo	false	Boolean	On behalf of flag

Request

curl -X POST 'https://public-api.kayse.ai/v1/case_lists' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
  "name": "Mass Tort Prospects",
  "description": "Prospects matching tort filters",
  "filter": {
    "case_type_ids": [25],
    "status_ids": [30]
  },
  "include_ids": [101, 102]
}'

Response

{
  "id": 1,
  "name": "Mass Tort Prospects",
  "description": "Prospects matching tort filters",
  "case_count": 52,
  "origin": "public_api",
  "update_origin": null
}

Bulk Upsert Case Lists

POST/v1/case_lists/bulk

Request Body Fields

Field	Required	Type	Description
lists	true	Array	Array of case list definitions

Each object inside lists accepts the same fields as the create endpoint. When an id is provided, the existing list is updated.

Request

curl -X POST 'https://public-api.kayse.ai/v1/case_lists/bulk' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
  "lists": [
    {
      "name": "PI Prospects",
      "filter": { "case_type_ids": [10] }
    },
    {
      "id": 55,
      "name": "Updated List",
      "is_obo": true
    }
  ]
}'

Response

{
  "results": [
    { "id": 100, "action": "created" },
    { "id": 55, "action": "updated" }
  ]
}

Attach Cases to a Case List

PATCH/v1/case_lists/{id}/attach

Attach cases to a case list using a filter, explicit case IDs, or both.

If this case list is already linked to an active or paused campaign that has a form attached, or to a legacy campaign with no explicit status that Kayse treats as active, Kayse also queues any missing form tasks for the newly attached cases. That backfill happens asynchronously after the attach request succeeds.

Path Parameters

Field	Required	Type	Description
id	true	Int	Case list ID

Request Body Fields

Field	Required	Type	Description
filter	conditional	Object	Case filter criteria (required unless include_ids is provided)
include_ids	conditional	Array	Case IDs to attach (required unless filter is provided)
exclude_ids	false	Array	Case IDs to exclude (requires filter)

Request

curl -X PATCH 'https://public-api.kayse.ai/v1/case_lists/1/attach' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
  "include_ids": [201, 202, 203]
}'

Response

{
  "action": "attach",
  "list_id": "1"
}

Detach Cases from a Case List

PATCH/v1/case_lists/{id}/detach

Detach cases from a case list using a filter, explicit case IDs, or both.

Path Parameters

Field	Required	Type	Description
id	true	Int	Case list ID

Request Body Fields

Field	Required	Type	Description
filter	conditional	Object	Case filter criteria (required unless include_ids is provided)
include_ids	conditional	Array	Case IDs to detach (required unless filter is provided)
exclude_ids	false	Array	Case IDs to exclude from detaching (requires filter)

Request

curl -X PATCH 'https://public-api.kayse.ai/v1/case_lists/1/detach' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
  "include_ids": [201, 202]
}'

Response

{
  "action": "detach",
  "list_id": "1"
}

Append Clients to a Case List

POST/v1/case_lists/{id}/clients/append

Add clients to a case list by providing their client IDs. The system finds all cases belonging to the specified clients and attaches them to the list.

If the target list is already linked to an active or paused campaign with a form attached, or to a legacy campaign with no explicit status that Kayse treats as active, Kayse also queues any missing form tasks for the newly matched cases. That backfill happens asynchronously after the append request succeeds.

Path Parameters

Field	Required	Type	Description
id	true	Int	Case list ID

Request Body Fields

Field	Required	Type	Description
client_ids	true	Array	Client IDs to add to the list

Request

curl -X POST 'https://public-api.kayse.ai/v1/case_lists/1/clients/append' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
  "client_ids": [101, 102, 103]
}'

Response

{
  "action": "append",
  "list_id": 1,
  "client_count": 3,
  "matched_case_count": 5
}

Remove Clients from a Case List

POST/v1/case_lists/{id}/clients/remove

Remove clients from a case list by providing their client IDs. The system finds all cases belonging to the specified clients and detaches them from the list.

Path Parameters

Field	Required	Type	Description
id	true	Int	Case list ID

Request Body Fields

Field	Required	Type	Description
client_ids	true	Array	Client IDs to remove from the list

Request

curl -X POST 'https://public-api.kayse.ai/v1/case_lists/1/clients/remove' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
  "client_ids": [101, 102]
}'

Response

{
  "action": "remove",
  "list_id": 1,
  "client_count": 2,
  "matched_case_count": 3
}

Duplicate a Case List

POST/v1/case_lists/{id}/duplicate

Create a copy of an existing case list, including its filter and case memberships.

Path Parameters

Field	Required	Type	Description
id	true	Int	Case list ID to duplicate

Request

curl -X POST 'https://public-api.kayse.ai/v1/case_lists/1/duplicate' \
-H 'X-API-KEY: your_api_key'

Response

{
  "id": 42,
  "original_list_id": "1"
}

Bulk Delete Case Lists

POST/v1/case_lists/bulk_delete

Request Body Fields

Field	Required	Type	Description
ids	true	Array	Case list IDs to delete

Request

curl -X POST 'https://public-api.kayse.ai/v1/case_lists/bulk_delete' \
-H 'X-API-KEY: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
  "ids": [44, 55]
}'

Response

{
  "deleted_ids": [44, 55]
}