# Segments

## List segments

`GET /v1/c/{slug}/segments` · Scopes: `contacts:read` · `campaigns:write`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |

### Request example

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/segments" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Response 200

```json
{
  "segments": [
    {
      "id": "01a1a0b0-1c2d-7e3f-8a9b-0c1d2e3f4a5b",
      "name": "Clientes do plano anual",
      "conditions": [
        {
          "field": "field.plano",
          "op": "eq",
          "value": "anual"
        }
      ],
      "count": 312,
      "updatedAt": "2026-10-23T13:02:11.000Z"
    }
  ]
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Create a segment

`POST /v1/c/{slug}/segments` · Scopes: `contacts:write`

A group of contacts by conditions: tag, source, last outcome, days since the last conversation or since created, marketing consent, name, WhatsApp and any field (`field.<key>`).

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |

### Request body

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | up to 120 characters |
| `conditions` | list of object | yes | up to 20 |
| `conditions[].field` | string | yes | up to 80 characters |
| `conditions[].op` | one of `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | yes |  |
| `conditions[].value` | string · number · boolean · one of `null` | no |  |

### Request example

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/segments" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes do plano anual",
  "conditions": [
    {
      "field": "field.plano",
      "op": "eq",
      "value": "anual"
    }
  ]
}'
```

### Response 201

```json
{
  "segment": {
    "id": "01a1a0b0-1c2d-7e3f-8a9b-0c1d2e3f4a5b"
  }
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Edit a segment

`PUT /v1/c/{slug}/segments/{id}` · Scopes: `contacts:write`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |
| `id` | The record's id. |

### Request body

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | up to 120 characters |
| `conditions` | list of object | yes | up to 20 |
| `conditions[].field` | string | yes | up to 80 characters |
| `conditions[].op` | one of `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | yes |  |
| `conditions[].value` | string · number · boolean · one of `null` | no |  |

### Request example

```bash
curl -X PUT "https://api.donetalk.com/v1/c/demo/segments/:id" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes do plano anual",
  "conditions": [
    {
      "field": "field.plano",
      "op": "eq",
      "value": "anual"
    }
  ]
}'
```

### Response 200

```json
{
  "ok": true
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Delete a segment

`DELETE /v1/c/{slug}/segments/{id}` · Scopes: `contacts:write`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |
| `id` | The record's id. |

### Request example

```bash
curl -X DELETE "https://api.donetalk.com/v1/c/demo/segments/:id" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Response 200

```json
{
  "ok": true
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Count who matches

`POST /v1/c/{slug}/segments/count` · Scopes: `contacts:read` · `campaigns:write`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |

### Request body

| Field | Type | Required | Notes |
|---|---|---|---|
| `conditions` | list of object | yes | up to 20 |
| `conditions[].field` | string | yes | up to 80 characters |
| `conditions[].op` | one of `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | yes |  |
| `conditions[].value` | string · number · boolean · one of `null` | no |  |

### Request example

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/segments/count" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conditions": [
    {
      "field": "tag",
      "op": "has",
      "value": "01a12150-3610-7c00-b680-188c2b4c7313"
    }
  ]
}'
```

### Response 200

```json
{
  "count": 312
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Search contacts by conditions

`POST /v1/c/{slug}/contacts/search` · Scopes: `contacts:read`

### Path parameters

| Field | Notes |
|---|---|
| `slug` | The company's identifier in DoneTalk (the key's own). |

### Request body

| Field | Type | Required | Notes |
|---|---|---|---|
| `segmentId` | string (uuid) | no |  |
| `conditions` | list of object | no | up to 20; default `[]` |
| `conditions[].field` | string | yes | up to 80 characters |
| `conditions[].op` | one of `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | yes |  |
| `conditions[].value` | string · number · boolean · one of `null` | no |  |
| `q` | string | no | up to 100 characters |
| `limit` | integer | no | up to 200; at least 1; default `50` |
| `offset` | integer | no | up to 1000000; default `0` |

### Request example

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/contacts/search" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conditions": [
    {
      "field": "marketing",
      "op": "eq",
      "value": "opted_in"
    }
  ],
  "limit": 50
}'
```

### Response 200

```json
{
  "total": 312,
  "marketingAllowed": 298,
  "contacts": [
    {
      "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
      "displayName": "Ana Souza",
      "source": "api",
      "fields": {
        "cpf": "529.982.247-25",
        "plano": "anual"
      },
      "isBlocked": false,
      "address": "5548999990001",
      "marketing": "opted_in",
      "lastOutcome": "converted",
      "tags": [
        {
          "id": "01a12150-3610-7c00-b680-188c2b4c7313",
          "name": {
            "pt-BR": "VIP",
            "en": "VIP",
            "es": "VIP"
          },
          "color": "#92400e"
        }
      ],
      "lastActivityAt": "2026-10-22T18:40:02.000Z",
      "createdAt": "2026-09-23T22:19:30.396Z"
    }
  ]
}
```

### Possible errors

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`