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

# Segments

> Describe an audience in JSON: groups, rules and operators.

A segment is a filter saved on a list. Build it in the interface ([Segments](/contacts/segments)) or here, in JSON.

## Create a segment

"VIP customers, or those who opened the back-to-school campaign, and active in the last 60 days":

```bash theme={null}
curl -X POST https://lekalao.example.com/api/v1/lists/$LIST/segments \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Active VIPs",
    "conditions": {
      "operator": "and",
      "rules": [
        {
          "operator": "or",
          "rules": [
            { "type": "tags", "operator": "has_any", "value": ["vip"] },
            { "type": "campaign", "operator": "opened", "value": "0c9e3f5a-6b1d-4d2e-8a7f-1e2d3c4b5a69" }
          ]
        },
        { "type": "engagement", "operator": "active_within_days", "value": 60 }
      ]
    }
  }'
```

The `201` answer carries the segment and `subscribers_count`, how many people it names at that moment. Members are worked out again at every send: a segment is never frozen.

## The shape

* A **group**: `{ "operator": "and" | "or", "rules": [ … ] }`.
* A **rule**: `{ "type", "operator", "value", "key" }`.
* A group may hold rules and groups, **two levels** deep at most.
* **50 rules** in all, at most.

Only subscribers of the list whose status is `subscribed` are counted.

## The rules

### Fields of the record

`type`: `email`, `first_name`, `last_name`.

| `operator`                                             | `value`                |
| ------------------------------------------------------ | ---------------------- |
| `equals`, `not_equals`                                 | Text. Case is ignored. |
| `contains`, `not_contains`, `starts_with`, `ends_with` | Text.                  |
| `is_empty`, `is_not_empty`                             | None.                  |

```json theme={null}
{ "type": "email", "operator": "ends_with", "value": "@mybakery.example" }
```

### Tags

`type`: `tags`.

| `operator` | `value`                     |
| ---------- | --------------------------- |
| `has_any`  | At least one of these tags. |
| `has_all`  | All of these tags.          |
| `has_none` | None of these tags.         |

`value` is an array of tag **names** or **ids** from the list. An unknown tag is refused.

### Language

`type`: `language`. `operator`: `equals` or `not_equals`. `value`: a code such as `fr` or `pt-BR`.

### Attributes

`type`: `attribute`, with `key` the name of the attribute (letters, digits, `_`, `.`, `-`).

| `operator`                         | `value`               |
| ---------------------------------- | --------------------- |
| `equals`, `not_equals`, `contains` | Text.                 |
| `greater_than`, `less_than`        | A number.             |
| `date_before`, `date_after`        | A date, `YYYY-MM-DD`. |
| `is_set`, `is_not_set`             | None.                 |

```json theme={null}
{
    "type": "attribute",
    "key": "points",
    "operator": "greater_than",
    "value": 100
}
```

### Subscription date

`type`: `subscribed_at`.

| `operator`                               | `value`               |
| ---------------------------------------- | --------------------- |
| `before`, `after`                        | A date, `YYYY-MM-DD`. |
| `within_last_days`, `more_than_days_ago` | A number of days.     |

### Activity

| `type`            | `operator`                                                                     | `value`                       |
| ----------------- | ------------------------------------------------------------------------------ | ----------------------------- |
| `campaign`        | `received`, `not_received`, `opened`, `not_opened`, `clicked`, `not_clicked`   | The campaign's `id`.          |
| `automation_mail` | the same ones                                                                  | The automation e-mail's `id`. |
| `link`            | `clicked`, `not_clicked`                                                       | The link's `id`.              |
| `engagement`      | `active_within_days` (opened or clicked), `inactive_within_days` (did nothing) | A number of days.             |

### Other lists

`type`: `list`. `operator`: `subscribed_to` or `not_subscribed_to`. `value`: the `id` of **another** list of the team.

```json theme={null}
{ "type": "list", "operator": "not_subscribed_to", "value": "3e7d…" }
```

## Read, change, delete

| Call                       | Effect                                                                            |
| -------------------------- | --------------------------------------------------------------------------------- |
| `GET /lists/{id}/segments` | The segments of the list, without counts.                                         |
| `GET /segments/{id}`       | One segment, with `subscribers_count`.                                            |
| `PUT /segments/{id}`       | Changes `name` and/or `conditions`. The conditions you send replace the old ones. |
| `DELETE /segments/{id}`    | Deletes the segment. Campaigns already sent keep their statistics.                |

In the answers, tags come back as names and the other references as ids, just as you sent them.

## Errors

An invalid rule answers `422` with the exact path:

```json theme={null}
{
    "message": "There is no tag \"vipp\" on this list.",
    "errors": {
        "conditions.rules.0.rules.0.value": [
            "There is no tag \"vipp\" on this list."
        ]
    }
}
```