> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Static contact lists: create, fill, template, and export

> Build hand-curated contact lists for one-off blasts and re-engagement waves — create and duplicate lists, add and remove members, start from a template, export to CSV, and target the list from campaigns.

# Static contact lists

A contact list is a saved, hand-curated set of contacts. You decide exactly who is on it, and membership changes only when you (or an API call) add or remove someone. Use lists for one-off blasts, re-engagement waves, VIP cohorts, and any audience where a human picked the members. Everything below works in the dashboard under **Audience → Lists** and over the [Contacts API](/api-reference/endpoints/contacts) under `/api/v1/contacts/lists`.

## 1. Lists vs segments

Both target groups of contacts, but they answer different questions.

|                     | List (static)                                                               | Segment (dynamic)                                                             |
| ------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Membership          | Hand-curated; changes only on explicit add/remove                           | Computed from a filter; re-evaluated as contact data changes                  |
| Best for            | One-off sends, re-engagement waves, VIP cohorts, approved recipient rosters | Always-on targeting — "all active customers", "churn risk above 60%"          |
| Send-time behaviour | The campaign resolves a fixed roster                                        | The campaign can re-evaluate the filter and pick up contacts that newly match |
| Source of truth     | The add/remove history                                                      | The filter definition                                                         |

Pick a list when the audience is a decision, not a query: the 400 contacts legal approved for a regulatory notice, the lapsed customers you want to win back with one dedicated wave, the VIPs a success manager hand-picked. Pick a segment when the audience is a standing rule that should keep itself current — see [Build CDP segments](/guides/cdp-segments) and the [segment recompute model](/concepts/cdp-segment-recompute-model) for how membership stays materialized.

## 2. Create, edit, duplicate, delete

Create a list with a name and an optional description — up to 100 characters for the name and 500 for the description:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/contacts/lists \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Win-back wave — March",
    "description": "Contacts lapsed 90+ days, approved for one re-engagement wave"
  }'
```

In the dashboard, **Create list** opens the same two fields. Once a list exists, each card on the Lists page carries three actions:

* **Edit** renames the list or rewrites its description. Membership is untouched.
* **Duplicate** clones the list and copies every member into it. The new list is named after the source with a copy suffix, so an approved roster can branch into a second wave without re-curating. Over the API, `POST /api/v1/contacts/lists/{id}/duplicate` returns the new list plus the count of members copied.
* **Delete** removes the list and its member associations. The confirmation states how many contacts will be detached before you commit. Deleting a list never deletes the contacts themselves — they stay in your workspace, only the grouping is gone.

## 3. Members

Open a list to see its members panel: a searchable table of the members with name, phone, and email per row, and the list's member count in the header.

Add members in three ways:

* **Search and pick.** The add-members box searches your contacts as you type and shows matching rows. Click matches to stage them — each pick becomes a removable chip — then commit the whole selection in one request. The bulk endpoint `POST /api/v1/contacts/lists/{id}/members/bulk` accepts up to 1,000 contact ids per call, so curating a large roster is a handful of commits, not one request per person.
* **Direct identifier.** Paste a phone number (E.164 or national format — it is normalized server-side), an email, or a contact id and press Add: `POST /api/v1/contacts/lists/{id}/members` with `{ "identifier": "+15550101234" }`, or `{ "contact_id": "cnt_…" }` when you already know the canonical id. A known id added twice is a no-op — the response reports the contact was already a member rather than duplicating the row.
* **Import.** If the roster lives in a CSV, import it as contacts and attach them to a list in one pass — see [Import contacts](/guides/import-contacts).

Remove a member from the row's Remove action (confirming first — the dialog reassures the contact can be re-added later). Over the API, `DELETE /api/v1/contacts/lists/{id}/members/{memberId}` removes one member. Removal detaches the contact from this list only; the contact itself, and its place in every other list and segment, is untouched.

Lists do not go stale on their own — no one joins or leaves unless someone acts. That is the point, and it is also the discipline: a list built for a regulatory notice should be re-curated before its second use, because nothing in the platform will remove a contact who has since unsubscribed from a category. Eligibility (consent, opt-outs, quiet hours) is still enforced at send time by the messaging pipeline, but membership itself is frozen until you touch it.

## 4. Starter templates

On an empty workspace the Lists page offers four one-click starter lists. Each template creates an empty list with a pre-filled name and description you can edit after creation; members are then added the usual way.

| Template               | Pre-filled intent                                                 |
| ---------------------- | ----------------------------------------------------------------- |
| VIP Customers          | Highest-value contacts for white-glove campaigns and early access |
| Newsletter Subscribers | Opted-in contacts — the default broadcast audience                |
| Trial Users            | Contacts evaluating the product, for onboarding nudges            |
| Re-engagement          | Lapsed or inactive contacts for a win-back wave                   |

Templates are starting points, not rules: a templated list behaves exactly like one you created by hand.

## 5. Export

Two CSV exports answer two different questions:

* **Export the lists themselves** from the Lists page header. The file carries one row per list — list id, name, description, member count, and created/updated timestamps (rendered in your timezone) — which is the catalogue answer to "what audiences do we have curated right now?". An active search is honoured: export downloads the set you are looking at. Exports stop at 50,000 lists; narrow the search if you need a fully unfiltered download past that.
* **Export a list's members** from the members panel of an open list. The file carries one row per member — name, phone, email — which is the recipient-roster answer for a send you want to review or reconcile offline. The active member filter is honoured the same way, and the same 50,000-row cap applies.

For compliance workflows: a member export is a snapshot of membership, not a data-subject extract. When a person is erased through a data-subject request, their contact record and every list association go with it — lists recompute their member counts automatically. See [Data subject requests](/compliance/dsar) for erasure mechanics, and [Ad-hoc audience CSV export](/guides/audience-export-adhoc) when you need a one-off export built from a filter you have not saved as either a list or a segment.

## 6. Target a list from a campaign

A saved list is directly targetable by campaigns, broadcasts, and flows. Over the campaigns API, target it with `audience_type: "list"` and the list id:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/audience/preview" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_type": "list",
    "audience_id": "contactList_9f2a7c1e4b",
    "channel": "sms"
  }'
```

The preview returns the resolved member count plus a sample, so you can confirm the roster before launch. At send time the difference from segment targeting is when membership is frozen:

* A **list** resolves to the members it holds when the audience resolves — a fixed roster. Contacts added to the list after the send resolves are not swept into an in-flight send.
* A **segment** can re-evaluate its filter at send time, so a growing segment keeps working without anyone updating the campaign.

Choose per the table in section 1; either way, confirm the resolved count with the audience preview before launch. The full campaign field reference is in [Campaign end-to-end](/guides/campaign-end-to-end).

## 7. Route change

Lists used to live under **Contacts → Lists** as a tab on the Contacts hub. They now live under **Audience → Lists**, alongside segments. Old `/contacts/lists` links and bookmarks keep working — they redirect to the current route automatically.

## See also

* [Contacts API reference](/api-reference/endpoints/contacts) — lists CRUD, duplicate, members, and bulk member add
* [Build CDP segments](/guides/cdp-segments) — dynamic audiences from filters, computed traits, and scores
* [Segment recompute model](/concepts/cdp-segment-recompute-model) — how dynamic membership stays current
* [Import contacts](/guides/import-contacts) — bulk CSV ingest into lists
* [Campaign end-to-end](/guides/campaign-end-to-end) — send-time audience resolution and preview
* [Data subject requests](/compliance/dsar) — erasure and the membership records it removes