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

Add the locations to the specified pass.

Jump to examples ↓

POST /pass/{passId}/locations

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:

passId stringREQUIRED
The pass you want to add locations to.

Request body:

Set locations for the pass.

Content-Type: application/json
Type: object

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

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"
    },
    { "...": "..." }
  ]
}

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

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 ↓

POST /pass/{id}

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:

id stringREQUIRED
The id of the template you want to create your pass from.

Request body:

Create a pass; pass composition varies by vendor.

Content-Type: application/json
One of
- Create Pass Apple Wallet Request
  A pass for Apple Wallet.
- Create Pass Android Pay Request
  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
    A pass response includes both identifiers and the content of all fields on a pass.
  - Google Wallet pass response
    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

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:\/\/wallet.urbanairship.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"
    }
}

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:\/\/s3.amazonaws.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

Delete the specified location from the specified pass.

Jump to examples ↓

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

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:

passId stringREQUIRED
The id of the pass you want to remove locations from.
passLocationId stringREQUIRED
The location you want to remove from the pass.

Responses

200
Success.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - locations array

Examples

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

Delete pass

Delete the specified pass.

Jump to 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 to deactivate the pass on the end-user’s device.

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:

id stringREQUIRED
The id of the pass you want to delete.

Responses

200
The pass was successfully deleted.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - passId integer
    The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
  - status string
    Indicates that the pass was deleted.
    Possible values: deleted

Examples

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

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

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

Generates a pass

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 ↓

POST /pass/{id}/dynamic

Security:

httpBasic

Query parameters:

expiry string
The expiration date for the pass.

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:

id stringREQUIRED
The templateId of the template you want to create the pass from.

Request body:

Create a pass; pass composition varies by vendor.

Content-Type: application/json
One of
- Create Pass Apple Wallet Request
  A pass for Apple Wallet.
- Create Pass Android Pay Request
  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
    A pass response includes both identifiers and the content of all fields on a pass.
  - Google Wallet pass response
    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

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:\/\/wallet.urbanairship.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"
}

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

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 ↓

GET /pass/{id}

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:

id stringREQUIRED
The id of the pass you want to look up.

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
    A pass response includes both identifiers and the content of all fields on a pass.
  - Google Wallet pass response
    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

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

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:\/\/s3.amazonaws.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

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 ↓

GET /pass

Security:

httpBasic

Query parameters:

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:

Api-Revision stringREQUIRED
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
  OBJECT PROPERTIES
  - count integer
    The total number of passes associated with the template.
  - pagination object<Pagination object>
    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

GET /v1/pass?templateId=12345&status=uninstalled HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

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

List the passes associated with the specified tag.

Jump to examples ↓

GET /tag/{tag}/passes

Security:

httpBasic

Query parameters:

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:

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

Path parameters:

tag stringREQUIRED
A tag id or name. The request returns a paginated list of passes associated with the specified tag.

Responses

200
A successful response returns a paginated array of passes.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - count integer
    The total number of results.
  - pagination object<Pagination object>
    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.
    - id integer
      The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
    - installedAt string
      The date and time when pass was first installed on the device.
    - 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.
    - uninstalledAt string
      The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled.
    - updatedAt string
      The date and time when the item was created.
    - url string
      Pass download URL.

Examples

GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

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

List passes for an adaptive link.

Jump to examples ↓

GET /links/adaptive/{adaptiveLinkId}/passes

Security:

httpBasic

Query parameters:

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:

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

Path parameters:

adaptiveLinkId stringREQUIRED
The adaptive link ID used for pass creation.

Responses

200
A successful request returns a paged list of passes for a particular adaptive link.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - count integer
    The total number of passes associated with an adaptive link.
  - pagination object<Pagination object>
    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

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

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

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 ↓

PUT /pass/{id}

Note

You can also update a pass to include an expiration date using the expirationDate key.

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:

id stringREQUIRED
The id of the pass you want to update.

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
Update Wallet Pass
OBJECT PROPERTIES
- beacons arrayAPPLE 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
  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>
  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>
  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
    A pass response includes both identifiers and the content of all fields on a pass.
  - Google Wallet pass response
    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

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

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

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

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:\/\/wallet.urbanairship.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"
       }
    ]
}

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

{
    "ticketId": 1234
}