# Apple Passes Only

Operations that apply only to Apple Wallet passes.


## Add or update beacons for Apple Wallet pass {#addreplacebeaconsforpassexternalid}

Add or replace beacons on the specified Apple Wallet pass with an external ID.

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

### `PUT /pass/template/{templateId}/id/{passExternalId}/beacons`

**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 |
|------|------|----------|-------------|
| `templateId` | `string` | Required | The template of the Apple Wallet pass that you want to apply beacons to. |
| `passExternalId` | `string` | Required | The external ID of the Apple Wallet pass you want to apply beacons 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**

An array of beacons that you want to associate with the pass.

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

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

  An array of objects, each representing a beacon you want to add to an Apple Wallet pass.


**Responses**

**`201`** A successful call results in a ticket to apply beacons to the pass.

Response body:

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

- **`ticketId`** `integer`

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

**`404`** The pass or template ID does not exist.

**Examples**

*Example request*

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

 {
    "beacons":[
       {
          "uuid": "55502220-A123-A88A-F321-555A444B333C",
          "relevantText": "You are near the Ship",
          "major": 2,
          "minor": 346
       }
    ]
 }

```

*Response*

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

{
   "ticketId": 7
}

```

---

## Download an Apple Wallet .pkpass {#getapplewalletpass}

Download an Apple Wallet pass as a .pkpass file, using its pass ID. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes. To download a pass using an external ID, see [Download an Apple Wallet .pkpass by external ID](#operation-pass-template-templateid-id-passexternalid-download-get).

See [Apple's developer documentation](https://developer.apple.com/wallet/) for information about .pkpass files and contents.

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

### `GET /pass/{passId}/download`

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

**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 the .pkpass file as a .zip extension.

**Examples**

*Example request*

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

```

---

## Download an Apple Wallet .pkpass by external ID {#getapplewalletpassfortemplateexternalid}

Download an Apple Wallet pass as a .pkpass file, using its external ID and template ID. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes. To download a pass using its pass ID, see [Download an Apple Wallet .pkpass](#operation-pass-passid-download-get).


See [Apple's developer documentation](https://developer.apple.com/wallet/) for information about .pkpass files and contents.


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

### `GET /pass/template/{templateId}/id/{passExternalId}/download`

**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 |
|------|------|----------|-------------|
| `templateId` | `string` | Required | The template used to create the pass. |
| `passExternalId` | `string` | Required | The external ID of the pass you want to download. |

**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 the .pkpass file as a .zip extension.

**`404`** The pass or template ID does not exist.

**Examples**

*Example request*

```http
GET /v1/pass/template/123/id/mypass/download HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2 

```

---

## Download multiple Apple Wallet passes in a single .pkpasses file {#getapplewalletpasses}

Download multiple Apple Wallet passes bundled into a single .pkpasses file, using their pass IDs provided as a comma-separated query parameter. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes. To download multiple passes using external IDs, see [Download multiple Apple Wallet passes in a single .pkpasses file by external ID](#operation-pass-template-templateid-download-get).

See [Apple's developer documentation](https://developer.apple.com/wallet/) for information about .pkpass files and contents.

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

### `GET /pass/download`

**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 |
|------|------|----------|-------------|
| `passIds` | `string` | Required | One or more pass IDs (comma separated) that should be included in the download. |

**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 the .pkpasses file as a .zip extension.

**Examples**

*Example request*

```http
GET /v1/pass/download?passIds=123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

```

---

## Download multiple Apple Wallet passes in a single .pkpasses file by external ID {#getapplewalletmultipassfortemplateexternalid}

Download multiple Apple Wallet passes bundled into a single .pkpasses file, using their external IDs provided as a comma-separated query parameter and a template ID. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes. To download multiple passes using pass IDs, see [Download multiple Apple Wallet passes in a single .pkpasses file](#operation-pass-download-get).

See [Apple's developer documentation](https://developer.apple.com/wallet/) for information about .pkpass files and contents.


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

### `GET /pass/template/{templateId}/download`

**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 |
|------|------|----------|-------------|
| `templateId` | `string` | Required | The ID of the template the pass will be or was created from. For [External IDs](/docs/developer/rest-api/wallet/introduction/#external-ids), format the `{templateId}` as `id/{templateExternalId}`. |

**Query parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `exids` | `string` | Required | The external IDs (comma separated) of the passes that you want in the download. |

**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 the .pkpasses file as a .zip extension.

**`404`** The pass or template ID does not exist.

**Examples**

*Example request*

```http
GET /v1/pass/template/123/download?exids=mypass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2 

```

*Example request with external template ID*

```http
GET /v1/pass/template/id/1234/download?exids=mypass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2 

```

---

## List beacons on Apple Wallet pass {#getbeaconsforpassexternalid}

Lists location beacons assigned to the specified Apple Wallet pass.


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

### `GET /pass/template/{templateId}/id/{passExternalId}/beacons`

**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 |
|------|------|----------|-------------|
| `templateId` | `string` | Required | The template of the Apple Wallet pass that you want to get beacons from. |
| `passExternalId` | `string` | Required | The external ID of the Apple Wallet pass you want to get beacons for. |

**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`** An array of beacons belonging to the pass.

Response body:

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

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

  An array of objects, each representing a beacon associated with the Apple Wallet pass.


**`404`** The pass or template ID does not exist.

**Examples**

*Example request*

```http
GET /v1/pass/template/123/id/mypass/beacons HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

```

*Response*

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

{
   "beacons":[
      {
         "uuid": "55502220-A123-A88A-F321-555A444B333C",
         "relevantText": "You are near the Ship",
         "major": 2,
         "minor": 346
      }
   ]
}

```

---

## View Apple Wallet JSON {#getapplewalletpassjson}

Returns the JSON of an Apple Wallet pass. The Airship request payload is translated when sent to Apple. You can use this endpoint to view the JSON payload as passed to Apple Wallet for debugging purposes.

See [Apple's developer documentation](https://developer.apple.com/wallet/) for information about Apple Wallet payloads.

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

### `GET /pass/{passId}/viewJSONPass`

**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 return Apple Wallet JSON for. |

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

Response body:

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

Type: `object`

**Examples**

*Example request*

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

```

*Response*

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

{
   "passTypeIdentifier": "pass.com....",
   "storeCard": {
      "backFields":[
         {
            "key": "Program Details",
            "label": "Program Details",
            "value": "Some information about how the loyalty program works and its benefits.\n\nAdditional terms and support information."
         },
         {
            "key": "Merchant Website",
            "label": "Merchant Website",
            "value": "http:\/\/www.example.com"
         },
         {
            "key": "back0",
            "label": "Built with Airship Mobile Wallet",
            "value": "Find out more and create your own passes at https://www.airship.com/channels/mobile-wallet/"
         }
      ],
      "primaryFields":[
         {
            "key": "Program Name",
            "label": "Airship",
            "value": "Program Name",
            "textAlignment": "PKTextAlignmentNatural"
         }
      ],
      "headerFields":[
         {
            "key": "Points",
            "label": "Points",
            "value": 1234.0,
            "textAlignment": "PKTextAlignmentNatural",
            "numberStyle": "PKNumberStyleDecimal"
         }
      ],
      "secondaryFields":[
         {
            "key": "Tier",
            "label": "Tier",
            "value": 2.0,
            "textAlignment": "PKTextAlignmentNatural",
            "numberStyle": "PKNumberStyleDecimal"
         },
         {
            "key": "Tier Name",
            "label": "Tier Name",
            "value": "Silver",
            "textAlignment": "PKTextAlignmentNatural"
         },
         {
            "key": "Member Name",
            "label": "Member Name",
            "value": "First Last",
            "textAlignment": "PKTextAlignmentNatural"
         }
      ]
   },
   "organizationName": "Airship",
   "backgroundColor": "rgb(0,147,201)",
   "labelColor": "rgb(24,86,148)",
   "authenticationToken": "df897c90-5a9b-48dd-a4b4-8020486811b7",
   "serialNumber": "bcc7cdae-e491-4e36-a95e-9758e31549aa",
   "barcode": {
      "message": "123456789",
      "messageEncoding": "iso-8859-1",
      "format": "PKBarcodeFormatPDF417",
      "altText": "123456789"
   },
   "teamIdentifier": "MN52833CEX",
   "formatVersion": 1,
   "webServiceURL": "https:\/\/wallet-api.urbanairship.com\/apple",
   "description": "Template 1",
   "foregroundColor": "rgb(255,255,255)"
}

```

---

## View Apple Wallet JSON with external ID {#getapplewalletpassjsonexternalid}

View the JSON of an Apple Wallet Pass. The Airship request payload is different from the JSON payload contained in an Apple Wallet pass. You can use this endpoint to view the JSON payload as passed to Apple Wallet.

See [Apple's developer documentation](https://developer.apple.com/wallet/) for information about Apple Wallet payloads.

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

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

**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 |
|------|------|----------|-------------|
| `passExternalId` | `string` | Required | The custom identifier of the pass you want to return Apple Wallet JSON for. |

**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 JSON as passed to Apple Wallet.

Response body:

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

Type: `object`

**Examples**

*Example request*

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

```

*Response*

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

{
   "passTypeIdentifier": "pass.com....",
   "storeCard": {
      "backFields":[
         {
            "key": "Program Details",
            "label": "Program Details",
            "value": "Some information about how the loyalty program works and its benefits.\n\nAdditional terms and support information."
         },
         {
            "key": "Merchant Website",
            "label": "Merchant Website",
            "value": "http:\/\/www.example.com"
         },
         {
            "key": "back0",
            "label": "Built with Airship Mobile Wallet",
            "value": "Find out more and create your own passes at https://www.airship.com/channels/mobile-wallet/"
         }
      ],
      "primaryFields":[
         {
            "key": "Program Name",
            "label": "Airship",
            "value": "Program Name",
            "textAlignment": "PKTextAlignmentNatural"
         }
      ],
      "headerFields":[
         {
            "key": "Points",
            "label": "Points",
            "value": 1234.0,
            "textAlignment": "PKTextAlignmentNatural",
            "numberStyle": "PKNumberStyleDecimal"
         }
      ],
      "secondaryFields":[
         {
            "key": "Tier",
            "label": "Tier",
            "value": 2.0,
            "textAlignment": "PKTextAlignmentNatural",
            "numberStyle": "PKNumberStyleDecimal"
         },
         {
            "key": "Tier Name",
            "label": "Tier Name",
            "value": "Silver",
            "textAlignment": "PKTextAlignmentNatural"
         },
         {
            "key": "Member Name",
            "label": "Member Name",
            "value": "First Last",
            "textAlignment": "PKTextAlignmentNatural"
         }
      ]
   },
   "organizationName": "Airship",
   "backgroundColor": "rgb(0,147,201)",
   "labelColor": "rgb(24,86,148)",
   "authenticationToken": "df897c90-5a9b-48dd-a4b4-8020486811b7",
   "serialNumber": "bcc7cdae-e491-4e36-a95e-9758e31549aa",
   "barcode": {
      "message": "123456789",
      "messageEncoding": "iso-8859-1",
      "format": "PKBarcodeFormatPDF417",
      "altText": "123456789"
   },
   "teamIdentifier": "MN52833CEX",
   "formatVersion": 1,
   "webServiceURL": "https:\/\/wallet-api.urbanairship.com\/apple",
   "description": "Template 1",
   "foregroundColor": "rgb(255,255,255)"
}

```

---