Segments — CRUD & Evaluation

Create, read, update, and delete segments, plus duplicate them and evaluate their membership (preview, clients, passes, size, count). See the overview for the segment model and Filters for filter config.

Auth: Bearer token — workspace member. List / create are workspace-scoped by path; all other routes resolve the workspace from the segment row.

---

List Segments

GET /wallethero-api/workspace/:workspaceId/segments

Lists every segment in the workspace, newest first (sorted by -date_created).

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/segments" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "workspace_id": "WORKSPACE_ID",
      "name": "VIP Members",
      "description": "Gold and Platinum tiers",
      "filters": [],
      "date_created": "2026-01-10T08:00:00Z"
    }
  ]
}

SDK

const { data } = await wh.segments.list({
  filter: { workspace_id: { _eq: "WORKSPACE_ID" } },
});
// or:
const { data: byWs } = await wh.segments.getByWorkspace("WORKSPACE_ID");

---

Create Segment

POST /wallethero-api/workspace/:workspaceId/segments

Creates a segment. Filters are validated and each gets an id assigned.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Request Body

Field	Type	Required	Description
name	string	Yes	Segment name
description	string	No	Free-text description
filters	SegmentFilter[]	No	Filter objects (default []). See Filters

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/segments" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Members",
    "filters": [
      {
        "filter_type": "custom_field",
        "filter_config": {
          "custom_field_filters": {
            "tier": { "operator": "_in", "value": ["Gold", "Platinum"] }
          }
        }
      }
    ]
  }'

Response (201)

{
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "workspace_id": "WORKSPACE_ID",
    "name": "VIP Members",
    "filters": [
      { "id": "f1", "filter_type": "custom_field", "filter_config": { "custom_field_filters": { "tier": { "operator": "_in", "value": ["Gold", "Platinum"] } } } }
    ]
  }
}

SDK

const { data: segment } = await wh.segments.create({
  workspace_id: "WORKSPACE_ID",
  name: "VIP Members",
  filters: [
    {
      filter_type: "custom_field",
      filter_config: {
        custom_field_filters: { tier: { operator: "_in", value: ["Gold", "Platinum"] } },
      },
    },
  ],
});

---

Get Segment

GET /wallethero-api/segments/:id

Fetches a single segment by ID.

Auth: Bearer token — workspace member (resolved from the segment row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Segment identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/segments/SEGMENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": { "id": "SEGMENT_ID", "workspace_id": "WORKSPACE_ID", "name": "VIP Members", "filters": [] }
}

SDK

const { data: segment } = await wh.segments.get("SEGMENT_ID");

---

Update Segment

PATCH /wallethero-api/segments/:id

Updates a segment. Any workspace_id in the body is stripped. Supplying filters replaces the existing filter array.

Auth: Bearer token — workspace member (resolved from the segment row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Segment identifier

Request Body

Field	Type	Required	Description
name	string	No	New name
description	string	No	New description
filters	SegmentFilter[]	No	Replacement filter array

Example Request

curl -X PATCH "https://api.wallethero.app/wallethero-api/segments/SEGMENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Super VIP Members" }'

Response (200)

{ "data": { "id": "SEGMENT_ID", "name": "Super VIP Members", "filters": [] } }

SDK

const { data } = await wh.segments.update("SEGMENT_ID", { name: "Super VIP Members" });

---

Delete Segment

DELETE /wallethero-api/segments/:id

Deletes a segment.

Auth: Bearer token — workspace member (resolved from the segment row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Segment identifier

Example Request

curl -X DELETE "https://api.wallethero.app/wallethero-api/segments/SEGMENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{ "message": "Segment deleted" }

SDK

await wh.segments.delete("SEGMENT_ID");

---

Duplicate Segment

POST /wallethero-api/segments/:id/duplicate

Creates a copy of the segment, including its filters.

Auth: Bearer token — workspace member (resolved from the segment row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Segment identifier to copy

Request Body

Field	Type	Required	Description
name	string	No	Name for the new segment

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/segments/SEGMENT_ID/duplicate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "VIP Members (copy)" }'

Response (200)

{ "data": { "id": "44444444-4444-4444-4444-444444444444", "name": "VIP Members (copy)", "filters": [] } }

SDK

const segment = await wh.segments.duplicate("SEGMENT_ID", "VIP Members (copy)");

---

Calculate Segment Size

POST /wallethero-api/segments/:id/calculate

Computes the number of clients matching the segment's filters.

Auth: Bearer token — workspace member (resolved from the segment row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Segment identifier

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/segments/SEGMENT_ID/calculate" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{ "data": { "total": 1542 } }

SDK

const size = await wh.segments.calculateSize("SEGMENT_ID");
console.log(size.total);

---

Count Segment Clients

GET /wallethero-api/segments/:id/client-count

Returns the matching client count — the same result as Calculate Segment Size, via a GET.

Auth: Bearer token — workspace member (resolved from the segment row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Segment identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/segments/SEGMENT_ID/client-count" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{ "data": { "total": 1542 } }

SDK

No SDK method — call the REST endpoint directly, or use segments.calculateSize().

---

Preview Segment Clients

GET /wallethero-api/segments/:id/preview

Returns a sample of the clients in the segment.

Auth: Bearer token — workspace member (resolved from the segment row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Segment identifier

Query Parameters

Parameter	Type	Required	Default	Description
limit	number	No	100	Max clients to return

Example Request

curl "https://api.wallethero.app/wallethero-api/segments/SEGMENT_ID/preview?limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    { "id": "client-1", "first_name": "Jane", "last_name": "Doe", "email": "[email protected]" }
  ]
}

SDK

const clients = await wh.segments.preview("SEGMENT_ID", 50);

---

Get Segment Clients

GET /wallethero-api/segments/:id/clients

Returns the clients in the segment (same evaluation as preview; intended for fetching the full list).

Auth: Bearer token — workspace member (resolved from the segment row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Segment identifier

Query Parameters

Parameter	Type	Required	Default	Description
limit	number	No	100	Max clients to return

Example Request

curl "https://api.wallethero.app/wallethero-api/segments/SEGMENT_ID/clients?limit=500" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    { "id": "client-1", "first_name": "Jane", "last_name": "Doe", "email": "[email protected]" }
  ]
}

SDK

const clients = await wh.segments.getClients("SEGMENT_ID", 500);

---

Get Segment Passes

GET /wallethero-api/segments/:id/passes

Returns the clients in the segment. Functionally identical to Get Segment Clients; kept for backward compatibility.

Auth: Bearer token — workspace member (resolved from the segment row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Segment identifier

Query Parameters

Parameter	Type	Required	Default	Description
limit	number	No	100	Max items to return

Example Request

curl "https://api.wallethero.app/wallethero-api/segments/SEGMENT_ID/passes?limit=100" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{ "data": [ { "id": "client-1", "first_name": "Jane", "email": "[email protected]" } ] }

SDK

// Deprecated — prefer getClients()
const passes = await wh.segments.getPasses("SEGMENT_ID", 100);