Apple Passes Only

Operations that apply only to Apple Wallet passes.

Add or update beacons for Apple Wallet pass

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

Jump to examples ↓

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

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

templateId stringREQUIRED
The template of the Apple Wallet pass that you want to apply beacons to.
passExternalId stringREQUIRED
The external ID of the Apple Wallet pass you want to apply beacons to.

Request body:

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

Content-Type: application/json
OBJECT PROPERTIES
- beacons array
  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
  OBJECT PROPERTIES
  - 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

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
       }
    ]
 }

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

{
   "ticketId": 7
}

Download Apple Wallet .pkpass

Download the contents of an Apple Wallet .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes.

See Apple’s developer documentation for information about .pkpass files and contents.

Jump to examples ↓

GET /pass/{passId}/download

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

passId stringREQUIRED
The id of the pass you want to download.

Responses

200
Returns the .pkpass file as a .zip extension.

Examples

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

Download Apple Wallet .pkpass with external ID

Download the contents of an Apple Wallet .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes.

See Apple’s developer documentation for information about .pkpass files and contents.

Jump to examples ↓

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

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

templateId stringREQUIRED
The template used to create the pass.
passExternalId stringREQUIRED
The external ID of the pass you want to download.

Responses

200
Returns the .pkpass file as a .zip extension.
404
The pass or template ID does not exist.

Examples

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 .pkpass file

Download Apple Wallet passes in a single .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes. See also Download multiple Apple Wallet Passes in a single .pkpass file with external ID.

See Apple’s developer documentation for information about .pkpass files and contents.

Jump to examples ↓

GET /pass/download

Query parameters:

passIds stringREQUIRED
One or more pass IDs (comma separated) that should be included in the download.

Request headers:

Api-Revision stringREQUIRED
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

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

Download multiple Apple Wallet Passes with external IDs in a single .pkpass file

Download Apple Wallet passes with external IDs in a single .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes. See also Download multiple Apple Wallet Passes in a single .pkpass file.

See Apple’s developer documentation for information about .pkpass files and contents.

Jump to examples ↓

GET /pass/template/{templateId}/download

Query parameters:

exids stringREQUIRED
The external IDs (comma separated) of the passes that you want in the download.

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

templateId stringREQUIRED
The ID of the template the pass will be or was created from. For External IDs, format the {templateId} as id/{templateExternalId}.

Responses

200
Returns the .pkpass file as a .zip extension.
404
The pass or template ID does not exist.

Examples

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

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

Lists location beacons assigned to the specified Apple Wallet pass.

Jump to examples ↓

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

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

templateId stringREQUIRED
The template of the Apple Wallet pass that you want to get beacons from.
passExternalId stringREQUIRED
The external ID of the Apple Wallet pass you want to get beacons for.

Responses

200
An array of beacons belonging to the pass.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - beacons array
    An array of objects, each representing a beacon associated with the Apple Wallet pass.
404
The pass or template ID does not exist.

Examples

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

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

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 for information about Apple Wallet payloads.

Jump to examples ↓

GET /pass/{passId}/viewJSONPass

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

passId stringREQUIRED
The id of the pass you want to return Apple Wallet JSON for.

Responses

200
A successful request returns Apple JSON
Response body:
- Content-Type: application/json
  Type: object

Examples

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

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 Reach",
            "value": "Find out more and create your own passes at https://wallet.urbanairship.com\n\nAirship, Inc.,1417 NW Everett St., Portland, OR 97209 800.720.2098 support@urbanairship.com"
         }
      ],
      "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

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 for information about Apple Wallet payloads.

Jump to examples ↓

GET /pass/id/{passExternalId}/viewJSONPass

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

passExternalId stringREQUIRED
The custom identifier of the pass you want to return Apple Wallet JSON for.

Responses

200
Returns JSON as passed to Apple Wallet.
Response body:
- Content-Type: application/json
  Type: object

Examples

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

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 Reach",
            "value": "Find out more and create your own passes at https://wallet.urbanairship.com\n\nAirship, Inc.,1417 NW Everett St., Portland, OR 97209 800.720.2098 support@urbanairship.com"
         }
      ],
      "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)"
}