Segments

Contact segments — reusable audience definitions built from conditions (tags, channel, status, custom fields, activity) or a static list of members. Used when composing broadcasts and as automation triggers. Audience size can be previewed without saving a segment via /segments/estimate.

Condition types

Supported condition types: tag, channel, status, date, field, activity, custom; conditions are combined with group_logic (and or or).

Pagination and search

Listing (GET /segments) supports pagination (page, perPage — default 50) and search (search).

Endpoints

Method	Path	Summary
GET	`/v1/segments` List segments (paginated, searchable)	List segments (paginated, searchable)
POST	`/v1/segments` Create a segment	Create a segment
PATCH	`/v1/segments/{segment}` Update a segment	Update a segment
POST	`/v1/segments/{segment}` Update a segment (POST alias of PATCH for clients without PATCH)	Update a segment (POST alias of PATCH for clients without PATCH)
DELETE	`/v1/segments/{segment}` Delete a segment	Delete a segment
POST	`/v1/segments/estimate` Estimate audience size from conditions (without saving)	Estimate audience size from conditions (without saving)

Examples

Create a dynamic segment

Request

bash

curl -X POST https://api.aisar.app/v1/segments \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New leads",
    "description": "Contacts with recent inbound activity",
    "conditions": [
      { "type": "tag", "operator": "has_any", "value": [1, 2], "group": 0 },
      { "type": "channel", "operator": "in", "value": [7], "group": 0 }
    ],
    "group_logic": "and"
  }'

Response

json

{
  "data": {
    "id": "45",
    "name": "New leads",
    "slug": "new-leads",
    "type": "dynamic",
    "description": "Contacts with recent inbound activity",
    "conditions": [
      { "group": 0, "type": "tag", "operator": "has_any", "value": [1, 2], "field_name": null },
      { "group": 0, "type": "channel", "operator": "in", "value": [7], "field_name": null }
    ],
    "conditions_summary": "Tag in (Lead, Hot) AND channel is WhatsApp",
    "estimated_count": 120,
    "contacts_count": null,
    "members": null,
    "created_at": "2026-03-15T10:00:00.000000Z",
    "updated_at": "2026-03-15T10:00:00.000000Z"
  }
}

Estimate audience without saving

Request

bash

curl -X POST https://api.aisar.app/v1/segments/estimate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "type": "tag", "operator": "has_any", "value": [1, 2], "group": 0 }
    ]
  }'

Response

json

{
  "data": {
    "estimated_count": 120
  }
}

Update a segment

Request

bash

curl -X PATCH https://api.aisar.app/v1/segments/46 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hot leads",
    "description": "High-intent contacts from priority channels",
    "conditions": [
      { "type": "tag", "operator": "has_any", "value": [2], "group": 0 },
      { "type": "status", "operator": "is", "value": "open", "group": 0 }
    ],
    "group_logic": "and"
  }'

Response

json

{
  "data": {
    "id": "46",
    "name": "Hot leads",
    "slug": "hot-leads",
    "type": "dynamic",
    "description": "High-intent contacts from priority channels",
    "conditions": [
      { "group": 0, "type": "tag", "operator": "has_any", "value": [2], "field_name": null },
      { "group": 0, "type": "status", "operator": "is", "value": "open", "field_name": null }
    ],
    "conditions_summary": "Tag in (Hot) AND status is open",
    "estimated_count": 64,
    "contacts_count": null,
    "members": null,
    "created_at": "2026-03-15T10:00:00.000000Z",
    "updated_at": "2026-03-16T09:30:00.000000Z"
  }
}