1. Home
  2. /Developer
  3. /REST APIs
  4. /Wallet API
  5. /Data Formats
  6. /Passes

Passes

Schemas used when creating passes (as opposed to adaptive links).

Apple Wallet pass request

A pass for Apple Wallet.

Jump to examples ↓

OBJECT PROPERTIES
  • beacons array

    Beacons for an Apple pass.

  • fields object

    Fields for an Apple Wallet pass. Provide only the field objects and values you want to differentiate or personalize from the template.

  • headers object

    Headers on an Apple Wallet pass. Provide only the header objects and values you want to differentiate or personalize from the template. See Apple Template Headers for information about available header objects for Apple Wallet templates and passes.

    OBJECT PROPERTIES
    • expirationDate string

      May contain value and label fields. value indicates the expiration date of the pass. label can be set to either valid or voided, where valid indicates a non-expired pass and voided indicates that the pass is no longer accepted.

    • sharingStatus object

      A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.

      On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.

      You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.

      OBJECT PROPERTIES
      • changeMessage string

        The message that appears when you update this field.

      • value stringREQUIRED

        Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.

        Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

  • locations array

    A list of locations associated with a pass.

  • nfc object

    If your Apple certificate is NFC-enabled, and your terminals use Apple’s Value Added Services protocol, you can include this object in Loyalty passes to identify pass holders and provide their credentials over NFC.

    OBJECT PROPERTIES
    • encryptionPublicKey stringREQUIRED

      The public encryption key for NFC communications. Use a Base64 encoded X.509 SubjectPublicKeyInfo structure containing a ECDH public key for group P256.

    • message stringREQUIRED

      The payload for an Apple Pay terminal, 64 bytes or less. Messages longer than 64 bytes are truncated.

  • publicUrl object

    A public URL from which users can download a pass.

    For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify type: single in the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.

    For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.

    OBJECT PROPERTIES
    • installs integer

      The number of users who have installed the pass from the URL specified in the path field.

    • path string

      The URL for the pass.

    • type stringREQUIRED

      Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.

      Possible values: single, multiple

    • used boolean

      If true, a user has accessed the path URL.

  • semantics object<Boarding pass semantics>

    Apple boarding pass only, top-level semantics.

    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.

  • tags array[string]

    An array of tags associated with the pass.

  • templateId integer

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

Used in:

Examples

Example pass for Apple Wallet

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

Apple Wallet pass response

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

Jump to examples ↓

All of
  • Create Pass Apple Wallet Request

    A pass for Apple Wallet.

  • OBJECT PROPERTIES
    • createdAt string

      The date and time when the item was created.

    • externalId string

      The external ID for the pass, returned only if you created the pass using an external ID.

    • id integer

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

    • publicUrl object

      A public URL from which users can download a pass.

      For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify type: single in the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.

      For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.

      OBJECT PROPERTIES
      • installs integer

        The number of users who have installed the pass from the URL specified in the path field.

      • path string

        The URL for the pass.

      • type stringREQUIRED

        Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.

        Possible values: single, multiple

      • used boolean

        If true, a user has accessed the path URL.

    • serialNumber string
    • status string

      Indicates whether a pass has been installed or not.

      Possible values: installed, not_been_installed

    • tags array[string]

      Tags associated with the pass.

    • uaEntityId string
    • updatedAt string

      The date and time when the item was last updated.

    • url string

      The URL for the pass.

Used in:

Examples

Example Apple Wallet pass response

{
    "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": {
        "sale": {
            "changeMessage": "Hey %@, check out our new sale!",
            "fieldType": "HEADER",
            "value": "20%",
            "label": "Percent off",
            "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
        }
    ]
}

Beacon object

Associates a pass with an iBeacon. Apple Wallet supports up to 10 beacons per pass. When the pass holder comes into proximity with an iBeacon bearing the same UUID, the pass becomes relevant (displayed on the lock screen).

Jump to examples ↓

OBJECT PROPERTIES
  • major integerREQUIRED

    Major identifier of a beacon.

  • minor integerREQUIRED

    Minor identifier of a beacon.

  • relevantText stringREQUIRED

    Text displayed on the lock screen.

  • uuid stringREQUIRED

    Unique identifier of a beacon.

Used in:

Examples

Example beacon object

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

Google Wallet pass 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.

Jump to examples ↓

OBJECT PROPERTIES
  • fields object

    Fields for the pass. The template defines a field’s location on the pass and its default value(s). When creating a pass, you only need to populate the fields you want to update, and even then, you only need to provide the value you want to change for the field and the changeMessage if you want to notify pass holders of the change in the value.

  • headers object

    Include objects from the template headers object if you want to change the label, value, or changeMessage for fields in the pass header — like barcodes and titles.

    OBJECT PROPERTIES
    • expirationDate string

      May contain value and label fields. value indicates the expiration date of the pass. label can be set to either valid or voided, where valid indicates a non-expired pass and voided indicates that the pass is no longer accepted.

  • locations array

    A list of locations associated with a pass.

  • publicUrl objectREQUIRED

    A public URL from which users can download a pass.

    For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify type: single in the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.

    For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.

    OBJECT PROPERTIES
    • installs integer

      The number of users who have installed the pass from the URL specified in the path field.

    • path string

      The URL for the pass.

    • type stringREQUIRED

      Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.

      Possible values: single, multiple

    • used boolean

      If true, a user has accessed the path URL.

  • templateId integer

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

Used in:

Examples

Example Google pass request

{
    "headers": {
         "expirationDate":{
            "value":"2014-08-20T9: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"
      }
    },
    "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"
    }
}

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.

Jump to examples ↓

OBJECT PROPERTIES
  • createdAt string

    The date and time when the item was created.

  • externalId string

    The external ID for the pass, returned only if you created the pass using an external ID.

  • fields object

    Contains all populated fields from the template. The fieldType within each object indicates the module it belonged to.

    While all fields take a similar shape, the response may contain different keys to represent the value or label from the originating template field. This has to do with the way that Google Wallet interprets templates and passes.

    OBJECT PROPERTIES
    • offerModule object

      Specific to google coupons, this module contains information about redeeming the coupon.

      OBJECT PROPERTIES
      • endTime string

        The expiration date for the offer.

      • multiUseOffer boolean

        Indicates whether the coupon/offer is available for multiple users or just a single user.

      • provider string

        The offer provider name.

      • redemptionChannel string

        Indicates whether the user can redeem the offer at a physical location or online.

        Possible values: online, instore, both, temporaryPriceReduction

  • headers object<Google headers>

    Fields appearing in the headers object for a Google pass template. Header fields typically follow the same model as other fields for Google Wallet templates and passes, but often have specific value, fieldType, and formatType values.

  • id integer

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

  • publicUrl object

    A public URL from which users can download a pass.

    For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify type: single in the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.

    For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.

    OBJECT PROPERTIES
    • installs integer

      The number of users who have installed the pass from the URL specified in the path field.

    • path string

      The URL for the pass.

    • type stringREQUIRED

      Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.

      Possible values: single, multiple

    • used boolean

      If true, a user has accessed the path URL.

  • serialNumber string
  • status string

    Indicates whether a pass has been installed or not.

    Possible values: installed, not_been_installed

  • tags array[string]

    Tags associated with the pass.

  • uaEntityId string
  • updatedAt string

    The date and time when the item was last updated.

  • url string

    The URL for the pass.

Used in:

Examples

Example Google pass response

{
  "createdAt": "2018-10-25T19:13:14Z",
  "headers": {
      "background_color": {
          "ignoresTimeZone": null,
          "changeMessage": null,
          "label": "",
          "hideEmpty": false,
          "formatType": "String",
          "value": "#006491",
          "fieldType": "topLevel",
          "required": false
      },
      "strip_image": {
          "ignoresTimeZone": null,
          "changeMessage": null,
          "label": "",
          "hideEmpty": false,
          "formatType": "String",
          "value": "https://s3.amazonaws.com/passtools_prod/1169167/images/587ac4e3d188b0fcd4f05038d8814fefd82ac834_iOS_Logo_320x100_WHITE.png",
          "fieldType": "image",
          "required": false
      },
      "expirationDate": {
          "ignoresTimeZone": null,
          "changeMessage": null,
          "label": "",
          "hideEmpty": false,
          "formatType": "String",
          "value": "2019-10-25T19:13:14Z",
          "fieldType": "topLevel",
          "required": false
      }
  },
  "serialNumber": "06bad8bd-b399-4c86-83b6-06fcee2e52b6",
  "uaEntityId": "9e3bf713-f6e6-4d6e-b2d4-c9ab6028892e",
  "id": "47400533",
  "templateId": "63621",
  "fields": {
      "image": {
          "ignoresTimeZone": null,
          "title.string": "https://s3.amazonaws.com/passtools_prod/1169167/images/9af688aea35f473e29ca187438c12083202f1eeb_Android_Logo_660x660.png",
          "hideEmpty": false,
          "formatType": "String",
          "fieldType": "titleModule",
          "description.string": "Logo Image"
      },
      "Details": {
          "col": 0,
          "ignoresTimeZone": null,
          "header": "Coupon Details",
          "hideEmpty": false,
          "row": 0,
          "formatType": "String",
          "body": "25% off when you spend £20 or more online using code WNTRBLOG",
          "fieldType": "textModulesData"
      },
      "FinePrint": {
          "col": 0,
          "ignoresTimeZone": null,
          "header": "Terms & Conditions ",
          "hideEmpty": false,
          "row": 0,
          "formatType": "String",
          "body": "Please go to http://www.dominos.co.uk and click on “Boring Legal Stuff”",
          "fieldType": "textModulesData"
      },
      "offerModule": {
          "multiUserOffer": false,
          "redemptionChannel": "both",
          "provider": "Domino's Snap Offer",
          "endTime": "2018-01-31T00:00:00.000Z"
      },
      "Merchant Website": {
          "ignoresTimeZone": null,
          "description": "Visit Us Online",
          "hideEmpty": false,
          "formatType": "URL",
          "uri": "https://www.dominos.co.uk/?vc=WNTRBLOG",
          "fieldType": "linksModuleData",
          "order": 1
      },
      "imageModulesData": {
          "image": "https://s3.amazonaws.com/passtools_prod/1169167/images/834420d3cbf287f56c8be46806e58e23e8296e94_Android_Hero_1032x336_Opt1.png",
          "ignoresTimeZone": null,
          "imageDescription": "Logo Image",
          "hideEmpty": false,
          "formatType": "String",
          "fieldType": "imageModulesData"
      },
      "Coupon Title": {
          "col": 0,
          "ignoresTimeZone": null,
          "title.string": "Coupon",
          "hideEmpty": false,
          "row": 0,
          "formatType": "String",
          "fieldType": "titleModule",
          "description.string": "25% Off Online "
      }
  },
  "url": "https://wallet-api.urbanairship.com/v1/pass/47400533/download",
  "updatedAt": "2018-10-25T19:13:14Z",
  "tags": [],
  "status": "installed"
}