# 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 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tiledesk.com/apis/rest-api/segments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.