# Segments

A Segment identifies a group/set of Wallet passes that contains a tag or combination of tags, using boolean `and`, `or`, and `not` operators. Use segments to group and target passes for subsequent updates.


## Create segment {#createsegment}

Create a segment for a project.

[Jump to examples ↓](#createsegment-examples)

### `POST /segments/{projectId}`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)
- [oauth2Token]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-oauth2Token): wseg

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `projectId` | `string` | Required | The ID of the project. |

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | The particular API revision you want to use. In general, this is `1.2`. Possible values: `1.2` |

**Request body**

Contains `and`, `or`, or `not` operators for tags that identify your segment.

**Content-Type:** `application/json`

- **`criteria`** `object` <[Segment selector]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#segmentselector)>

  Boolean tag selectors specifying a group of passes. You can nest `AND` and `OR` selectors.

- **`display_name`** `string`

  The name of the segment.

**Responses**

**`200`** A response returns a segment ID that you can use to reference the segment in future operations.

Response body:

**Content-Type:** `application/json`

- **`ok`** `boolean`

  If true, the operation completed successfully.

- **`operationId`** `string`

  An identifier for the operation. Use this value to reference
the operation for troubleshooting purposes.


  Format: `uuid`

- **`segmentId`** `string`

  An identifier for the segment. Use this value to reference the segment in other operations.

  Format: `uuid`

**Examples**

*Example request*

```http
POST /v1/segments/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

{
   "criteria": {
      "and": [
         {
            "tag": "TZ_PST"
         },
         {
            "not": {
               "tag": "TZ_ET"
            }
         }
      ]
   },
   "display_name": "timezone"
}

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "ok": true,
   "segmentId": "b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
   "operationId": "dd2f1d32-aca9-4463-91c2-a3420bbcd489"
}

```

---

## Delete segment {#deletesegment}

Delete a segment by ID. This operation just deletes the segment criteria. The passes previously selected by this criteria are unchanged.

[Jump to examples ↓](#deletesegment-examples)

### `DELETE /segments/{projectId}/{segmentId}`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)
- [oauth2Token]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-oauth2Token): wseg

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `projectId` | `string` | Required | The ID of the project. |
| `segmentId` | `string` | Required | The ID of the segment. |

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | The particular API revision you want to use. In general, this is `1.2`. Possible values: `1.2` |

**Responses**

**`204`** A successful delete request returns no content.

**Examples**

*Example request*

```http
DELETE /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

```

*Response*

```http
HTTP/1.1 204 No Content

```

---

## List segments {#listsegments}

List meta information for all segments for a project.

[Jump to examples ↓](#listsegments-examples)

### `GET /segments/{projectId}`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)
- [oauth2Token]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-oauth2Token): wseg

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `projectId` | `string` | Required | The ID of the project. |

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | The particular API revision you want to use. In general, this is `1.2`. Possible values: `1.2` |

**Responses**

**`200`** A response returns a list of segments for a project.

Response body:

**Content-Type:** `application/json`

- **`segments`** `array[object]`
**Examples**

*Example request*

```http
GET /v1/segments/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2              

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "segments": [
      {
         "creation_date": "2017-03-17T05:45:21Z",
         "display_name": "timezone",
         "id": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
         "modification_date": "2017-03-17T05:45:21Z"
      },
      {
         "creation_date": "2017-03-17T23:29:06Z",
         "display_name": "my testing segment",
         "id": "5eae7f52-3dc7-4a67-8a89-9b357815e7f7",
         "modification_date": "2017-03-17T23:29:06Z"
      }
   ]
}

```

---

## Look up segment {#getsegment}

Returns the selector criteria for a segment.

[Jump to examples ↓](#getsegment-examples)

### `GET /segments/{projectId}/{segmentId}`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)
- [oauth2Token]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-oauth2Token): wseg

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `projectId` | `string` | Required | The ID of the project. |
| `segmentId` | `string` | Required | The ID of the segment. |

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | The particular API revision you want to use. In general, this is `1.2`. Possible values: `1.2` |

**Responses**

**`200`** A successful request returns the selection criteria for the segment.

Response body:

**Content-Type:** `application/json`

- **`criteria`** `object` <[Segment selector]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#segmentselector)>

  Boolean tag selectors specifying a group of passes. You can nest `AND` and `OR` selectors.

- **`display_name`** `string`

  The name of the segment.

**Examples**

*Example request*

```http
GET /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2             

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "criteria": {
      "and": [
         {
            "tag": "TZ_PST"
         },
         {
            "not": {
               "tag": "TZ_ET"
            }
         }
      ]
   },
   "display_name": "timezone"
}

```

---

## Update passes by segment {#updatepassesbysegment}

Update passes by segment ID and template ID.

[Jump to examples ↓](#updatepassesbysegment-examples)

### `PUT /segments/{projectId}/{segmentId}/passes`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)
- [oauth2Token]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-oauth2Token): wpas

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `projectId` | `string` | Required | The ID of the project. |
| `segmentId` | `string` | Required | The ID of the segment. |

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `templateId` | `string` |  | The ID for the template. Required since pass updates for segments are done at the template level. |

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | The particular API revision you want to use. In general, this is `1.2`. Possible values: `1.2` |

**Request body**

Provide only the fields you want to update.

**Content-Type:** `application/json`

- **`fields`** `object`
**Responses**

**`200`** A response returns one or more [`ticketId`](/docs/developer/rest-api/wallet/operations/tickets/) values, each referencing the pass update operation.

Response body:

**Content-Type:** `application/json`

- **`ticketId`** `integer`

  A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.

**Examples**

*Example request*

```http
PUT /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a/passes?templateId=6789 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

{
    "fields":{
        "secondary1":{
            "value":"Mega Offer"
        },
        "primary1":{
            "value":"$20 Off"
        }
    }
}

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "ticketId": 123
}

```

---

## Update segment {#updatesegment}

Update selection criteria or the display name for a segment.

[Jump to examples ↓](#updatesegment-examples)

### `PUT /segments/{projectId}/{segmentId}`

**Security:**

- [httpBasic]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-httpBasic)
- [oauth2Token]({{< ref "/developer/rest-api/wallet/introduction/" >}}#security-oauth2Token): wseg

**Path parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `projectId` | `string` | Required | The ID of the project. |
| `segmentId` | `string` | Required | The ID of the segment. |

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Api-Revision` | `string` | Required | The particular API revision you want to use. In general, this is `1.2`. Possible values: `1.2` |

**Request body**

**Content-Type:** `application/json`

- **`criteria`** `object` <[Segment selector]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#segmentselector)>

  Boolean tag selectors specifying a group of passes. You can nest `AND` and `OR` selectors.

- **`display_name`** `string`

  The name of the segment.

**Responses**

**`200`** A response returns a segment ID that you can use to reference the segment in future operations.

Response body:

**Content-Type:** `application/json`

- **`ok`** `boolean`

  If true, the operation completed successfully.

- **`operationId`** `string`

  An identifier for the operation. Use this ID to reference the operation for troubleshooting purposes.

  Format: `uuid`

- **`segmentId`** `string`

  An identifier for the segment that you can use to reference the segment in other operations.

  Format: `uuid`

**Examples**

*Example request*

```http
PUT /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

{
   "criteria": {
      "and": [
         {
            "tag": "TZ_PST"
         },
         {
            "not": {
               "tag": "TZ_ET"
            }
         }
      ]
   },
   "display_name": "timezone_info"
}          

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
 "ok": true,
 "segmentId": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
 "operationId": "f573b3c5-b0ee-4461-a179-2e78aab20400"
}

```

---