ClarifyAPI
Lists

Create a list

Creates a list on the given object type. A dynamic list derives its membership from the SQL query; a static list starts empty. Returns the created list.

POST
/workspaces/{workspace}/objects/{object}/lists

Authorization

Authorization<token>

API key authentication. Send your key in the Authorization header as: api-key <your-api-key>.

In: header

Path Parameters

workspace*string

The workspace slug — the {slug} segment of your Clarify workspace URL.

object*string

The object type: a built-in entity (person, company, deal, …) or a custom object (c_*).

Query Parameters

silent?boolean

When true, suppresses in-app and Slack notifications for this mutation.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/workspaces/string/objects/string/lists" \  -H "Content-Type: application/json" \  -d '{    "title": "Enterprise deals",    "emoji": "🏢",    "description": "Open deals with enterprise accounts.",    "layout": "table",    "type": "dynamic",    "query": {      "sql": "SELECT * FROM deal WHERE amount >= 50000"    }  }'
{  "data": {    "type": "list",    "id": "9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f",    "attributes": {      "_id": "9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f",      "user_id": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81",      "entity": "deal",      "title": "Enterprise deals",      "emoji": "🏢",      "description": "Open deals with enterprise accounts.",      "type": "dynamic",      "state": "published",      "layout": "table",      "options": {},      "query": {        "sql": "SELECT * FROM deal WHERE amount >= 50000"      },      "owner_id": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81",      "rank": 0,      "applied_version_id": null,      "list_evaluation_status": "idle",      "list_evaluation_started_at": null,      "last_list_evaluation_at": "2026-02-01T17:45:00.000Z",      "_updated_at": "2026-02-01T17:45:00.000Z",      "_updated_by": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81",      "_created_at": "2026-01-15T09:30:00.000Z",      "_created_by": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81"    }  }}

Export a list’s rows as CSV

Streams the rows of a list as a `text/csv` file download. The first row is a header of field names. Pass a `sql` statement in the body to export a custom query instead of the list’s own rows.

Delete a list

Permanently deletes a list. The object’s default list and the last remaining list on an object cannot be deleted. This cannot be undone.