Update a list

Rename a list, archive it, change its personas, or monitor or stop a whole list.

Renames a list, changes its description, archives it or brings it back, replaces the personas it belongs to, and monitors or stops the whole list. The type of a list cannot be changed. Archiving follows the same rule as deleting: it is refused when the list 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), while a signal setup still watches it, and on the "All my employees" list, which cannot be moved to a persona either.

To monitor or stop a whole list, including the accounts added to it later, send signal_buckets: see Monitor or stop a whole list.

Route

PATCH/api/v3/lists/{kind}/{list_id}

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.

Body parameters

Parameter	Type	Description
name	string	New name. Up to 255 characters.
description	string or null	New description, up to 1000 characters. `null` clears it.
signal_buckets	array of string or null	Customer and prospect lists only. `["essential"]` monitors the whole list, `null` stops it. See Monitor or stop a whole list.
archived	boolean	`true` archives the list, `false` brings it back. Archiving keeps every member. Archiving a monitored list stops its monitoring (the month already paid is not refunded) but the list keeps its `signal_buckets`, and every `monitoring_by_persona` entry reads `0` while it is archived; bringing it back restores the monitoring, and charging, right away.
persona_ids	array of integer	Replaces the full set of personas the list belongs to. Leave it out to keep them; send `[]` to make the list visible from every persona. A monitored list attached to no persona is monitored, and charged, in every active persona. Up to 100 values. A change is refused with `409` when a signal setup using the list would be left on a list that is not attached to its persona: the answer names those signal setups in `signal_setup_ids`.

Send only the fields you want to change, at least one: an empty body {} is refused with 422. Any other field is refused with a 422, including type (it cannot be changed) and mode (it is read-only).

Monitor or stop a whole list

On a customer or prospect list, signal_buckets monitors or stops every account of the list at once:

"signal_buckets": ["essential"] monitors every account of the list, including the accounts added to it later.
"signal_buckets": null stops monitoring every account of the list, including the ones you picked one by one. The month already paid is not refunded.
Leaving signal_buckets out leaves the list and its accounts as they are.

A list attached to several personas is monitored, and charged, in each of them. To pick individual accounts instead, use Monitor or stop accounts. To see the result for each account, read the monitoring of List members. See Account Monitoring.

Sending signal_buckets on a list that is not a customer or prospect list is refused with 422, and errors.signal_buckets says "only allowed on customer or prospect lists".

Example request

This call monitors every account of the list, including the ones added later.

curl -X PATCH "https://api.getsillage.com/api/v3/lists/company/12" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "signal_buckets": [
    "essential"
  ]
}'

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.
data.member_count	integer	How many companies or people are on the list.
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.
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.
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.
data.is_deletable	boolean	Whether deleting or archiving the list would succeed right now.
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.
409	You tried to archive a list that cannot go: the only list of its kind for its persona (for a prospect list, of its tier), one a signal setup still watches, or the "All my employees" list (also refused when you move it to a persona). Or a `persona_ids` change would leave signal setups on a list that is not attached to their persona (`list_persona_setup_conflict`): `detail` says how to fix it and `signal_setup_ids` lists those signal setups.
422	The body is not valid, is empty (`{}`), a `name` or `description` is longer than allowed, there are more than 100 `persona_ids`, or it has an unknown field, `signal_buckets` is sent for a list that is not a customer or prospect list (`errors.signal_buckets` says "only allowed on customer or prospect lists"), or a `persona_ids` entry is not one of your personas.
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.

Update a list

On this page