​

Lists vs segments: the two membership models

​

1. The two membership models

• A list is a stored set of contact ids. Membership is an explicit row: a contact is on the list because someone (or an API call) added them, and they leave only when someone removes them. The list holds the membership; the membership does not change unless the list itself is edited. There is no recompute, no filter, no “current state” to drift — the list is the current state.
• A segment is a stored predicate. Membership is a derived result: a contact is in the segment because, at the last recompute tick, running the segment’s filter against that contact’s profile returned true. The segment holds the rule, not the roster. The roster is materialized by running the rule, and it is re-run on the cadence the segment recompute model defines — a near-real-time per-contact pass on the event stream plus a scheduled batch backstop, with enriched profile traits refreshed daily.

​

2. What each ships with

​

The list model

• Manual add, manual remove. Members arrive by search-and-pick in the dashboard, by direct identifier (phone, email, or contact id) over the Contacts API, by bulk add (POST /api/v1/contacts/lists/{id}/members/bulk, up to 1,000 ids per call), or by CSV import that attaches contacts to a list in one pass. Removal is a row-level action; the contact itself is untouched — only the grouping is gone.
• Stable membership. Once added, a contact stays until removed. No background process touches the roster. This is the point and the discipline: a list built for a regulatory notice does not silently drop a contact who later unsubscribed — eligibility (consent, opt-outs, quiet hours) is still enforced at send time by the messaging pipeline, but membership is frozen until you touch it. Re-curate before reuse.
• No recompute. There is nothing to recompute. The member count is a count of rows, not a count of predicate matches. The list’s freshness is exactly the freshness of the last add/remove you performed.
• Ideal for fixed cohorts. Event invitees, a VIP group a success manager hand-picked, a suppression roster legal approved, a one-off re-engagement wave, a regulatory-notice recipient set that must not drift. See the static lists guide for the full workflow.

​

The segment model

• A predicate over contact data. The segment’s filter references profile fields, computed traits, scores, and behavioral events — “contacts whose lifecycle_stage is active and total_orders ≥ 5”, or “contacts in the top churn-risk tier.” The filter is the source of truth; the materialized membership is a read over it.
• Recomputed on a cadence. Membership is re-evaluated near-real-time per contact (the event-stream pass) and reconciled by a scheduled batch sweep; enriched profile traits the filter references are refreshed on a daily sweep. See the segment recompute model for the per-surface staleness table — the dashboard badge converges in ~1s, ad-audience syncs land in hours.
• Reflects fresh state automatically. A contact that newly qualifies is entered; one that no longer qualifies is exited. A growing segment keeps working in a recurring campaign without anyone editing the campaign — this is the property a list does not have.
• Ideal for standing rules. “Everyone who bought in the last 30 days”, “churn risk above 60%”, “active customers” — audiences that should keep themselves current. See the segments guide for building them, and the scoring pipeline for the scores a segment filter can read.

​

3. Decision table — which construct for which use case

​

4. How they interact

1. A segment can be materialized into a list (snapshotting). Export a segment’s current membership to CSV (GET /api/v1/contacts/segments/:id/export.csv), then import that CSV into a list — or, where the segments surface offers it, snapshot the current membership into a static list directly. The result is a list that holds the segment’s membership at the moment you materialized it. The snapshot does not inherit the segment’s recompute; it is a list from that point on, with all the list properties — stable, frozen, no recompute.
2. A list can be one input to a segment predicate. A segment filter can reference list membership — “in segment active_buyers and not in list suppression_roster” combines a derived audience with a stored one. The segment recomputes; the list’s membership is read as-is at recompute time. This is how a standing rule and a hand-curated suppression set compose.
3. A send can target either directly. Over the campaigns API, target a list with audience_type: "list" and the list id, or target a segment with its id. At send time the difference is when membership is frozen: a list resolves to the members it holds when the audience resolves (a fixed roster — contacts added after the send resolves are not swept in); a segment can re-evaluate its filter at send time, so a growing segment keeps working without anyone touching the campaign. See Campaign end-to-end for the send-time resolution.

​

The snapshot-then-diverge footgun

​

5. Scale and cost notes

• A list is O(rows stored). Member count is a row count; cost is the storage of the membership rows and the add/remove traffic you generate. A list of 1M contacts is 1M rows that do nothing until you touch them. There is no recompute spend, no per-send fan-out beyond resolving the roster.
• A segment’s cost follows the predicate complexity and the recompute cadence. A filter over a single profile field is cheap; a filter over behavioral event counts, computed traits, and scores costs the evaluation of each at every recompute tick. The real-time per-contact pass is bounded to the one contact an event binds to, but the scheduled batch sweep re-evaluates the tenant’s full auto-refresh set — a complex predicate across a large population is the expensive shape. See the segment recompute model for the cadence that drives the sweep.
• Very large segments fan out per-send. A send that targets a segment re-evaluates the filter at send time, and a journey that triggers on segment entry or exit enrolls every contact that crosses — the journey enrollment fan-out page defines the per-journey entry rate limit that bounds that blast radius. A list send resolves a fixed roster and does not re-evaluate; the fan-out difference is the send-time re-evaluation, not the membership size alone.

​

6. Worked example — a “last-90-day buyers” audience

​

Build it as a segment (for a weekly recurring campaign)

curl -X POST https://api.orbit.devotel.io/api/v1/contacts/segments \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Last-90-day buyers",
    "auto_refresh": true,
    "filter": {
      "all": [
        { "field": "last_order_at", "op": "gte", "value": "now-90d" },
        { "field": "total_orders", "op": "gte", "value": 1 }
      ]
    }
  }'

​

Materialize a one-time list copy (for a legal-notice send)

# 1. Export the segment's current membership to CSV.
curl "https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9f2a7c1e4b/export.csv" \
  -H "X-API-Key: dv_live_sk_your_key_here" -o last-90-day-buyers-legal-snapshot.csv

# 2. Import that CSV into a static list (see the import guide for the wizard).
#    The list now holds the snapshot — frozen, auditable, no recompute.

​

Contrast the two lifecycles

​

Cross-references

• Segment recompute model — when a segment’s membership actually moves, and the per-surface staleness table.
• CDP streaming destinations — streaming the membership-crossing events that drive a segment to a Kafka topic or Kinesis stream.
• Journey enrollment fan-out — the entry rate limit that bounds the blast radius when a journey triggers on segment entry or exit.
• Contact scoring pipeline — the daily scores a segment filter can read, and the on-demand pass for freshly imported contacts.
• Ad-audience incrementality — the holdout and lift measurement for a segment activated to a paid-media audience.
• Build CDP segments — the guide for building the segment whose lifecycle this page contrasts.
• Static contact lists — the guide for the list model this page contrasts.
• Audience hub — the tile map where Lists and the segment surfaces sit side by side on the grid.