Create a list

Creates a list in your workspace. What it holds follows from its type, which cannot be changed afterwards.

There is no idempotency key: sending the same request twice creates two lists. Before you retry, check the state with GET /v3/lists.

Access modes

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

Authorization: Bearer sk_live_...

Body parameters

Parameter	Type	Description
type	string	Required. `competitor`, `partner`, `customer`, `prospect`, `influencer` or `champion`. The `employee` list comes with the workspace and cannot be created here. It cannot be changed later, and it decides whether the list holds companies or people.
name	string	Required. Name of the list. A list name is a label: duplicates are allowed. Up to 255 characters.
description	string	Optional. Up to 1000 characters.
signal_buckets	array of string or null	Optional. Customer and prospect lists only. Monitors every account of the list, including the accounts that join later: `["essential"]`. `null`, or leaving it out, adds accounts without monitoring them.
tier	integer or null	Optional. Prospect lists only: `1`, `2` or `3`; a prospect list created without a tier gets `1`. Refused with `422` on every other type, customer lists included. Set once: it cannot be changed afterwards.
persona_ids	array of integer	Optional. IDs of the personas to attach the list to, from List personas. Leave it out to create 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.

Only these fields can be sent. Any other field is refused with a 422.

Example request

curl -X POST "https://api.getsillage.com/api/v3/lists" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "customer",
  "name": "Key customers",
  "description": "The accounts we want to keep watching",
  "signal_buckets": [
    "essential"
  ],
  "persona_ids": [
    7
  ]
}'

Success response

Status: 201 Created

{
  "data": {
    "id": 12,
    "kind": "company",
    "type": "customer",
    "name": "Key customers",
    "description": "The accounts we want to keep watching",
    "member_count": 0,
    "bound_signal_setup_count": 0,
    "tier": null,
    "signal_buckets": ["essential"],
    "monitoring_by_persona": [
      { "persona_id": 7, "monitored_count": 0, "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.
422	The body is not valid: a field is missing or unknown, a `name` or `description` is longer than allowed, there are more than 100 `persona_ids`, `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"), `tier` is sent for a list that is not a prospect list (`errors.tier` says "is only allowed on prospect lists"), or a `persona_ids` entry is not one of your personas (`errors.persona_ids[1]` says "must be the id of a persona of this workspace. See GET /v3/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.