Segments API

A segment is a saved audience definition — a filter over your contacts (attributes, custom fields, engagement history, loyalty traits) that campaigns, flows, and personalization can target. The saved-segment CRUD surface lives under the Contacts API; this page covers the top-level segment endpoints that operate on audiences without requiring you to save one first, plus AI-assisted segment discovery. Base path: /api/v1/segments (ad-hoc + AI endpoints below) and /api/v1/contacts/segments (saved-segment CRUD, membership, and its own GET /{id}/export.csv — see the Contacts API). Authentication: API key (X-API-Key) or session JWT.

Method	Path	Scope	Purpose
`POST`	`/api/v1/segments/auto-suggest`	`contacts:write`	AI-proposed high-value segments from your org’s own data
`POST`	`/api/v1/segments/export.csv`	`contacts:write`	Export an ad-hoc (unsaved) audience as CSV
`POST`	`/api/v1/segments/from-clicks`	`contacts:write`	Turn short-link clickers into a saved, retargetable segment

AI auto-suggest

Unlike the description-driven segment builder (POST /contacts/segments/autopilot, which turns a sentence like “everyone who clicked the pricing page but didn’t book a demo” into a filter), auto-suggest takes no input — it reads your org’s own CDP event volume (top event names, contact tags, engagement histogram) and proposes up to 5 segments you probably haven’t created yet, each with a name, a one-line pitch, a rationale, and a ready-to-use filter. Nothing is persisted — the operator picks a suggestion to pre-fill the create-segment dialog.

Ad-hoc CSV export

GET /contacts/segments/{id}/export.csv already streams a saved segment’s membership as CSV. POST /segments/export.csv covers the case where you haven’t saved a segment yet — you have a filter (the same filter shape the segment builder and auto-suggest use) and just want the matching contacts as a one-off download, without persisting a segment or waiting for membership to materialize. Hard-capped at 50,000 rows per call (the optional limit in the body can set a lower cap). When the result set hits the cap, the response carries an X-Export-Truncated: true header so you know the file is partial — save the audience as a segment and use the paginated saved-segment export for a larger or recurring pull.

Clicked-link cohorts

POST /segments/from-clicks closes the loop from link engagement to audience: given a tracked short link (link_id) or every link in a campaign (campaign_id), it resolves the distinct contacts who clicked and materializes them as a static segment — no filter rules, just a point-in-time snapshot of “people who clicked this.” Useful for a targeted re-engagement send to exactly the people who showed interest. Because click activity is a point-in-time event rather than a live trait, the resulting segment does not auto-refresh — generate a fresh cohort to capture a later window. The request body must contain at least one of link_id or campaign_id, and accepts an optional window_days (1–365), name, and description.

Examples

POST /segments/auto-suggest

Request (all fields are optional — limit defaults to 5 and is clamped to 8):

curl -X POST https://api.orbit.devotel.io/api/v1/segments/auto-suggest \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 5, "focus_hint": "focus on retention" }'

Each returned suggestion carries name, description (a one-line, operator-facing pitch), rationale (why it is high-value for your data), and filters (a filter tree you can persist as-is). Every suggestion is validated against your contacts before the response — suggestions that would match nothing are dropped, and llm_dropped_count tells you how many were filtered out.

{
  "data": {
    "suggestions": [
      {
        "name": "Recently Engaged Buyers",
        "description": "Customers who interacted with any channel in the last 30 days.",
        "rationale": "Your top event volume is purchase-heavy, and contacts with recent message activity convert better on re-engagement sends.",
        "filters": {
          "op": "AND",
          "conditions": [
            { "field": "lifecycle_stage", "op": "equals", "value": "customer" },
            { "field": "last_message_at", "op": "in_last", "value": "30d" }
          ]
        },
        "preview_match_count": 4321
      },
      {
        "name": "Lapsed Email Openers",
        "description": "Contacts who have opened an email before, but not in the last 30 days.",
        "rationale": "A win-back audience: they historically engaged over email, so a re-open campaign on the same channel has a fair shot.",
        "filters": {
          "op": "AND",
          "conditions": [
            { "field": "last_opened_email", "op": "is_set" },
            { "field": "last_opened_email", "op": "not_in_last", "value": "30d" }
          ]
        },
        "preview_match_count": 1187
      }
    ],
    "org_summary": {
      "total_events_30d": 128402,
      "top_event_names": [
        { "event_name": "page_view", "count": 42211 },
        { "event_name": "purchase_completed", "count": 9104 }
      ],
      "top_segment_labels": [
        { "segment_label": "champion", "count": 214 },
        { "segment_label": "engaged", "count": 1860 }
      ],
      "top_tags": [
        { "tag": "vip", "count": 402 },
        { "tag": "trial", "count": 1337 }
      ],
      "total_contacts": 15640
    },
    "llm_output_preview": "{\"suggestions\":[{\"name\":\"Recently Engaged Buyers\",...",
    "llm_dropped_count": 0
  },
  "meta": {
    "request_id": "req_9f8e7d6c5b4a3210",
    "timestamp": "2026-08-25T09:41:12.083Z"
  }
}

If the org has no usable CDP signal yet (zero contacts or zero events in the last 30 days), the endpoint skips the AI round-trip and responds with an empty list plus a hint:

{
  "data": {
    "suggestions": [],
    "org_summary": { "total_events_30d": 0, "top_event_names": [], "top_segment_labels": [], "top_tags": [], "total_contacts": 0 },
    "llm_output_preview": "",
    "llm_dropped_count": 0,
    "note": "Not enough CDP signal yet — emit some events via the /events/track or /cdp/v1/:ingest_id/track endpoints to seed suggestions."
  },
  "meta": { "request_id": "req_9f8e7d6c5b4a3211", "timestamp": "2026-08-25T09:41:12.083Z" }
}

Other failure modes are explicit error envelopes — 422 AI_PARSE_FAILED when the model output is not parseable, 502 AI_SUGGEST_FAILED when the suggestion call itself fails, and 503 SERVICE_UNAVAILABLE when auto-suggest is not enabled on the deployment. Retry on 502; on 422 and 503, fall back to the manual segment builder.

POST /segments/export.csv

Request — any filter tree the segment builder accepts, plus an optional per-call row cap and download filename:

curl -X POST https://api.orbit.devotel.io/api/v1/segments/export.csv \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "op": "AND",
      "conditions": [
        { "field": "lifecycle_stage", "op": "equals", "value": "customer" },
        { "field": "email_opt_in", "op": "equals", "value": true },
        { "field": "country_code", "op": "in", "value": ["US", "CA"] }
      ]
    },
    "limit": 5000,
    "filename": "na-customers-opted-in"
  }'

A 200 response is the CSV itself (Content-Type: text/csv, Content-Disposition: attachment; filename="na-customers-opted-in-2026-08-25.csv"). Phone and email columns honour the caller’s role and reveal-context exactly as the dashboard does — a caller without reveal permission receives masked values.

contact_id,first_name,last_name,email,phone,country_code,lifecycle_stage,tags,created_at
cnt_8f3a2b1c4d5e6f708192a3b4c5d6e7f8,Ada,Lovelace,ada@example.com,+14155550123,US,customer,"vip,newsletter",2026-03-14T08:22:10.411Z
cnt_1a2b3c4d5e6f708192a3b4c5d6e7f809,Grace,Hopper,grace@example.com,+14155550124,CA,customer,"newsletter",2026-04-02T17:03:44.902Z
cnt_5e6f708192a3b4c5d6e7f8091a2b3c4d,Alan,Turing,alan@example.com,,US,customer,,2026-05-21T11:47:01.265Z

An invalid filter (a non-allowlisted field, a mismatched operator, or a body that fails shape validation) returns a 400 envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unknown segmentation field \"lifecycle\". Use one of the allowlisted fields or a 'custom_attributes.<key>' path.",
    "status": 400
  },
  "meta": { "request_id": "req_9f8e7d6c5b4a3212", "timestamp": "2026-08-25T09:41:12.083Z" }
}

Two rate limits apply to this endpoint: a heavy export is capped at 5 requests per minute per tenant, and a generic per-key limit sits on top of that. On 429, wait for the window and retry with backoff; for pulls that routinely exceed the 50,000-row hard cap or the rate budget, persist the audience as a segment and page through GET /contacts/segments/{id}/export.csv instead.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests, retry later.",
    "status": 429
  },
  "meta": { "request_id": "req_9f8e7d6c5b4a3213", "timestamp": "2026-08-25T09:41:12.083Z" }
}

POST /segments/from-clicks

Request — scope the cohort by link_id or campaign_id, optionally narrow to a recency window and name the segment:

curl -X POST https://api.orbit.devotel.io/api/v1/segments/from-clicks \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "cmp_a1b2c3d4e5f6a7b8", "window_days": 30, "name": "Clicked Q3 promo" }'

On success the response is a 201 with the persisted segment and its materialized membership count:

{
  "data": {
    "segment": {
      "id": "seg_9b8a7f6e5d4c3b2a01928374a5b6c7d8",
      "name": "Clicked Q3 promo",
      "description": null,
      "auto_refresh": false
    },
    "member_count": 1842
  },
  "meta": { "request_id": "req_9f8e7d6c5b4a3214", "timestamp": "2026-08-25T09:41:12.083Z" }
}

Because the segment row now exists, every saved-segment surface applies to it — for example, to pull the cohort as CSV:

curl -X GET "https://api.orbit.devotel.io/api/v1/contacts/segments/seg_9b8a7f6e5d4c3b2a01928374a5b6c7d8/export.csv?limit=500" \
  -H "X-API-Key: dv_live_sk_your_key_here"

If no contacts have clicked the link(s) yet — or clicks exist but none are message-attributed back to a recipient contact — the endpoint returns a 422 instead of creating an empty segment:

{
  "error": {
    "code": "EMPTY_COHORT",
    "message": "No contacts have clicked the requested link(s) yet, so there is no cohort to materialise. Clicks must be message-attributed (the link was sent in a message bound to a contact) to resolve back to a recipient.",
    "status": 422
  },
  "meta": { "request_id": "req_9f8e7d6c5b4a3215", "timestamp": "2026-08-25T09:41:12.083Z" }
}

Recipe: auto-suggest → saved segment → campaign target

The full loop, end to end:

Get suggestions. POST /segments/auto-suggest and read data.suggestions. Each suggestion’s filters is a ready-to-persist filter definition.
Pick one and persist it. Pass the suggestion’s filters to the saved-segment create endpoint with a name — membership materializes immediately on create, so the segment is usable without waiting for the refresh cycle:

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": "Recently Engaged Buyers",
    "description": "Customers active in the last 30 days.",
    "filters": {
      "op": "AND",
      "conditions": [
        { "field": "lifecycle_stage", "op": "equals", "value": "customer" },
        { "field": "last_message_at", "op": "in_last", "value": "30d" }
      ]
    }
  }'

Use the returned segment id. Target it from a campaign audience, a flow trigger, or the personalization rule engine — anywhere a segment_id is accepted. A saved segment auto-refreshes (unless you created it from a click cohort, which is a fixed snapshot), so step 2 is done once and steps 1–3 can be repeated whenever you want fresh suggestions.

To sanity-check membership before committing the segment to a campaign, post the same filters body to POST /segments/export.csv and download the matching rows — that one-off export never persists anything.

SDK note

The Node SDK covers saved-segment CRUD (orbit.contacts.segments.list() / .create() / .get() over /contacts/segments). The three ad-hoc endpoints on this page — auto-suggest, ad-hoc export, and click cohorts — are invoked directly over HTTP as shown above; parse the CSV responses yourself or save the audience as a segment and use the SDK’s saved-segment surface.

API Reference

All Endpoints

Segments API: build and export contact audiences

Segments API

AI auto-suggest

Ad-hoc CSV export

Clicked-link cohorts

Examples

POST /segments/auto-suggest

POST /segments/export.csv

POST /segments/from-clicks

Recipe: auto-suggest → saved segment → campaign target

SDK note

See also

​Segments API

​AI auto-suggest

​Ad-hoc CSV export

​Clicked-link cohorts

​Examples

​POST /segments/auto-suggest

​POST /segments/export.csv

​POST /segments/from-clicks

​Recipe: auto-suggest → saved segment → campaign target

​SDK note

​See also

Segments API

AI auto-suggest

Ad-hoc CSV export

Clicked-link cohorts

Examples

POST /segments/auto-suggest

POST /segments/export.csv

POST /segments/from-clicks

Recipe: auto-suggest → saved segment → campaign target

SDK note

See also