Lists
Reusable lists of companies or people that signal agents watch.
A list is a reusable, named set of companies or people that you bind to a signal agent. The agent then surfaces interactions involving the list's members. Lists are workspace-scoped and exist independently of any agent — one list can be bound to several agents over time.
Coming from /api/v2/watchlists? Lists replace it. The old path keeps answering for existing integrations but is no longer documented and will be withdrawn. Four things change on the wire: title becomes name, entity_count becomes member_count, the /entities sub-resource becomes /members, and the add-members request body key entities becomes members. The HTTP verbs and status codes are unchanged. Lists also return fields the old path does not: tier and default_signal_bucket on the list, and signal_bucket on each member. Everything else keeps its name.
Kind is derived from type
Every list has an immutable type, set at creation. The type determines the list kind (company vs people) — you never declare the kind yourself:
type | kind | members |
|---|---|---|
competitor | company | companies |
partner | company | companies |
customer | company | companies |
prospect | company | companies |
influencer | profile | people |
champion | profile | people |
employee | profile | people |
The employee list, "All my employees", is created for you with every workspace and is the only one of its type. You cannot create another one, delete it or archive it, nor change the personas it belongs to; renaming it and adding or removing its members works as on any other list.
type cannot be changed after creation (it would move the list across kinds). name and description are editable.
Tracking and signal buckets
A list carries two defaults that apply to every member:
| Field | Values | Meaning |
|---|---|---|
default_tracking_status | followed, unfollowed | Whether Sillage watches the members for new signals. Defaults to followed. |
default_signal_bucket | bucket_1, bucket_2, bucket_3 | A label carried on every member. Defaults to bucket_1. Read-only. |
Each member can override either one. A member's tracking_status or signal_bucket set to null means the member follows the list default — that is the normal case, and it is what you get for a member you never touched. Set an explicit value to make one member behave differently from the rest of the list, and set it back to null to return it to the list default.
An unfollowed member is not watched for new signals and does not consume credits.
Signal buckets are stored and returned only. They change nothing about how a member is processed today; they exist so you can label members ahead of a future usage-based plan. default_signal_bucket is read-only over the API: it is returned on every list but cannot be set on create or update.
default_tracking_status is the one default you can write, on Create list and on Update list.
Tiers
Company lists of type customer and prospect can carry a tier (1, 2 or 3), which lets you rank your accounts by importance. A company can belong to several tiered lists; the highest tier is the one that applies to it.
tier is read-only over the API and it is nullable with no default: a list that has never been given a tier returns tier: null, and so does every list created before tiers existed. Every list of another type, and every list of people, returns tier: null as well, since only company lists carry the field at all. A tier is assigned by converting a segment into a list inside Sillage, not through this API, so there is no request body field for it.
Archived, deleted, restored
A list leaves your workspace's view in one of two ways, and neither one loses anything.
| What you do | What happens to it | How to undo | |
|---|---|---|---|
| Archive | pass archived: true to Update list | keeps every member; drops out of List all lists unless you pass include_archived=true | pass archived: false |
| Delete | Delete list | stops being returned by every endpoint | Restore list |
archived_at tells the two apart: it carries a timestamp on an archived list and null on an active one. A deleted list has no readable state — it simply is not there until you restore it.
Archive the lists you may want back in view. Delete the ones you consider finished. Either way the companies and people on them are shared across your workspace and are never touched.
Endpoints
Single-list endpoints are keyed by a compound /:kind/:list_id path, where kind is company or profile and matches the list's immutable type. The company and profile collections have independent id sequences, so the kind disambiguates which one a list_id refers to (no cross-kind id collision). The collection endpoints take no kind.
- Create list:
POST /api/v2/lists - List all lists:
GET /api/v2/lists - Get list:
GET /api/v2/lists/:kind/:list_id - Update list:
PUT /api/v2/lists/:kind/:list_id - Delete list:
DELETE /api/v2/lists/:kind/:list_id - Restore list:
POST /api/v2/lists/:kind/:list_id/restore - Add members:
POST /api/v2/lists/:kind/:list_id/members - List members:
GET /api/v2/lists/:kind/:list_id/members - Remove member:
DELETE /api/v2/lists/:kind/:list_id/members/:member_id - Set member tracking status:
PATCH /api/v2/lists/:kind/:list_id/members/:member_id/tracking-status - List membership log:
GET /api/v2/lists/:kind/:list_id/membership-logs
Binding to an agent
Bind a list to an agent with the watchlist_id field on Create agent or Update agent — the binding fields kept their original names. On update you may also send watchlist_kind, but you do not have to: it is worked out from the agent's own type. An agent watches at most one list; send watchlist_id: null to unbind. Sending watchlist_kind on its own, or a non-null kind with a null id, returns 422.