Clarify API
Lists

Get a list

Returns a single list by ID as a JSON:API resource.

GET
/workspaces/{workspace}/objects/{object}/lists/{list}

Authorization

apiKey
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_*).

list*string

The unique ID of the list.

Response Body

application/json

curl -X GET "https://example.com/workspaces/string/objects/string/lists/string"
{
  "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"
    }
  }
}

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.

List an object’s lists

Returns the lists defined on an object type as a paginated JSON:API collection. Dynamic lists are excluded unless you pass a matching `filter`.