Get a list

Returns one list.

Access modes

Use a workspace API key. The workspace is inferred from the key.

Authorization: Bearer sk_live_...

Path parameters

Parameter	Type	Description
kind	string	`company` or `profile`. It matches the `kind` of the list.
list_id	integer	ID of the list.

Query parameters

Parameter	Type	Description
response_format	string	`concise` or `normalized` (default). `concise` returns `id`, `kind`, `type` and `name` only; `normalized` adds the other fields. With `concise`, the other fields are absent, not `null`.

Example request

curl "https://api.getsillage.com/api/v3/lists/company/12" \
  -H "Authorization: Bearer $SILLAGE_API_KEY"

Success response

Status: 200 OK

{
  "data": {
    "id": 12,
    "kind": "company",
    "type": "customer",
    "name": "Key customers",
    "description": "The accounts we want to keep watching",
    "member_count": 48,
    "bound_signal_setup_count": 0,
    "tier": null,
    "signal_buckets": ["essential"],
    "monitoring_by_persona": [
      { "persona_id": 7, "monitored_count": 48, "not_covered_count": 0 }
    ],
    "mode": "manual",
    "archived": false,
    "archived_at": null,
    "persona_ids": [7],
    "is_deletable": true,
    "not_deletable_reason": null
  }
}

Response fields

Field	Type	Description
data.id	integer	ID of the list.
data.kind	string	`company` or `profile`. Follows from `type`, read-only.
data.type	string	What the list is for: `competitor`, `partner`, `customer`, `prospect`, `influencer`, `champion` or `employee`.
data.name	string	Name of the list.
data.description	string or null	Description of the list. Left out with `response_format=concise`.
data.member_count	integer	How many companies or people are on the list. Left out with `concise`.
data.bound_signal_setup_count	integer	How many signal setups and older app signals use this list.
data.tier	integer or null	Tier of the list, `1` to `3`, on prospect lists. `null` on every other type.
data.signal_buckets	array of string or null	`["essential"]` when every account of the list is monitored, including the accounts that join later. `null` when the whole list is not monitored. Only customer and prospect lists carry it. An archived list keeps its value, restored when you unarchive it. Left out with `concise`.
data.monitoring_by_persona	array of object or null	One entry per persona the list is watched for: its attached personas, or every active persona when it is attached to none. `null` on lists that are not customer or prospect lists. Left out with `concise`.
data.monitoring_by_persona[].persona_id	integer	ID of the persona.
data.monitoring_by_persona[].monitored_count	integer	Accounts of the list monitored, and paid for, in this persona. `0` while the list is archived.
data.monitoring_by_persona[].not_covered_count	integer	Accounts of the list with monitoring on in this persona but not paid for. `0` while the list is archived.
data.mode	string	`manual` or `smart`. See Smart lists. Read-only. Left out with `concise`.
data.archived	boolean	`true` while the list is archived.
data.archived_at	string or null	When the list was archived, as an ISO 8601 timestamp. `null` while it is in use.
data.persona_ids	array of integer	IDs of the personas the list belongs to. An empty array means the list is visible from every persona. A monitored list attached to no persona is monitored, and charged, in every active persona. Left out with `concise`.
data.is_deletable	boolean	Whether deleting or archiving the list would succeed right now. Left out with `concise`.
data.not_deletable_reason	string or null	Why the list cannot be deleted or archived, `null` when it can: `last_list_of_tier` (it is the only list of its kind for its persona, for a prospect list of its tier, such as the only prospect Tier 1 list for this persona, or the only one attached to no persona: create another one first), `in_use` (a signal setup, or an older signal set up in the Sillage app, uses it) or `employee_list` (the "All my employees" list is never deleted). New values may be added; ignore values you don't know.

Errors

Status	Meaning
401	The API key is missing or invalid.
404	The list does not exist.
422	`kind` or `list_id` is not valid, or a query parameter is not known.
429	Rate limit exceeded.
500	An unexpected server error occurred.

Error responses use RFC 9457 problem documents with Content-Type: application/problem+json. type is always about:blank; code tells one problem from another, detail says what went wrong this time, and errors names the field at fault.