Lists

Lists are Clarify's pipeline and saved-view abstraction. Static lists are manual pipelines — you add and remove records explicitly. Dynamic lists are SQL-driven views that auto-evaluate against your data.

Type	Use case	Records
`static`	Pipelines, manual groupings	Added/removed explicitly
`dynamic`	Saved filters, reporting views	Auto-populated by SQL query

List all lists

GET /lists

Returns all lists across all object types in the workspace. Supports offset pagination.

GET /lists?page[limit]=100&page[offset]=0

List by object type

GET /objects/{object}/lists

Returns lists scoped to a single object type.

GET /objects/deal/lists

Get a list

GET /objects/{object}/lists/{listId}

Returns a single list by ID, including its query (for dynamic lists), layout, and evaluation status.

Create a list

POST /objects/{object}/lists

{
  "title": "Sales Pipeline",
  "type": "static",
  "description": "Main sales pipeline",
  "layout": "board",
  "permission": "workspace"
}

Field	Type	Required	Notes
`title`	string	Yes
`type`	`"static"` or `"dynamic"`	Yes	`"default"` is not allowed via API
`description`	string	No
`layout`	`"table"` or `"board"`	No	Board renders as a Kanban view
`permission`	`"private"` or `"workspace"`	No	Defaults to published/workspace-visible
`emoji`	string or null	No	Defaults to `null`
`query`	object or null	No	SQL query for dynamic lists (see below)

Returns the created list with its id.

{
  "data": {
    "id": "lst_01HX9Z2K3M4N5P6Q7R8S9T0U",
    "type": "list",
    "attributes": {
      "title": "Sales Pipeline",
      "type": "static",
      "layout": "board"
    }
  }
}

Dynamic list queries

Dynamic lists use a SQL query to filter and display records. Pass a query object with sql and version: 6.

{
  "title": "High-value deals",
  "type": "dynamic",
  "description": "Deals over $10k",
  "query": {
    "sql": "SELECT \"deal\".name AS \"deal:__object__\", \"deal\".stage, \"deal\".amount FROM \"deal\" WHERE \"deal\".amount > 10000 ORDER BY \"deal\"._created_at DESC NULLS LAST",
    "version": 6
  }
}

If you omit query, the API generates a default view with standard columns. Only provide it when you need custom columns or filters.

Column conventions

Columns must be fully qualified with the object type, and use specific alias patterns for the UI to render them correctly.

Column type	Alias pattern	Example
Record link (clickable)	`"entity:__object__"`	`"deal".name AS "deal:__object__"`
Plain field	None needed	`"deal".amount`
Relationship column	`"entity$field:__object__"`	`"deal$company_id".name AS "deal$company_id:__object__"`

Relationship columns require a LEFT JOIN:

SELECT "deal".name AS "deal:__object__",
       "deal$company_id".name AS "deal$company_id:__object__",
       "deal$owner_id".name AS "deal$owner_id:__object__",
       "deal".amount, "deal".stage
FROM "deal"
LEFT JOIN "company" AS "deal$company_id"
  ON "deal".company_id = "deal$company_id"._id
LEFT JOIN "user" AS "deal$owner_id"
  ON "deal".owner_id = "deal$owner_id"._id

Without the JOIN, relationship columns render as raw UUIDs.

Filtering on multi_select fields

Use the ?| operator on the items key. Send it raw — don't escape it.

WHERE ("deal".labels->'items') ?| ARRAY['hot-lead', 'enterprise']

This renders as a native filter widget (dropdown with chips) in the Clarify UI.

Filter patterns by field type

Field type	SQL pattern
String equals	`UPPER("deal".field) = UPPER('value')`
String contains	`"deal".field ILIKE '%value%'`
Select (enum)	`"deal".stage = 'Won'`
Select (one of)	`"deal".stage IN ('Won', 'Lost')`
Multi-select contains	`("deal".labels->'items') ?\| ARRAY['val1']`
Number	`"deal".amount > 1000`
Date	`"deal".close_date >= '2026-01-01'`
Boolean	`"deal".is_active = true`

Update a list

PATCH /objects/{object}/lists/{listId}

Partial update — all fields from create are accepted, all optional.

{
  "title": "Renamed Pipeline",
  "layout": "table"
}

When updating query, the entire query object is replaced. If you need to add columns to a list that has user-applied filters, GET the list first, merge your changes into the existing SQL, and PATCH with the complete query.

Delete a list

DELETE /objects/{object}/lists/{listId}

Returns 202 Accepted.

Lists

On this page