Create List

Creates a workspace-scoped list. Set the immutable type — the list kind (company or people) is derived from it server-side, you never declare it. A new list starts empty; add members with Add members.

default_tracking_status applies to every member that does not carry its own override, and you can change it later with Update list. default_signal_bucket is read-only — it is returned on the created list but cannot be set here. tier can be set once, at creation, on a customer or prospect list only, and never changed afterwards — create a new list rather than re-tiering an existing one, since a tier change would silently re-tier every account already on it.

A list is filled by hand, with Add members and Remove member.

Create list

POST/api/v2/lists

Request body

Field	Type	Description
type	enum	Required, immutable. One of `competitor`, `partner`, `customer`, `prospect` (company) or `influencer`, `champion` (people). `employee` is created for you and cannot be created here.
name	string	Required, non-empty. Display name.
description	string	Optional free-text description.
default_tracking_status	enum	Optional. `followed` or `unfollowed`. Defaults to `followed`.
tier	integer	Optional, nullable. `1`, `2` or `3`. Only allowed on a `customer` or `prospect` list — sending it on any other type returns a `400`. Immutable after creation.
persona_ids	integer[]	Optional. The personas this list belongs to. Omit, or send an empty array, to create a list that applies to every persona.

No other field is accepted. default_signal_bucket is read-only, and any unknown key in the body is ignored.

Example request

curl -X POST "https://api.getsillage.com/api/v2/lists" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "competitor",
    "name": "Key competitors",
    "description": "Companies we track for competitive signals",
    "default_tracking_status": "followed",
    "persona_ids": [12, 15]
  }'

Example response

201 Created

{
  "data": {
    "id": 128,
    "kind": "company",
    "type": "competitor",
    "name": "Key competitors",
    "description": "Companies we track for competitive signals",
    "tier": null,
    "default_tracking_status": "followed",
    "default_signal_bucket": "bucket_1",
    "member_count": 0,
    "bound_agent_count": 0,
    "archived_at": null,
    "persona_ids": [12, 15]
  }
}

Response fields

Field	Type	Description
data.id	integer	Identifier of the list. Specific to your environment.
data.kind	string	`company` or `profile`, derived from `type`.
data.type	string	The immutable list type.
data.name	string	Display name.
data.description	string	Description, or `null`.
data.tier	integer	`1`, `2` or `3` on `customer` and `prospect` lists; `null` on every other type or when omitted at creation. Settable only at creation, never afterwards.
data.default_tracking_status	string	`followed` or `unfollowed` — applies to every member that has no override of its own.
data.default_signal_bucket	string	`bucket_1`, `bucket_2` or `bucket_3` — applies to every member that has no override. Read-only; a new list is always `bucket_1`.
data.member_count	integer	Number of members.
data.bound_agent_count	integer	Number of agents bound to this list.
data.persona_ids	integer[]	The personas this list belongs to. An empty array means the list applies to every persona.

Errors

Status	Description
400	A `tier` was sent on a list whose type is neither `customer` nor `prospect`.
401	The API key is missing or invalid.
422	Invalid body — unknown `type`, missing or empty `name`, a `type` of `employee`, an unknown `default_tracking_status`, or a `persona_ids` entry that does not belong to your workspace.
429	Too many requests.
500	An unexpected server error occurred.