Lists

A list holds records of one object. A static list is hand-picked, a smart list is every record matching its filter (kept current as records change), and a cohort is a recurring call list. Lists hold records, so they use the records scopes: reading is records:read, and adding or removing members is records:write. Every call also checks the list’s own sharing, as the key’s creator.

List your lists

GET /v1/lists returns every list the key’s creator can read. Pass object (an object’s id, key or name) to keep only that object’s lists.

curl "https://api.custral.com/v1/lists?object=Companies" \
  -H "Authorization: Bearer $CUSTRAL_API_KEY"

[
  {
    "id": "comp_3Ab9xK2mQ7",
    "name": "Live customers",
    "kind": "smart",
    "objectId": "obj_5Bc0xJ1kP4",
    "objectName": "Companies",
    "recordCount": 42,
    "doneCount": 0,
    "targetSize": null,
    "filterCount": 1
  }
]

Retrieve a list and its members

GET /v1/lists/{id} returns the list and a page of its members, with total for the whole list. Page with limit (1 to 200, default 50) and offset. A smart list’s members are read from its filter at the moment you ask.

curl "https://api.custral.com/v1/lists/comp_3Ab9xK2mQ7?limit=100&offset=0" \
  -H "Authorization: Bearer $CUSTRAL_API_KEY"

{
  "list": {"id": "comp_3Ab9xK2mQ7", "name": "Live customers", "kind": "smart", "objectId": "obj_5Bc0xJ1kP4", "objectName": "Companies", "recordCount": 42, "doneCount": 0, "targetSize": null, "filterCount": 1},
  "members": [
    {"recordId": "rec_7Dd2xL3nR6", "name": "Hooli", "done": false}
  ],
  "total": 42
}

boolean

Whether the record has been marked worked on this list. Per list: the same record can be done on one list and not another.

Add or remove records

POST /v1/lists/{id}/records adds up to 500 records to a static list or a cohort’s current period. POST /v1/lists/{id}/records/remove takes them off. Both answer record by record, so one bad id never fails the rest. A smart list’s members come from its filter, so both calls refuse one with list_membership_by_filter. Change the filter in the app instead.

curl -X POST https://api.custral.com/v1/lists/comp_9Ee4xM5oS8/records \
  -H "Authorization: Bearer $CUSTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recordIds": ["rec_7Dd2xL3nR6", "rec_2Ff6xN7pT0"]}'

{
  "changed": ["rec_7Dd2xL3nR6"],
  "unchanged": ["rec_2Ff6xN7pT0"],
  "missing": [],
  "wrongObject": []
}

string[]

Records already in the state you asked for: already on the list for an add, not on it for a remove.

string[]

Records of a different object than the list’s. A list holds one object’s records.

With the SDK

import {Custral} from "@custral/sdk";

const custral = new Custral({apiKey: process.env.CUSTRAL_API_KEY});

const lists = await custral.lists.list({object: "Companies"});
const {members, total} = await custral.lists.retrieve(lists[0].id, {limit: 100});
await custral.lists.addRecords("comp_9Ee4xM5oS8", ["rec_7Dd2xL3nR6"]);

With MCP

An MCP client holding mcp:read and records:read can read lists. With mcp:write and records:write it can also create lists and add records to them. Removing records is never offered over MCP.

Introduction

Endpoints

Embeds & real-time

List your lists

Retrieve a list and its members

Add or remove records

With the SDK

With MCP

​List your lists

​Retrieve a list and its members

​Add or remove records

​With the SDK

​With MCP

List your lists

Retrieve a list and its members

Add or remove records

With the SDK

With MCP