> For the complete documentation index, see [llms.txt](https://developer.tiledesk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.tiledesk.com/apis/rest-api/segments.md).

# Segments

You can use the API to get or set segment information. A segment is a collection of contacts, defined by a specific set of attributes, used to filter them in a marketing campaign. User segmentation is the process of separating leads into distinct groups, or segments, based on shared characteristics. A company might segment leads based on language preferences, product version, geographical region.

## The Segment Model

| Key         | Type   | Description                                                       |
| ----------- | ------ | ----------------------------------------------------------------- |
| id          | String | The unique identifier for the segment which is given by Tiledesk. |
| name        | String | The segment name                                                  |
| match       | String | all or any                                                        |
| createdAt   | String | The time (ISO-8601 date string) when the segment was created.     |
| filters     | Array  |                                                                   |
| createdBy   | String | The unique identifier of the row creator                          |
| id\_project | String | The unique identifier of the project                              |

## Get all segments

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/segments`

Example

```
curl -v -X GET -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/segments
```

## Get a segment by id

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/segments/:id`

Fetches a segment by his or her segment ID

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| id          | string | the segment identifier                                                                   |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |
| Content-Type  | string | use "application/json" value                                |

Example

```
curl -v -X GET -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/segments/5c81593adf767b0017d1aa66
```

## Create a new segment

<mark style="color:green;">`POST`</mark> `https://api.tiledesk.com/v3/:project_id/segments`

Allows to add more segments.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |
| Content-Type  | string | use "application/json" value                                |

#### Request Body

| Name    | Type   | Description                        |
| ------- | ------ | ---------------------------------- |
| name    | string | The segment name                   |
| match   | string | The segment match type. All or Any |
| filters | array  | The segment filters                |

Example:

```
curl -v -X POST -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  -d '{ "name":"segment1", "filters": [{"field":"field1","operator":"=","value":"value1"}]}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/segments
```

## Update a segment by id

<mark style="color:orange;">`PUT`</mark> `https://api.tiledesk.com/v3/:project_id/segments/:id`

Allows to update a segment.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The id is the segment indentifier.                                                       |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |
| Content-Type  | string | use "application/json" value                                |

#### Request Body

| Name    | Type   | Description                        |
| ------- | ------ | ---------------------------------- |
| name    | string | The segment name                   |
| match   | string | The segment match type. All or Any |
| filters | array  | The segment filters                |

## Delete a segment by id

<mark style="color:red;">`DELETE`</mark> `https://api.tiledesk.com/v3/:project_id/segments/:id`

Allows to delete a segment.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The id is the segment indentifier.                                                       |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |