Lists

A list is a reusable, named set of companies or people. Signal setups watch lists: a signal that works on a list carries a list_id in its parameters (see Signal Setups). Lists belong to your workspace and exist independently of any signal setup.

Endpoints

Single-list endpoints are keyed by kind and list_id. kind is company or profile and matches the kind of the list, because companies and people have their own ID sequences. The collection endpoints take no kind.

Kind follows from type

Every list has a type, set at creation and never changed. The type decides the kind of the list, so you never send a kind when you create one:

Monitoring accounts

Customer and prospect lists are the lists whose accounts you can monitor. Monitoring covers the account's mapping, signals and content, and is paid per account and per persona. To monitor or stop a whole list, including the accounts that join it later, send signal_buckets on Update a list. To pick accounts one by one, use Monitor or stop accounts. See Account Monitoring.

Each customer or prospect list read carries monitoring_by_persona: one entry per persona the list is watched for (its attached personas, or every active persona when it is attached to none), each with persona_id, monitored_count (the accounts of the list monitored, and paid for, in that persona) and not_covered_count (the accounts with monitoring on in that persona but not paid for). Every entry reads 0 while the list is archived.

On every other list (competitors, partners, influencers, champions), an account is either in the list or not: add or remove the member.

The employee list is your "All my employees" list: every workspace has exactly one, created for you. You add and remove people in it like any people list, but it cannot be created, deleted, archived or moved to a persona. The "Engaged with my content on LinkedIn" signal reads the posts of the people on it.

Tiers

Prospect lists carry a tier (1, 2 or 3). You can set it when you create the list, and a prospect list created without one gets Tier 1. It never changes afterwards: create another list rather than re-tiering one. Every other list, customer lists included, returns tier: null, and sending a tier for one is refused with 422. A list can be deleted or archived while another list of the same kind covers its persona (for a prospect list, another list of the same tier): the only prospect Tier 1 list for a persona, for example, stays. Each list says whether it can go right now in is_deletable and, when it cannot, why in not_deletable_reason.

Personas

persona_ids tells which personas a list belongs to. An empty array means the list is visible from every persona. A list attached to several personas is monitored, and charged, in each of them. A monitored list attached to no persona is monitored, and charged, in every active persona.

Members

A member's id is the ID the rest of the API uses for that company or person: the one GET /api/v3/companies/{company_id} takes for a company, and the one GET /api/v3/leads/{lead_id} takes for a person. Pass it as member_id to remove the member.

Smart lists

Smart lists are managed in the app; their members can't be added or removed through the API. A list's mode is manual or smart and is read-only. The members of a smart list can still be read.

Archived, deleted, restored

An archived list keeps every member and leaves the default listing: pass archived: true to Update a list, and archived: false to bring it back. List lists returns archived lists with include_archived=true. archived and archived_at tell the two apart.

A deleted list stops being returned by every endpoint, but nothing is destroyed: Restore a list brings it back with its members and settings. Archiving or deleting a monitored list stops its monitoring (the month already paid is not refunded). An archived list keeps its signal_buckets, and every monitoring_by_persona entry reads 0 while it is archived; restoring or unarchiving it restores the monitoring, and charging, right away.

Deleting a list is refused while a signal setup still watches it.