# Passes

A pass is essentially a populated, personalized template intended for a single platform — Apple Wallet or Google Wallet. Passes manifest as links; you distribute the pass link to users, and they tap or click the link to install the pass.

If you want to distribute passes to both Apple and Google users, you may want to use Adaptive links instead. While a pass is intended for a single platform, so you have to distribute separate pass links to independent Apple and Google audiences, an adaptive link is a single pass link that detects the user's platform and installs the correct pass. Adaptive links can save you the trouble of maintaining separate passes and distribution lists for your customers.


## Add locations to pass {#addlocationstopass}

Add the locations to the specified pass.

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

### `POST /pass/{passId}/locations`

**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 |
|------|------|----------|-------------|
| `passId` | `string` | Required | The pass you want to add locations to. |

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

Set locations for the pass.

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

- **`locations`** `array` <[Location object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#locationobject)>
**Responses**

**`200`** Returns `passLocationId` for each location on the pass. Use this value to identify locations in other location-based operations.

Response body:

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

Type: `array`

**Examples**

*Example request*

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

{
  "locations": [
    {
      "longitude": "-122.374",
      "latitude": "37.618",
      "relevantText": "Hello loc0",
      "streetAddress1": "address line #1",
      "streetAddress2": "address line #2",
      "city": "San Francisco",
      "region": "CA",
      "regionCode": "94404",
      "country": "US"
    },
    { "...": "..." }
  ]
}

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json

[
   {
      "passLocationId": 65,
      "value": {
         "region": "CA",
         "regionCode": "94404",
         "relevantText": "Hello loc0!",
         "streetAddress1": "add11",
         "streetAddress2": "add22",
         "longitude": "-122.3742",
         "latitude": "37.618",
         "city": "FC"
      }
   },
   {
      "passLocationId": 66,
      "value": {
         "region": "CA",
         "regionCode": "94404",
         "relevantText": "Hello loc1!",
         "streetAddress1": "add12",
         "streetAddress2": "add23",
         "longitude": "-123.374",
         "latitude": "38.618",
         "city": "FC"
      }
   }
]

```

---

## Create pass {#createpass}

Create a pass from the specified template.

You can optionally assign an external ID to the pass or generate the pass from templates with external IDs. See the appropriate endpoints to assign or use external IDs.

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

### `POST /pass/{id}`

**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 |
|------|------|----------|-------------|
| `id` | `string` | Required | The `id` of the template you want to create your pass from. |

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

Create a pass; pass composition varies by vendor.

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

**One of:**

- [Apple Wallet pass request]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassapplewalletrequest)

  A pass for Apple Wallet.

- [Google Wallet pass request]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassandroidpayrequest)

  A pass for Google Wallet. Unlike templates, in which the `fieldsModel` contains fields nested inside `module` objects, fields are collapsed in pass requests and responses. The `fieldType` corresponds to the template field module that the field belongs to.

Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.



**Responses**

**`200`** A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.

Response body:

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

**One of:**

- [Apple Wallet pass response]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassapplewalletresponse)

  A pass response includes both identifiers and the content of all fields on a pass.

- [Google Wallet pass response]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassandroidpayresponse)

  A pass response for Google Wallet.  A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

Unlike templates, in which the `fieldsModel` contains fields nested inside `module` objects, fields are collapsed in pass requests and responses. The `fieldType` corresponds to the template field module (an object) that the field belongs to.


Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.



**Examples**

*Example request*

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

{
    "headers": {
        "expirationDate": {
           "value": "2014-08-20T09:41-08:00"
         },
         "barcodeAltText": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         },
         "barcode_value": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         }
    },
    "fields": {
      "Coupon": {
         "changeMessage": "Enjoy %@ off your next order!",
         "value": "20%",
         "label": "Coupon"
      },
      "SiteAddress": {
         "changeMessage": "Check out things we think you would like at %@",
         "value": "https://www.example.com/new?custnumb=123456",
         "label": "personal deals"
      },
      "InStore": {
         "changeMessage": "Or visit your nearest store at %@",
         "value": "1234 Fake St.",
         "label": "nearestStore"
      },
      "thumbnail_image": {
          "value": "https:\/\/example.com\/assets\/favicon.png"
      }
    },
    "beacons":[
        {
           "uuid": "55502220-A123-A88A-F321-555A444B333C",
           "relevantText": "You are near the Ship",
           "major": 2,
           "minor": 346
        }
    ],
    "locations":[
        {
           "longitude": -122.374,
           "latitude": 37.618,
           "relevantText": "Hello loc0",
           "streetAddress1": "address line #1",
           "streetAddress2": "address line #2",
           "city": "San Francisco",
           "region": "CA",
           "regionCode": "94404",
           "country": "US"
        }
    ],
    "publicUrl": {
        "type": "single"
    }
}

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 12345,
    "templateId": 123,
    "createdAt": "2012-11-01 12:37:07.0",
    "url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/888\/download",
    "publicUrl": {
          "path": "https:\/\/wallet-api.urbanairship.com\/v1\/download\/pass\/9c9c9c7d-c6b6-9c9c-9d2b-9c9c9c54c89c",
          "used": false,
          "type": "Single",
          "installs": 0
    },
    "passFields": {
        "gate": {
            "changeMessage": "Your gate has changed to %@",
            "fieldType": "HEADER",
            "value": "A56",
            "label": "my value",
            "required": false
        },
        "logo_text": {
            "changeMessage": null,
            "fieldType": "TOP_LEVEL",
            "value": "Test Value",
            "label": "",
            "required": false
        },
        "boarding_time": {
            "changeMessage": "Be at your new gate by %@",
            "fieldType": "PRIMARY",
            "value": "08:45",
            "label": "",
            "required": false
        },
        "thumbnail_image": {
            "formatType": "String",
            "changeMessage": null,
            "fieldType": "image",
            "value": "https:\/\/example.com\/passtools...0bb4_favicon.png",
            "label": "",
            "required": false,
            "hideEmpty": false
        }
    },
    "beacons":[
        {
            "uuid": "55502220-A123-A88A-F321-555A444B333C",
            "relevantText": "You are near the Ship",
            "major": 2,
            "minor": 346
        }
    ],
    "locations":[
        {
            "relevantText":"Hello loc0",
            "latitude":37.618,
            "id":30473906,
            "longitude":-122.374
        }
    ]
}

```

---

## Delete locations from pass {#deletelocationfrompass}

Delete the specified location from the specified pass.

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

### `DELETE /pass/{passId}/location/{passLocationId}`

**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 |
|------|------|----------|-------------|
| `passId` | `string` | Required | The `id` of the pass you want to remove locations from. |
| `passLocationId` | `string` | Required | The location you want to remove from the pass. |

**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`** Success.

Response body:

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

- **`locations`** `array` <[Location object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#locationobject)>
**Examples**

*Example request*

```http
DELETE /v1/pass/123/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

```

---

## Delete pass {#deletepass}

Delete the specified pass.

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

### `DELETE /pass/{id}`

{{< note >}}
The Delete function does not remove passes from the end-user's device, but removes from our system. Deleted passes no longer count towards billing. See [Editing Wallet Pass Expiration](/docs/guides/wallet/user-guide/updating-passes/edit-expiration/) to deactivate the pass on the end-user's device.
{{< /note >}}

**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 |
|------|------|----------|-------------|
| `id` | `string` | Required | The `id` of the pass you want to delete. |

**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`** The pass was successfully deleted.

Response body:

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

- **`passId`** `integer`

  The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

  Read only: true

- **`status`** `string`

  Indicates that the pass was deleted.

  Possible values: `deleted`

**Examples**

*Example request*

```http
DELETE /v1/pass/123 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

{
    "status": "deleted",
    "passId": "123"
}

```

---

## Generates a pass {#createdynamiclink}

Generates a pass with an optional expiration date and serial number. You can also assign an external ID to passes generated from this endpoint.

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

### `POST /pass/{id}/dynamic`

**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 |
|------|------|----------|-------------|
| `id` | `string` | Required | The `templateId` of the template you want to create the pass from.  |

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `expiry` | `string` |  | The expiration date for the pass. |

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

Create a pass; pass composition varies by vendor.

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

**One of:**

- [Apple Wallet pass request]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassapplewalletrequest)

  A pass for Apple Wallet.

- [Google Wallet pass request]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassandroidpayrequest)

  A pass for Google Wallet. Unlike templates, in which the `fieldsModel` contains fields nested inside `module` objects, fields are collapsed in pass requests and responses. The `fieldType` corresponds to the template field module that the field belongs to.

Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.



**Responses**

**`200`** A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.

Response body:

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

**One of:**

- [Apple Wallet pass response]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassapplewalletresponse)

  A pass response includes both identifiers and the content of all fields on a pass.

- [Google Wallet pass response]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassandroidpayresponse)

  A pass response for Google Wallet.  A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

Unlike templates, in which the `fieldsModel` contains fields nested inside `module` objects, fields are collapsed in pass requests and responses. The `fieldType` corresponds to the template field module (an object) that the field belongs to.


Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.



**Examples**

*Example request*

```http
POST /v1/pass/12345/dynamic&expiry=2017-05-18 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
   "headers": {
      "expirationDate": {
         "value": "2014-08-20T09:41-08:00"
      },
         "barcodeAltText": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         },
         "barcode_value": {
            "changeMessage" : null,
            "value": "abc1234567890",
            "label": ""
         }
   },
   "fields": {
      "Coupon": {
         "changeMessage": "Enjoy %@ off your next order!",
         "value": "20%",
         "label": "Coupon"
      },
         "SiteAddress": {
            "changeMessage": "Check out things we think you would like at %@",
            "value": "https://www.example.com/new?custnumb=123456",
            "label": "personal deals"
         },
         "InStore": {
            "changeMessage": "Or visit your nearest store at %@",
            "value": "1234 Fake St.",
            "label": "nearestStore"
         },
         "thumbnail_image": {
            "value": "https:\/\/example.com\/assets\/favicon.png"
         }
   },
      "beacons":[
         {
            "uuid": "55502220-A123-A88A-F321-555A444B333C",
            "relevantText": "You are near the Ship",
            "major": 2,
            "minor": 346
         }
   ],
   "publicURL": {
      "type": "single"
   },
   "externalId": "abcd"
}

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
   "url": "https://wallet-api.urbanairship.com/v1/pass/dynamic/44e128a5-ac7a-4c9a-be4c-224b6bf81b20"
}

```

---

## Get pass {#getpass}

Get the specified pass. This endpoint will return the external ID of a pass, but only if there is one associated with it.

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

### `GET /pass/{id}`

**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 |
|------|------|----------|-------------|
| `id` | `string` | Required | The `id` of the pass you want to look up. |

**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`** Returns a complete pass, including headers and fields on the pass and metadata about the pass.

Response body:

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

**One of:**

- [Apple Wallet pass response]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassapplewalletresponse)

  A pass response includes both identifiers and the content of all fields on a pass.

- [Google Wallet pass response]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassandroidpayresponse)

  A pass response for Google Wallet.  A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

Unlike templates, in which the `fieldsModel` contains fields nested inside `module` objects, fields are collapsed in pass requests and responses. The `fieldType` corresponds to the template field module (an object) that the field belongs to.


Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.



**Examples**

*Example request*

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

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
   "tags":[

   ],
   "headers": {
      "barcodeAltText": {
         "formatType": "String",
         "changeMessage": null,
         "fieldType": "barcode",
         "value": "123456789",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "logo_color": {
         "formatType": "String",
         "changeMessage": null,
         "fieldType": "topLevel",
         "value": "rgb(24,86,148)",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "icon_image": {
         "formatType": "String",
         "changeMessage": null,
         "fieldType": "topLevel",
         "value": "https:\/\/example.com\/passtools_prod\/1\/images\/default-pass-icon.png",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "barcode_value": {
         "formatType": "String",
         "changeMessage": null,
         "fieldType": "barcode",
         "value": "123456789",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "logo_text": {
         "formatType": "String",
         "changeMessage": "%@",
         "fieldType": "topLevel",
         "value": "Logo",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "barcode_encoding": {
         "formatType": "String",
         "changeMessage": null,
         "fieldType": "barcode",
         "value": "iso-8859-1",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "suppress_strip_shine": {
         "formatType": "String",
         "changeMessage": null,
         "fieldType": "topLevel",
         "value": "true",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "barcode_label": {
         "formatType": "String",
         "changeMessage": "%@",
         "fieldType": "barcode",
         "value": "Member ID",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "barcode_type": {
         "formatType": "String",
         "changeMessage": null,
         "fieldType": "barcode",
         "value": "PKBarcodeFormatPDF417",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "foreground_color": {
         "formatType": "String",
         "changeMessage": null,
         "fieldType": "topLevel",
         "value": "rgb(255,255,255)",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "background_color": {
         "formatType": "String",
         "changeMessage": null,
         "fieldType": "topLevel",
         "value": "rgb(0,147,201)",
         "label": "",
         "required": false,
         "hideEmpty": false
      },
      "relevantDate": {
         "changeMessage": "The new date is %@",
         "label": "relevantDate",
         "hideEmpty": false,
         "formatType": "String",
         "value": "2015-12-31T23:00:00-08:00",
         "fieldType": "topLevel",
         "required": false
      }
   },
   "id": "1234",
   "templateId": "12345",
   "updatedAt": "2013-06-19T01:06:23.000Z",
   "createdAt": "2013-06-19T01:06:17.000Z",
   "serialNumber": "14f94898-2f5e-46f5-925c-7e29fa9a0508",
   "installedAt": "2013-06-19T01:06:17.000Z",
   "url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/1249\/download",
   "status": "installed",
   "fields": {
      "Merchant Website": {
         "formatType": "URL",
         "changeMessage": "Get event details at %@",
         "order": 2,
         "fieldType": "back",
         "value": "http:\/\/www.example.com",
         "label": "Merchant Website",
         "required": false,
         "hideEmpty": false
      },
      "More Details": {
         "formatType": "String",
         "changeMessage": "%@",
         "order": 1,
         "fieldType": "back",
         "value": "More details about how to use this event ticket. Additional terms and support information.",
         "label": "More Details",
         "required": false,
         "hideEmpty": false
      },
      "Seat": {
         "textAlignment": "textAlignmentNatural",
         "changeMessage": "You are now seated at %@",
         "numberStyle": "PKNumberStyleDecimal",
         "label": "Seat",
         "hideEmpty": false,
         "formatType": "Number",
         "value": 1.0,
         "fieldType": "auxiliary",
         "required": false,
         "order": 3
      },
      "Row": {
         "textAlignment": "textAlignmentNatural",
         "changeMessage": "You are now seated in row %@",
         "numberStyle": "PKNumberStyleDecimal",
         "label": "Row",
         "hideEmpty": false,
         "formatType": "Number",
         "value": 1.0,
         "fieldType": "auxiliary",
         "required": false,
         "order": 2
      },
      "Section": {
         "textAlignment": "textAlignmentLeft",
         "changeMessage": "You are now seated in section %@",
         "label": "Section",
         "hideEmpty": false,
         "formatType": "String",
         "value": "1",
         "fieldType": "auxiliary",
         "required": true,
         "order": 1
      }
   }
}

```

---

## List passes {#getpasses}

List passes that your user account is responsible for. You can provide an optional template parameter, returning passes created from a particular template.

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

### `GET /pass`

**Security:**

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

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `templateId` | `string` |  | The `id` of the template you want to look up. |
| `status` | `string` |  | Find only passes matching the installation status.  * `installed` — passes currently installed. * `uninstalled` — passes that have been uninstalled. * `been_installed` — passes that have been either installed or uninstalled. * `not_been_installed` — passes that have never been installed.  Possible values: `installed`, `uninstalled`, `been_installed`, `not_been_installed` |
| `pageSize` | `integer` |  | The number of passes per page. Defaults to 10. Default: `10` |
| `page` | `integer` |  | The page of results you want to retrieve, starting at 1. Default: `1` |
| `order` | `string` |  | The order you want passes returned in, defaulting to `id`. Possible values: `id`, `createdAt`, `updatedAt` Default: `id` |
| `direction` | `string` |  | Determines whether to return values in ascending or descending order. Defaults to `DESC`. Possible values: `ASC`, `DESC` Default: `DESC` |

**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 a paged list of passes created from a particular template.

Response body:

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

- **`count`** `integer`

  The total number of passes associated with the template.

- **`pagination`** `object` <[Pagination object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#paginationobject)>

  Contains information about pagination, according to your query parameters.

- **`passes`** `array[object]`

  The metadata for passes associated with the template. Each object in the array represents a pass.

**Examples**

*Example request*

```http
GET /v1/pass?templateId=12345&status=uninstalled 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

{
          "passes": [{
              "id": 61,
              "templateId": 12345,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
              "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
              "createdAt": "2023-04-19T06:17:01.000Z",
              "updatedAt": "2023-04-19T06:17:01.000Z",
              "status": "uninstalled",
              "installedAt": "2023-04-19T06:17:02.000Z",
              "platform": "android"
            },
            {
              "id": 60,
              "templateId": 12345,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/60/download",
              "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e201",
              "createdAt": "2023-04-05T17:55:23.000Z",
              "updatedAt": "2023-04-05T17:55:23.000Z",
              "status": "installed",
              "installedAt": "2023-04-05T17:55:23.000Z",
              "platform": "android"
            }
          ],
          "pagination": {
            "order": "id",
            "direction": "desc",
            "page": 1,
            "start": 0,
            "pageSize": 2
          }
}

```

---

## List passes for a tag {#listpassesfortag}

List the passes associated with the specified tag.

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

### `GET /tag/{tag}/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 |
|------|------|----------|-------------|
| `tag` | `string` | Required | A tag `id` or `name`. The request returns a paginated list of passes associated with the specified tag. |

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | `string` |  | Find only passes matching the installation status.  * `installed` — passes currently installed. * `uninstalled` — passes that have been uninstalled. * `been_installed` — passes that have been either installed or uninstalled. * `not_been_installed` — passes that have never been installed.  Possible values: `installed`, `uninstalled`, `been_installed`, `not_been_installed` |
| `pageSize` | `integer` |  | The number of passes per page. Defaults to 10. Default: `10` |
| `page` | `integer` |  | The page of results you want to retrieve, starting at 1. Default: `1` |
| `order` | `string` |  | The order you want tags returned in, defaulting to `id`. Possible values: `id`, `createdAt`, `updatedAt` Default: `id` |
| `direction` | `string` |  | Determines whether to return values in ascending or descending order. Defaults to `DESC`. Possible values: `ASC`, `DESC` Default: `DESC` |

**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 response returns a paginated array of passes.

Response body:

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

- **`count`** `integer`

  The total number of results.

- **`pagination`** `object` <[Pagination object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#paginationobject)>

  Contains information about pagination, according to your query parameters.

- **`passes`** `object`

  Meta information about passes.

  **OBJECT PROPERTIES**

  - **`createdAt`** `string`

    The date and time when the item was last updated.

    Format: `date-time`

    Read only: true

  - **`id`** `integer`

    The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

    Read only: true

  - **`installedAt`** `string`

    The date and time when pass was first installed on the device.

    Format: `date-time`

  - **`platform`** `string`

    Wallet platform.

    Possible values: `iOS`, `Android`

  - **`serialNumber`** `string`

    The serial number of the pass.

  - **`status`** `string`

    Recent on-device pass status.

    Possible values: `installed`, `uninstalled`, `not_been_installed`

  - **`templateId`** `integer`

    The identifier for the template. You can recall the template by ID in other operations.

    Read only: true

  - **`uninstalledAt`** `string`

    The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled.

    Format: `date-time`

  - **`updatedAt`** `string`

    The date and time when the item was created.

    Format: `date-time`

    Read only: true

  - **`url`** `string`

    Pass download URL.

**Examples**

*Example request*

```http
GET /v1/tag/tag-name/passes 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

{
          "passes": [{
              "id": 61,
              "templateId": 1000057,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
              "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
              "createdAt": "2023-04-19T06:15:01.000Z",
              "updatedAt": "2023-04-19T06:15:01.000Z",
              "status": "installed",
              "installedAt": "2023-04-19T06:17:02.000Z",
              "platform": "android"
            },
            {
              "id": 51,
              "templateId": 1000081,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/51/download",
              "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e223",
              "createdAt": "2023-04-05T17:55:23.000Z",
              "updatedAt": "2023-04-05T17:55:23.000Z",
              "status": "installed",
              "installedAt": "2023-04-05T17:55:23.000Z",
              "platform": "ios"
            }
          ],
          "pagination": {
            "order": "id",
            "direction": "desc",
            "page": 1,
            "start": 0,
            "pageSize": 2
          }
}

```

---

## List passes for an Adaptive Link {#getpassesbyadaptivelink}

List passes for an adaptive link.


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

### `GET /links/adaptive/{adaptiveLinkId}/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 |
|------|------|----------|-------------|
| `adaptiveLinkId` | `string` | Required | The adaptive link ID used for pass creation. |

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | `string` |  | Find only passes matching the installation status.  * `installed` — passes currently installed. * `uninstalled` — passes that have been uninstalled. * `been_installed` — passes that have been either installed or uninstalled. * `not_been_installed` — passes that have never been installed.  Possible values: `installed`, `uninstalled`, `been_installed`, `not_been_installed` |
| `pageSize` | `integer` |  | The number of passes per page. Defaults to 10. Default: `10` |
| `page` | `integer` |  | The page of results you want to retrieve, starting at 1. Default: `1` |
| `order` | `string` |  | The order you want passes returned in, defaulting to `id`. Possible values: `id`, `createdAt`, `updatedAt` Default: `id` |
| `direction` | `string` |  | Determines whether to return values in ascending or descending order. Defaults to `DESC`. Possible values: `ASC`, `DESC` Default: `DESC` |

**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 a paged list of passes for a particular adaptive link.

Response body:

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

- **`count`** `integer`

  The total number of passes associated with an adaptive link.

- **`pagination`** `object` <[Pagination object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#paginationobject)>

  Contains information about pagination, according to your query parameters.

- **`passes`** `array[object]`

  The metadata for passes associated with the adaptive link. Each object in the array represents a pass.

**`404`** The adaptive link ID does not exist.


**Examples**

*Example request*

```http
GET /v1/links/adaptive/rthBWAWDaAA/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

```

*Response*

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

{
    "passes": [{
        "id": 616,
        "templateId": 1000057,
        "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/616/download",
        "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da0b8",
        "createdAt": "2023-04-19T06:17:01.000Z",
        "updatedAt": "2023-04-19T06:17:01.000Z",
        "status": "installed",
        "installedAt": "2023-04-19T06:17:02.000Z",
        "platform": "android"
      },
      {
        "id": 610,
        "templateId": 1000083,
        "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/610/download",
        "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e216",
        "createdAt": "2023-04-05T17:55:23.000Z",
        "updatedAt": "2023-04-05T17:55:23.000Z",
        "status": "installed",
        "installedAt": "2023-04-05T17:55:23.000Z",
        "platform": "android"
      }
    ],
    "pagination": {
      "order": "id",
      "direction": "desc",
      "page": 1,
      "start": 0,
      "pageSize": 2
    }
}

```

---

## Update pass {#updatepass}

Update the specified pass. You need only include the fields that you want to update for the pass.


  Optionally, you can also Schedule an update if you want to update a pass at a later date and time. See the `/schedules` endpoints for information about scheduling updates.


  Do not use the response payload from the `GET /v1/pass/(id)` endpoint to update a pass, as it contains information from both the pass itself and the template used to create the pass, and you cannot update a template from the  `/v1/pass endpoint`. You should only populate the JSON Parameters below. Within the headers and fields objects, these are the changeMessage,  value, and label fields.


  You can update `locations` on a pass, but doing so will replace all locations on the pass. See the Location Object for more about the fields you should provide in the locations array.

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

### `PUT /pass/{id}`

{{< note >}}
You can also update a pass to include an expiration date using the `expirationDate` key.
{{< /note >}}

**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 |
|------|------|----------|-------------|
| `id` | `string` | Required | The `id` of the pass you want to update. |

**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 from a pass object that you want to update.


Locations operate as a `set` operation. The array of pass locations is replaced by the locations you provide in an update; if you want to add to the locations on the pass, you must provide both the current locations and the locations you want to add in the payload.

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

- **`beacons`** `array` <[Beacon object]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#beacon)> **APPLE ONLY**

  An array of beacon objects you want to update for this pass.

- **`fields`** `object`

  The fields you want to update on the pass.

- **`headers`** `object`

  The headers you want to update for this pass.

- **`locations`** `array` <[Location object]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#locationobject)>

  The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.

- **`semantics`** `object` <[Boarding pass semantics]({{< ref "/developer/rest-api/wallet/schemas/flights-and-boarding-passes/" >}}#boardingpasssemantics)>

  An object that defines structured metadata for an Apple Wallet pass using key-value pairs. These semantic tags provide contextual information to the system to enhance the user experience.

  For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within `fields`.


- **`universalLinks`** `object` <[Universal links]({{< ref "/developer/rest-api/wallet/schemas/others/" >}}#universallinksobject)>

  An object containing key-value pairs of universal links where each key-value pair defines a universal link.

  A list of key-value pairs that represents partner URLs.

**Responses**

**`200`** A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.

Response body:

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

**One of:**

- [Apple Wallet pass response]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassapplewalletresponse)

  A pass response includes both identifiers and the content of all fields on a pass.

- [Google Wallet pass response]({{< ref "/developer/rest-api/wallet/schemas/passes/" >}}#createpassandroidpayresponse)

  A pass response for Google Wallet.  A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

Unlike templates, in which the `fieldsModel` contains fields nested inside `module` objects, fields are collapsed in pass requests and responses. The `fieldType` corresponds to the template field module (an object) that the field belongs to.


Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.



**Examples**

*Update expiration date example request*

```http
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
   "headers": {
      "expirationDate": {
            "value": "2024-08-20T9:41-08:00"
      }
   },
   "fields": {
      "Seat": {
            "value": "26E"
      }
   }
}

```

*Render pass void example request*

```http
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
   "headers": {
      "expirationDate": {
            "label": "voided"
      }
   }
}

```

*Example request*

```http
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
    "fields": {
       "Coupon": {
          "changeMessage": "Enjoy %@ off your next order!",
          "value": "20%",
          "label": "Coupon"
       },
       "SiteAddress": {
          "changeMessage": "Check out things we think you would like at %@",
          "value": "https://www.example.com/new?custnumb=123456",
          "label": "personal deals"
       },
       "InStore": {
          "changeMessage": "Or visit your nearest store at %@",
          "value": "1234 Fake St.",
          "label": "nearestStore"
       },
       "thumbnail_image": {
          "value": "https:\/\/example.com\/assets\/favicon.png"
       }
    },
    "beacons": [
       {
          "uuid": "55502220-A123-A88A-F321-555A444B333C",
          "relevantText": "You are near the Ship",
          "major": 1,
          "minor": 777
       },
       {
          "uuid": "55502220-A123-A88A-F321-555A444B333C",
          "relevantText": "You are near the Ship"
       }
    ],
    "locations":[
       {
           "longitude": -122.374,
           "latitude": 37.618,
           "relevantText": "Hello loc0",
           "streetAddress1": "address line #1",
           "streetAddress2": "address line #2",
           "city": "San Francisco",
           "region": "CA",
           "regionCode": "94404",
           "country": "US"
       }
    ]
}

```

*Response*

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "ticketId": 1234
}

```

---