NAV
passkit-logo
curl

Introduction

PassKit v3 API Documentation

The PassKit API v3 tools serve as the client interface to the latest PassKit web service. Use these tools to create and update your mobile wallet campaigns, templates, and passes. If you cannot find a method to achieve your objective or are struggling to use the API, please contact our support team with any questions you may have.

This documentation currently only provides information on how to use the API in shell. Let us know which language you would like us to provide SDKs and documentation for next.

Basic Data Model



data-model-concept


Above diagram shows the role and the relationship between different models. Each model has its own role. When those models combines together, it becomes a pass.

Name Role Description
Campaign Business Logic Store the business logic of a campaign. (e.g. start date of the campaign, limited the number of pass of specific campaign, etc.)
Template Design & Style Store the design and style among different wallets. (e.g. color, images, layout, etc.)
Pass Data Store the data of a user. (e.g. name of the user, memberID, points, etc.)

Authentication

JSON Web Tokens (for v3)

Your JWT token needs to conform to this structure:

{
  "Header":{
    "alg":"HS256",
    "typ":"JWT"
  },
  "Payload":{
    "key":"your_api_key",
    "iat":1437523200,
    "signature":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "url":"https://api-pass.passkit.net/v3/subusers",
    "method":"POST"
  }
}

The token must be signed with your API secret

PassKit v3 uses JSON web tokens (JWT) to authorize your requests. A number of libraries to help generate your JWT, as well as a JWT debugging tool, can be found at jwt.io.

If you use our SDKs then you are able to just add your API Key and Secret to the SDK, which will then handle the authorisation. If there are no suitable SDKs available, the following instructions will help you generate a JWT (JSON Web Token) and attach it to the request.

The JWT needs to be signed with the HS256 algorithm (which should be noted in the token headers) and it must be signed with your API secret.

The JWT payload required in PassKit’s v3 API is:

In v3, we would verify your request with above information to enhance the security.

The following conditions will fail in the verification process.

  1. The timestamp difference between iat and current timestamp is over 60 seconds.
  2. The hashed value of request payload is not match the signature in the JWT for POST and PUT method.
  3. The request URL is not match the url in the JWT
  4. The request method is not match the method in the JWT

Authorizing Requests

To authorize, use this code:

# With shell, you need to provide a valid JSON web token with each request

curl "api_endpoint_here"
  -H "Authorization: PKAuth json_web_token"

# Make sure to replace `json_web_token` with your generated token.
// Note: Make sure to import the passkitSDK package

PassKit pk = new PassKit("apiKey","apiSecret");

// Make sure to replace `apiKey` and `apiSecret` with you own credentials.
// Note: Make sure to import the passkitSDK package

$pk = new PassKit("apiKey","apiSecret");

// Make sure to replace `apiKey` and `apiSecret` with you own credentials.

All requests to the API need to be authorised. This means that you will need to generate a new JWT with each shell request.

Once the JWT is generated it needs to be added as a header with the prefix PKAuth.

The full http header looks like:

Authorization: PKAuth json_web_token

Campaigns

Campaigns is a concept to let you put your business logic into (e.g. start date of the campaign, the maximum number of pass in a campaign ,etc.). Before you create a pass, you must create a campaign to link them all together.

Create a Campaign

Create a campaign

curl https://api-pass.passkit.net/v3/campaigns
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "name":"campaignName",
  "passbookCertId":"Poxgb4dEJa",
  "status":"ACTIVE",
  "startDate":"2016-01-01T00:00:00Z",
  "endDate":"2018-01-01T00:00:00Z",
  "googleServiceAccount":"myGoogleServiceAccount@developer.gserviceaccount.com",
  "googleIssuerId":"111111111111111",
  "maxIssue":0,
  "meta":{
    "myKey":123,
    "myKey2":"myData"
  },
  "callbackUrl":{
    "onIssueCallbackUrl":"https://passkit.com/createhook",
    "onUpdateCallbackUrl":"https://passkit.com/updatehook",
    "onRegisterCallbackUrl":"https://passkit.com/registerhook",
    "onDeregisterCallbackUrl":"https://passkit.com/deregisterhook"
  },
  "hookEndpoint":"https://your-data-source.com",
  "dynamicKeys":[
    {
      "key":"key1",
      "type":"string|number|dateTime",
      "defaultValue":"defaultValue",
      "isEditable":"true|false"
    }
  ],
  "dynamicImageKeys":{
    "passbook":{
      "background":"images/dynamic/d583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "footer":"images/dynamic/e583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "icon":"images/dynamic/f583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "logo":"images/dynamic/g583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "strip":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "thumbnail":"images/dynamic/i583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png"
    }
  }
}

On success the api will respond with the Campaign Name in JSON format:

{
  "name": "campaignName"
}

HTTP Request

POST https://api-pass.passkit.net/v3/campaigns

JSON Body Parameters

Parameter Data Type Description
name string Required. Your campaign’s unique identifier. The name must only contain letters, numbers or the underscore character. and cannot contain any spaces (e.g. Happy_birthday_2018). Please note, this identifier cannot be changed after the campaign is created.
passbookCertId string Required. This is a prerequisite of enabling Apple Wallet on a campaign. This is the certificate ID that is generated by PassKit when you upload a certificate, you can check which certificates you have uploaded with the list certificates endpoint. This value cannot be changed after the value is set
status string The value must be either ACTIVE, FROZEN, or INVALID. Default is ACTIVE.

The campaign status controls whether passes can be issued or not.
ACTIVE - Enables passes to be issued.
FROZEN - Passes cannot be issued, existing passes are not affected and this value can be changed back to ACTIVE.
INVALID - Passes cannot be issued and all existing passes will be set to invalid. Once the INVALID value is set, it cannot be changed.
startDate
(required)
ISO8601 datetime The campaign start date. Passes cannot be issued before this time and date.
endDate ISO8601 datetime The campaign end date. Passes cannot be issued after this date and time, and all existing passes will be set to voided.
googleServiceAccount string Google service account name. This is a prerequisite of enabling Android Pay on a campaign. This value cannot be changed after the value is set
googleIssuerId string A Google issuer ID in Android Pay Merchant Center. This is a prerequisite of enabling Android Pay on a campaign. This value cannot be changed after the value is set
hookEndpoint string The API pulls the data from the URL during pass creation or update and the endpoint. The connection has to be SSL enabled (https). For more detail of enabling this functionality. Please contact us
dynamicKeys an array of Dynamic Keys You can define what kind of information you want to collect from the end-user during the pass issue process. Once this value is specified, the end-user will be redirected to a landing page containing a web form which is used to collect user information during the pass issue process. For example, specifying email as a key will enable the landing page to show a web form field to collect the user’s email address. This data is stored in a field called dynamicData which held in the pass record when a pass is successfully issued. For more details regarding pass records, please see pass JSON.

You can see a live web form demo here
dynamicImageKeys JSON object A list of flags to control images in the pass. Please see Dynamic Image Keys
meta JSON Object Metadata to store in campaign level. This data is invisiable to users.
maxIssue integer This is the maximum number of passes that can be issued within the campaign and can be used to limit the issued passes to a specific amount. Setting the value to 0 will allow an unlimited number off passes that can be issued for the campaign. Default is set at 0.
callbackUrl object An object to define event webhooks for pass activities. We will send a POST request to the URL defined in the object. Please see the detail here

onIssueCallbackUrl - An event will fire when a pass is created.
onUpdateCallbackUrl - An event will fire when a pass is updated
onRegisterCallbackUrl - An event will fire when a pass is installed on the Phone
onDeregisterCallbackUrl - An event will fire when a pass is uninstalled the on the Phone (only available for iOS, Pass2U and mWallet App)

Update a Campaign

Update a campaign

curl https://api-pass.passkit.net/v3/campaigns/campaignName
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "name":"campaignName",
  "passbookCertId":"Poxgb4dEJa",
  "status":"ACTIVE",
  "startDate":"2016-01-01T00:00:00Z",
  "endDate":"2018-01-01T00:00:00Z",
  "googleServiceAccount":"myGoogleServiceAccount@developer.gserviceaccount.com",
  "googleIssuerId":"111111111111111",
  "maxIssue":0,
  "meta":{
    "myKey":123,
    "myKey2":"myData"
  },
  "callbackUrl":{
    "onIssueCallbackUrl":"https://passkit.com/createhook",
    "onUpdateCallbackUrl":"https://passkit.com/updatehook",
    "onRegisterCallbackUrl":"https://passkit.com/registerhook",
    "onDeregisterCallbackUrl":"https://passkit.com/deregisterhook"
  },
  "hookEndpoint":"https://your-data-source.com",
  "dynamicKeys":[
    {
      "key":"key1",
      "type":"string|number|dateTime",
      "defaultValue":"defaultValue",
      "isEditable":"true|false"
    }
  ],
  "dynamicImageKeys":{
    "passbook":{
      "background":"images/dynamic/d583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "footer":"images/dynamic/e583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "icon":"images/dynamic/f583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "logo":"images/dynamic/g583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "strip":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "thumbnail":"images/dynamic/i583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png"
    }
  }
}

On success the api will respond with the Campaign Name in JSON format:

{
  "name": "campaignName"
}

HTTP Request

PUT https://api-pass.passkit.net/v3/campaigns/{campaignName}

URL Parameters

Parameter Data Type Description
campaignName string This is the reference name that you gave your campaign when you created it.

JSON Body Parameters

The JSON parameters are the same as Create Campaign Method

Retrieve a Campaign

Retrieve a Campaign

curl https://api-pass.passkit.net/v3/campaigns/campaignName
  -X GET
  -H "Authorization:PKAuth json_web_token"

Example of server response:

{
  "index":"ABCDEF",
  "name":"campaignName",
  "passbookCertId":"Poxgb4dEJa",
  "status":"ACTIVE",
  "startDate":"2016-01-01T00:00:00Z",
  "endDate":"2018-01-01T00:00:00Z",
  "googleServiceAccount":"myGoogleServiceAccount@developer.gserviceaccount.com",
  "googleIssuerId":"111111111111111",
  "maxIssue":0,
  "meta":{
    "myKey":123,
    "myKey2":"myData"
  },
  "callbackUrl":{
    "onIssueCallbackUrl":"https://passkit.com/createhook",
    "onUpdateCallbackUrl":"https://passkit.com/updatehook",
    "onRegisterCallbackUrl":"https://passkit.com/registerhook",
    "onDeregisterCallbackUrl":"https://passkit.com/deregisterhook"
  },
  "hookEndpoint":"https://your-data-source.com",
  "dynamicKeys":[
    {
      "key":"key1",
      "type":"string|number|dateTime",
      "defaultValue":"defaultValue",
      "isEditable":"true|false"
    }
  ],
  "dynamicImageKeys":{
    "passbook":{
      "background":"images/dynamic/d583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "footer":"images/dynamic/e583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "icon":"images/dynamic/f583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "logo":"images/dynamic/g583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "strip":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
      "thumbnail":"images/dynamic/i583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png"
    }
  }
}

HTTP Request

GET https://api-pass.passkit.net/v3/campaigns/{campaignName}

URL Parameters

Parameter Data Type Description
campaignName string This is the reference name that you gave your campaign when you created it.

JSON Response

Parameter Data Type Description
index string This is the index reference of your campaign.
name string This is the reference name that you gave your campaign when you created it.
passbookCertId string This is the Certificate ID of the certificate you chose for this campaign, you can check the specific certificate details with the retrieve certificate endpoint.
status string The value must be either ACTIVE, FROZEN, or INVALID. Default is ACTIVE.

The campaign status controls whether passes can be issued or not.
ACTIVE - Enables passes to be issued.
FROZEN - Passes cannot be issued, existing passes are not affected and this value can be changed back to ACTIVE.
INVALID - Passes cannot be issued and all existing passes will be set to invalid. Once the INVALID value is set, it cannot be changed.
startDate ISO8601 datetime The campaign start date. Passes cannot be issued before this time and date. Although this is a required parameter, you can always set the start date to be in the past.
endDate ISO8601 datetime The campaign end date. Passes cannot be issued after this date and time, and all existing passes will be set to voided.
googleServiceAccount string Google service account name. This is a prerequisite of enabling Android Pay on a campaign. This value cannot be changed after the value is set
googleIssuerId string A Google issuer ID in Android Pay Merchant Center. This is a prerequisite of enabling Android Pay on a campaign. This value cannot be changed after the value is set
hookEndpoint string The API pulls the data from the URL during pass creation or update and the endpoint. The connection has to be SSL enabled (https). For more detail of enabling this functionality. Please contact us
dynamicKeys an array of Dynamic Keys You can define what kind of information you want to collect from the end-user during the pass issue process. Once this value is specified, the end-user will be redirected to a landing page containing a web form which is used to collect user information during the pass issue process. For example, specifying email as a key will enable the landing page to show a web form field to collect the user’s email address. This data is stored in a field called dynamicData which held in the pass record when a pass is successfully issued. For more details regarding pass records, please see pass JSON.

You can see a live web form demo here
dynamicImageKeys JSON object A list of flags to control images in the pass. Please see Dynamic Image Keys
createdAt ISO8601 datetime This is when your campaign was created.
updatedAt ISO8601 datetime This is when your campaign was last updated.
meta JSON Object Metadata to store in campaign level. This data is invisiable to users.
whiteLabel WhiteLabelObject This is used to customise the campaign landing page. At the moment this feature is only available via a custom implementation. Please contact us with any enquiries.
maxIssue integer This is the maximum number of passes that can be issued within the campaign and can be used to limit the issued passes to a specific amount. Setting the value to 0 will allow an unlimited number off passes that can be issued for the campaign. Default is set at 0.
issued integer This is total number of passes that have currently been issued for this campaign.
callbackUrl object An object to define event webhooks for pass activities. We will send a POST request to the URL defined in the object. Please see the detail here

onIssueCallbackUrl - An event will fire when a pass is created.
onUpdateCallbackUrl - An event will fire when a pass is updated
onRegisterCallbackUrl - An event will fire when a pass is installed on the Phone
onDeregisterCallbackUrl - An event will fire when a pass is uninstalled the on the Phone (only available for iOS, Pass2U and mWallet App)

Retrieve all Campaigns

Retrieve all Campaigns

curl https://api-pass.passkit.net/v3/campaigns
  -X GET
  -H "Authorization:PKAuth json_web_token"

Example of server response:

[
  {
    "index":"OABd6Q4X",
    "name":"campaignName",
    "passbookCertId":"Poxgb4dEJa",
    "status":"ACTIVE",
    "startDate":"2016-01-01T00:00:00Z",
    "endDate":"2017-01-01T00:00:00Z",
    "createdAt":"2016-03-09T06:31:02.792548789Z",
    "updatedAt":"2016-03-09T07:10:49.350777006Z",
    "displayName":"Campaign Name",
    "description":"Campaign Description",
    "whiteLabel":{},
    "maxIssue":0,
    "issued":0,
    "meta":{
       "myKey":123,
       "myKey2":"myData"
    },
    "callbackUrl":{
       "onIssueCallbackUrl":"https://passkit.com/createhook",
       "onUpdateCallbackUrl":"https://passkit.com/updatehook",
       "onRegisterCallbackUrl":"https://passkit.com/registerhook",
       "onDeregisterCallbackUrl":"https://passkit.com/deregisterhook"
    }
  },
  {
    "index":"OABd6Q4X",
    "name":"campaignName2",
    "passbookCertId":"Poxgb4dEJa",
    "status":"ACTIVE",
    "startDate":"2016-01-01T00:00:00Z",
    "endDate":"2017-01-01T00:00:00Z",
    "createdAt":"2016-03-09T06:31:02.792548789Z",
    "updatedAt":"2016-03-09T07:10:49.350777006Z",
    "displayName":"Second Campaign Name",
    "description":"Second Campaign Description",
    "whiteLabel":{},
    "maxIssue":0,
    "issued":0
  }
]

HTTP Request

GET https://api-pass.passkit.net/v3/campaigns

This endpoint will return an array of all of your available campaigns. The structure of each array entry is the same as for a single campaign.

Templates

Template is a data model to store the appearence/style of the pass (e.g. color, images, layout, etc.). Unlike v2 endpoint, you can now create a template record without having a campaign.

Make Your Pass Dynamic

Pass issuers often need to offer passes where the data contained in the pass is unique for a particular pass, and which can be updated only for that one pass. This can be demonstrated with stored value passes, ticketing details and membership details. Please see below for details on enabling dynamic data in your pass.

  1. Dynamic Placeholder
  2. User Editable or not

1) Dynamic Placeholder

Example of using dynamic placeholder

{
  "passbook":{
    "header":[
      {
        "defaultLabel":"Points",
        "defaultValue":"#{memberPoints}"
      }
    ]
  }
}

We provide two placeholders that can define dynamic data, they are ${data_key} and #{data_key} (please see section 2 for distinction).

You can add these two placeholders in your template record (e.g text or beacon messages) and our API will loop through the object dynamicData in each pass record replacing all the placeholders in the template one by one. Please see the example in the right column.

You can combine static text with dymamic placeholder as well.

2) User Editable or Not

Dynamic placeholders are classified into two categories and differ slightly to allow identification. One placeholder allows the user add data (for example, adding their name via a web form), and the other prevents the user from adding data, but the field remains dynamic (for example, stored value). These are the standard placeholders used by v3 API, using your own placeholders could cause issues with future v3 API releases.

Dynamic Image Keys

This enables the images on the pass to dynamic. You can use these keys to allow the images to be changed at an individual or specific pass level, and allow users to upload their own images from the pass issue web form. For example, you may want your customers to be able to upload their own profile image to be used on a membership pass.

You can find a live demo here

Dynamic Image Key - Apple Wallet (Passbook)

Apple Wallet (Passbook) images settings MUST be contained inside an object key called “passbook”. There are 5 valid keys for this object, background, footer, logo, strip and thumbnail. For further details regarding images positions, please see Apple Wallet Image Position

Example json:

{
  "passbook":{
    "background":{
      "isDynamic":false,
      "isEditable":false
    },
    "footer":{
      "isDynamic":false,
      "isEditable":false
    },
    "logo":{
      "isDynamic":false,
      "isEditable":false
    },
    "strip":{
      "isDynamic":false,
      "isEditable":false
    },
    "thumbnail":{
      "isDynamic":false,
      "isEditable":false
    }
  }
}
Parameter Type Description
isDynamic bool This enables the image as dynamic. This is achieved by allowing an image ID stored in the pass record to override the default image ID stored in the template record. If set to true, the image of the pass record will always override the template default image. Set to false, the default image ID set in the template will be used.
isEditable bool This enables the user to upload their own image to be used on the pass using the web form. Set as true the user will be directed to a web form to upload an image before the pass is issued. Set at false, the image upload option will not display on the web form. Default is false.

You can find a live demo here

Create a Template

Create a Template

curl https://api-pass.passkit.net/v3/templates
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Example payload

{
  "name":"templateName",
  "language":"en",
  "locations":[
    {
      "name":"name of the location",
      "alt":0,
      "lat":22.22222222,
      "lon":114.11111111,
      "message":"message to display",
      "androidPayMeta":{
        "locationName":"location name in Android Pay",
        "phoneNumber":"phone number of the location in Android Pay"
      },
      "isAppleWalletEnabled":"true|false",
      "isAndroidPayEnabled":"true|false"
    }
  ],
  "meta":{
    "key1":123,
    "key2":"value"
  },
  "passbook":{
    "type":"generic",
    "orgName":"Organisation Name",
    "desc":"Basic description of the template.",
    "assoStoreId":[
      967907684
    ],
    "bgColor":"#FFFFFF",
    "labelColor":"#000000",
    "fgColor":"#AAAAAA",
    "iconFile":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
    "logoFile":"images/dynamic/d583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "stripFile":"images/dynamic/e583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "footerFile":"images/dynamic/f583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "thumbFile":"images/dynamic/g583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "bgFile":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "beacons":[
      {
        "name":"Humman readable text",
        "major":0,
        "minor":0,
        "uuid":"f3cb720c-56a4-43ec-bbce-b302a12de06a",
        "relevantText":"message want to display"
      }
    ],
    "header":[
      {
        "changeMsg":"Your new point balance is %@",
        "defaultLabel":"Points",
        "defaultValue":"#{memberPoints}",
        "textAlign":"right",
        "format":{
          "type":"number",
          "numberFormat":"decimal"
        }
      }
    ],
    "secondary":[
      {
        "defaultValue":"Hello ${memberName}",
        "textAlign":"left",
        "format":{
          "type":"text"
        }
      }
    ],
    "back":[
      {
        "defaultValue":[
          {
            "defaultLabel":"Find us",
            "defaultValue":"contact.example.com",
            "format":{
              "type":"text"
            }
          }
        ]
      },
      {
        "dynamicBackfieldKey":"key1",
        "defaultValue":[
          {
            "defaultLabel":"label",
            "defaultValue":"value",
            "format":{
              "type":"text"
            }
          }
        ]
      },
      {
        "defaultValue":[
          {
            "defaultLabel":"label",
            "defaultValue":"valye",
            "format":{
              "type":"text"
            }
          }
        ]
      }
    ]
  },
  "passbookLang":{
    "fr":{
      "text":{
        "Hello":"Bonjour"
      }
    }
  },
   "androidPay":{
    "type":"gift|offer|loyalty",
    "issuerName":"Issuer name",
    "homepageUri":{
      "uri":"https://passkit.com",
      "description":"description"
    },
    "wordMark":{
      "imageSource":{
        "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
        "description":"description"
      }
    },
    "heroImage":{
      "imageSource":{
        "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
        "description":"description"
      }
    },
    "hexBackgroundColor":"#ffffff",
    "barcode":{
      "altText":"message",
      "altTextOption":"message|pid",
      "format":"aztec|code128|code39|dataMatrix|pdf417|qrCode|textOnly",
      "message":"message",
      "messageOption":"message|pid"
    },
    "messages":[
      {
        "id":"1",
        "header":"label",
        "body":"value",
        "displayInterval":{
          "start":{
            "date":"2017-05-24T00:00:00Z"
          },
          "end":{
            "date":"2017-05-24T00:00:00Z"
          }
        },
        "actionUri":{
          "uri":"http://your-url.com",
          "description":"description"
        }
      }
    ],
    "infoModulesData":{
      "labelValueRows":[
        {
          "columns":[
            {
              "label":"label",
              "value":"value"
            }
          ]
        }
      ],
      "showLastUpdateTime":true
    },
    "imageModulesData":[
      {
        "mainImage":{
          "imageSource":{
            "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
            "description":"description"
          }
        }
      }
    ],
    "textModulesData":[
      {
        "dynamicBackfieldKey":"key1",
        "defaultValue":[
          {
            "header":"label",
            "body":"value"
          }
        ]
      }
    ],
    "linkModulesData":{
      "uris":[
        {
          "uri":"https://passkit.com",
          "description":"passkit link"
        }
      ]
    },
    "giftClass":{
      "programLogo":{
        "imageSource":{
          "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
          "description":"description"
        }
      },
      "allowBarcodeRedemption":"true|false",
      "eventNumberLabel":"eventNumberLabel",
      "eventNumberValue":"eventNumberValue",
      "pinLabel":"pinLabel",
      "pinValue":"pin value",
      "cardNumberValue":"card number",
      "balance":{
        "micros":1000,
        "currencyCode":"currencyCode"
      }
    },
    "offerClass":{
      "title":"offer title",
      "redemptionChannel":"both|instore|online|temporaryPriceReduction",
      "provider":"PassKit Provider",
      "titleImage":{
         "imageSource":{
          "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
          "description":"description"
        }
      },
      "details":"details",
      "finePrint":"finePrint",
      "helpUri":{
        "uri":"https://passkit.com",
        "description":"description"
      }
    },
    "loyaltyClass":{
      "programName":"programName",
      "programLogo":{
        "imageSource":{
          "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
          "description":"description"
        }
      },
      "accountNameLabel":"accountNameLabel",
      "accountNameValue":"accountNameValue",
      "accountIdLabel":"accountIdLabel",
      "accountIdValue":"accountIdValue",
      "rewardsTierLabel":"rewardsTierLabel",
      "rewardsTier":"rewardsTier",
      "loyaltyPoints":{
        "label":"label",
        "pointsType":"pointsType",
        "balanceValue":2000,
        "balanceType":"string|int|double|money",
        "currencyCode":"currencyCode"
      }
    }
  }
}

A successful call will result with a response including the Template Name in JSON format:

{
  "name": "templateName"
}

HTTP Request

POST https://api-pass.passkit.net/v3/templates

JSON Body Parameters

Parameter Data Type Description
name string Required. A unique identifier for your templates. The name must be alpha-numeric and cannot contain spaces. Please note, this cannot be changed after the template is created.
campaignName string DEPRECATED
language string Required. This defines the template’s default language. For a list of supported languages please see the Languages List.
startDate string DEPRECATED
endDate string DEPRECATED
status string DEPRECATED
maxIssue integer DEPRECATED
timezone float DEPRECATED
meta object Metadata to store in template level. This data is invisiable to users.
dynamicKeys an array of object DEPRECATED
dynamicImageKeys object A list of flags to control images in the pass. Please see Dynamic Image Keys
passbook
(required)
Apple Wallet Template This holds the design features of this template, for example, pass colours and images. Please see the Apple Wallet Template section for more detail.
passbook Apple Wallet Template This holds the design features of this template, for example, pass colours and images. Please see the Apple Wallet Template section for more detail.
passbookRedeem Apple Wallet template When you use the Redeem Method or the Update Pass Method to redeem a pass, the design features of the redeemed template will be applied. For more details regarding the use of the redeem pass method, please see Redeem Pass Method

This option provides an efficient way to apply template design changes after redemption, rather than updating each pass individually via the Update Pass Method.
passbookLang Passbook Language Object This field to defines the different language translations the template supports, please see multiple languages for more information. Please see the Language (Apple Wallet) for details on the structure used and a basic example in the example json side section.
passbookLangRedeem Passbook Language Object This field to defines the different language translations the template supports for the redeemed version of your pass, please see multiple languages for more information. The Passbook Language Section provides details on the structure, which is the same as for the passbookLang parameter.
androidPay Android Pay Template This holds the design features of this template, for example, pass colours and images. Please see the Android Pay Template section for more detail.
androidPayRedeem Android Pay Template When you use the Redeem Method or the Update Pass Method to redeem a pass, the design features of the redeemed template will be applied. For more details regarding the use of the redeem pass method, please see Redeem Pass Method

This option provides an efficient way to apply template design changes after redemption, rather than updating each pass individually via the Update Pass Method.

Update a Template

Update a Template

curl https://api-pass.passkit.net/v3/templates/{templateName}
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

On success the api will respond with the Template Name in JSON format:

{
  "name": "templateName"
}

This endpoint is used to update all the template attributes. Changes to the template made using this endpoint are not immediately updated on all passes. To send a template push update please use the Push Template Method

HTTP Request

PUT https://api-pass.passkit.net/v3/templates/{templateName}

URL Parameters

Parameter Data Type Description
templateName string This is the reference name that you gave your template when you created it.

JSON Body Parameters

The JSON parameters are the same as Create Template Method

Retrieve a Template

Retrieve a Template

curl https://api-pass.passkit.net/v3/templates/my_template_name
  -X GET
  -H "Authorization:PKAuth json_web_token"

Response example

{
  "name":"templateName",
  "language":"en",
  "createdAt":"2017-03-01T03:43:17.918425687Z",
  "updatedAt":"2017-03-01T03:43:17.918426641Z",
  "locations":[
    {
      "name":"name of the location",
      "alt":0,
      "lat":22.22222222,
      "lon":114.11111111,
      "message":"message to display",
      "androidPayMeta":{
        "locationName":"location name in Android Pay",
        "phoneNumber":"phone number of the location in Android Pay"
      },
      "isAppleWalletEnabled":"true|false",
      "isAndroidPayEnabled":"true|false"
    }
  ],
  "meta":{
    "key1":123,
    "key2":"value"
  },
  "passbook":{
    "type":"generic",
    "orgName":"Organisation Name",
    "desc":"Basic description of the template.",
    "assoStoreId":[
      967907684
    ],
    "bgColor":"#FFFFFF",
    "labelColor":"#000000",
    "fgColor":"#AAAAAA",
    "iconFile":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
    "logoFile":"images/dynamic/d583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "stripFile":"images/dynamic/e583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "footerFile":"images/dynamic/f583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "thumbFile":"images/dynamic/g583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "bgFile":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
    "beacons":[
      {
        "name":"Humman readable text",
        "major":0,
        "minor":0,
        "uuid":"f3cb720c-56a4-43ec-bbce-b302a12de06a",
        "relevantText":"message want to display"
      }
    ],
    "header":[
      {
        "changeMsg":"Your new point balance is %@",
        "defaultLabel":"Points",
        "defaultValue":"#{memberPoints}",
        "textAlign":"right",
        "format":{
          "type":"number",
          "numberFormat":"decimal"
        }
      }
    ],
    "secondary":[
      {
        "defaultValue":"Hello ${memberName}",
        "textAlign":"left",
        "format":{
          "type":"text"
        }
      }
    ],
    "back":[
      {
        "defaultValue":[
          {
            "defaultLabel":"Find us",
            "defaultValue":"contact.example.com",
            "format":{
              "type":"text"
            }
          }
        ]
      },
      {
        "dynamicBackfieldKey":"key1",
        "defaultValue":[
          {
            "defaultLabel":"label",
            "defaultValue":"value",
            "format":{
              "type":"text"
            }
          }
        ]
      },
      {
        "defaultValue":[
          {
            "defaultLabel":"label",
            "defaultValue":"valye",
            "format":{
              "type":"text"
            }
          }
        ]
      }
    ]
  },
  "passbookLang":{
    "fr":{
      "text":{
        "Hello":"Bonjour"
      }
    }
  },
   "androidPay":{
    "type":"gift|offer|loyalty",
    "issuerName":"Issuer name",
    "homepageUri":{
      "uri":"https://passkit.com",
      "description":"description"
    },
    "wordMark":{
      "imageSource":{
        "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
        "description":"description"
      }
    },
    "heroImage":{
      "imageSource":{
        "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
        "description":"description"
      }
    },
    "hexBackgroundColor":"#ffffff",
    "barcode":{
      "altText":"message",
      "altTextOption":"message|pid",
      "format":"aztec|code128|code39|dataMatrix|pdf417|qrCode|textOnly",
      "message":"message",
      "messageOption":"message|pid"
    },
    "messages":[
      {
        "id":"1",
        "header":"label",
        "body":"value",
        "displayInterval":{
          "start":{
            "date":"2017-05-24T00:00:00Z"
          },
          "end":{
            "date":"2017-05-24T00:00:00Z"
          }
        },
        "actionUri":{
          "uri":"http://your-url.com",
          "description":"description"
        }
      }
    ],
    "infoModulesData":{
      "labelValueRows":[
        {
          "columns":[
            {
              "label":"label",
              "value":"value"
            }
          ]
        }
      ],
      "showLastUpdateTime":true
    },
    "imageModulesData":[
      {
        "mainImage":{
          "imageSource":{
            "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
            "description":"description"
          }
        }
      }
    ],
    "textModulesData":[
      {
        "dynamicBackfieldKey":"key1",
        "defaultValue":[
          {
            "header":"label",
            "body":"value"
          }
        ]
      }
    ],
    "linkModulesData":{
      "uris":[
        {
          "uri":"https://passkit.com",
          "description":"passkit link"
        }
      ]
    },
    "giftClass":{
      "programLogo":{
        "imageSource":{
          "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
          "description":"description"
        }
      },
      "allowBarcodeRedemption":"true|false",
      "eventNumberLabel":"eventNumberLabel",
      "eventNumberValue":"eventNumberValue",
      "pinLabel":"pinLabel",
      "pinValue":"pin value",
      "cardNumberValue":"card number",
      "balance":{
        "micros":1000,
        "currencyCode":"currencyCode"
      }
    },
    "offerClass":{
      "title":"offer title",
      "redemptionChannel":"both|instore|online|temporaryPriceReduction",
      "provider":"PassKit Provider",
      "titleImage":{
         "imageSource":{
          "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
          "description":"description"
        }
      },
      "details":"details",
      "finePrint":"finePrint",
      "helpUri":{
        "uri":"https://passkit.com",
        "description":"description"
      }
    },
    "loyaltyClass":{
      "programName":"programName",
      "programLogo":{
        "imageSource":{
          "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
          "description":"description"
        }
      },
      "accountNameLabel":"accountNameLabel",
      "accountNameValue":"accountNameValue",
      "accountIdLabel":"accountIdLabel",
      "accountIdValue":"accountIdValue",
      "rewardsTierLabel":"rewardsTierLabel",
      "rewardsTier":"rewardsTier",
      "loyaltyPoints":{
        "label":"label",
        "pointsType":"pointsType",
        "balanceValue":2000,
        "balanceType":"string|int|double|money",
        "currencyCode":"currencyCode"
      }
    }
  }
}

HTTP Request

GET https://api-pass.passkit.net/v3/templates/{templateName}

To retrieve a specific template you need to send a GET request to the server with the template name. The JSON body response will contain the whole template, comprehensive of every value and attribute related to it.

In the column on the right there is an example of a retrieved pass in English and German, you can identify some features such as the footer and icon image, as well as how many devices have that specific template.

Retrieve all Templates

Retrieve all Templates (by Campaign Name)

HTTP Request

GET https://api-pass.passkit.net/v3/templates

This endpoint will return an array of all templates. The structure of each array entry is the same as for a single template.

Push Updates

To send a push update to all passes after making changes to the template you can do so using this endpoint.

Push Update

curl https://api-pass.passkit.net/v3/templates/templateName/push
  -X PUT
  -H "Authorization:PKAuth json_web_token"

On success the api will respond with the Template Name in JSON format:

{
  "name": "templateName"
}

HTTP Request

PUT https://api-pass.passkit.net/v3/templates/{templateName}/push

JSON Body Parameters

Empty payload

Backfield Group

Backfield groups allow you to define a set of backfields that can be replaced by dynamic backfields on the pass level. This concept applys to both Apple Wallet and Android Pay. Please see the following diagram:

passbook backfield diagram

The JSON for Apple Wallet backfield:

{
  "dynamicBackfieldKey":"custom-promotions",
  "defaultValues":[
    {
      "itemName":"backfield1",
      "attributedValue":"<a href=\"https://passkit.com\">PassKit</a>",
      "changeMsg":"Value Changed",
      "defaultLabel":"Default Promotion A",
      "defaultValue":"Default Promotion A Value",
      "format":{
        "type":"text",
        "dateFormat":"short",
        "timeFormat":"long",
        "ignoreTimezone":true,
        "isRelative":false,
        "currencyCode":"",
        "numberFormat":"decimal"
      },
      "detectorType":[
        "link"
      ]
    },
    {
      "itemName":"backfield2",
      "defaultLabel":"Default Promotion B",
      "defaultValue":"Default Promotion B Value",
      "format":{
        "type":"text",
        "dateFormat":"short",
        "timeFormat":"long",
        "ignoreTimezone":true,
        "isRelative":false,
        "currencyCode":"",
        "numberFormat":"decimal"
      }
    }
  ]
}

The pass will combine the template and pass record to create a pass. You can see an example here.

If you want to provide a custom list of back fields on each user’s pass (for example, a personalised list of promotions) then you can set the dynamicBackfieldKey for any group of backfields.

To see how backfields and backfield groups work you can use this helper tool to try out different configurations.

Parameter Data Type Description
defaultValues an array of Backfields (Apple Wallet)
or
an array of Text Module Object (Android Pay)
Required. These are the default values for the backfield group . If no dynamicBackfieldKey is provided then these backfields will always be displayed. Fields will appear in order on the back of the pass.
dynamicBackfieldKey string An optional string to provide the key name for dynamic backfields. If there is a matching key on the user’s pass, the backfields on the pass will be used instead of the defaultValue backfields for this backfield group.

Apple Wallet Template

Our API follows the original Apple structure closely, sometimes it may be necessary to refer back to Apple’s doccumentation to understand the true purpose of an optional field, as they are not always immediately obvious. We have left our API as open as possible to allow the full flexibility that Apple can provide with their passes.

Overall Structure

The overall json:

{
  "type":"general",
  "orgName":"Example Company",
  "desc":"Description of the template",
  "assoStoreId":[
    284882215
  ],
  "appLaunchUrl":"fb://profile/331998086879963",
  "bgColor":"#500000",
  "labelColor":"#200000",
  "fgColor":"#000000",
  "iconFile":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
  "logoFile":"images/dynamic/d583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
  "stripFile":"images/dynamic/e583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
  "footerFile":"images/dynamic/f583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
  "thumbFile":"images/dynamic/g583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
  "bgFile":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
  "logoText":"My Company",
  "transitType":"air",
  "header":[
    {
      "itemName":"Balance",
      "changeMsg":"You got %@ HKD",
      "defaultLabel":"Balance",
      "defaultValue":"#{balance=0}",
      "textAlign":"left",
      "format":{
        "type":"number",
        "numberFormat":"decimal",
        "currencyCode":"HKD"
      }
    }
  ],
  "primary":[
    {
      "defaultLabel":"Points",
      "defaultValue":"#{points=0}",
      "textAlign":"left",
      "format":{
        "type":"number",
        "numberFormat":"decimal"
      }
    },
    {
      "defaultLabel":"Name",
      "defaultValue":"${name}",
      "format":{
        "type":"string"
      }
    }
  ],
  "auxiliary":[
    {
      "defaultLabel":"Offer",
      "defaultValue":"Buy one get one free",
      "format":{
        "type":"string"
      }
    },
    {
      "defaultLabel":"Expiry Date",
      "defaultValue":"2019-05-26T05:38:20+08:00",
      "format":{
        "type":"date",
        "dateFormat":"short"
      }
    }
  ],
  "secondary":[

  ],
  "back":[

  ],
  "beacons":[
    {
      "name":"name",  
      "major":0,
      "minor":0,
      "uuid":"19d5f76a-fd04-5aa3-b16e-e93277163af6",
      "relevantText":"Welcome to PassKit"
    }
  ],
  "maxDist":10,
  "relevantDate":"2019-08-01T00:00:00Z",
  "barcode":{
    "altText":"Text below the barcode",
    "format":"pdf417",
    "message":"BarcodeText",
    "messageEncoding":"UTF-8"
  },
  "nfc":{
    "message":"messageForTerminal",
    "encryptionPublicKey":"L0ngRand0m3ncrypt1onK3y"
  } 
}

The example json shows all the possible fields that can be used when creating a pass, and example data for most fields. You will not need to use all these fields, however we have provided a list below with descriptions for your reference. The list follows the json object from top to bottom.

Parameter Data Type Description
type string Required. Valid options for this parameter are: boardingPass, coupon, storeCard, generic, eventTicket
desc string Required. This is a a brief description of the template, it is used by apple for user accessibility.
orgName string This is the name of the company or organisation issuing the pass.
assoStoreId an array of numbers This is used to display and link to an app on the back of the pass. Each number in the array should be an iTunes Adam ID, the pass will ONLY display the first app in the array which is compatible with the current device.
appLaunchUrl string This is used to specify a deep link into the app displayed on the back of the pass (the app is chosen from the assoStoreId). If the app supports deep linking, you can use this url to go to a specific point within the app when it is opened.
bgColor string Hex color string (e.g. #FFFFFF).

RGB object for backward compatible. This field allows you to provide the rgb values for the background colour of the pass. (deprecated)
labelColor string Hex color string (e.g. #FFFFFF).

RGB object for backward compatible. This field allows you to provide the rgb values for the label colour of the pass. (deprecated)
fgColor string Hex color string (e.g. #FFFFFF).

RGB object for backward compatible. This field allows you to provide the rgb values for the foreground colour of the pass. (deprecated)
iconFile string Required. The image path from Upload Image Endpoint.
(e.g. images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png).
logoFile string The image path from Upload Image Endpoint.
(e.g. images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png).
stripFile string The image path from Upload Image Endpoint.
(e.g. images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png).
footerFile string The image path from Upload Image Endpoint.
(e.g. images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png).
thumbFile string The image path from Upload Image Endpoint.
(e.g. images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png).
bgFile string The image path from Upload Image Endpoint.
(e.g. images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png).
logoText string This is the logo text displayed on your template.
transitType string This field is required for boarding passes, it defines which travel mode icon is displayed on the pass. Available values are air, boat, bus, generic, and train. the default value is generic.
header 
primary 
auxiliary 
secondary 
array of Item Fields These four fields contain the text that is displayed on the front of the pass. These fields follow the same format described below in the Item Field. The primary field(s) do not have the text align attribute.
back  an array of Backfield Groups These fields contain the text that is displayed in the pass backfields. Adresses and phone numbers are automatically made tapable and the href attribute can be be used with links.
beacons an array of Beacon Objects Beacons allow you to display subtle messages to your users when they are in close proximity. Ideally used in places where a user may want to access the pass. For more information regarding beacons and their use, please see our GemTots Page or download our guide to iBeacon.
locations an array of objects DEPRECATED.
maxDist number Maximum distance in meters from a relevant latitude and longitude that the releventText will be displayed. Apple will use the default max range (either 100m or 1000m depending on the Pass Type) if it is less than the value set here.
relevantDate string ISO8601 datetime. This allows you to set a date and time when the pass location notification is relevant. For example an event ticket should show on the lockscreen at the time of the event for it to be relevant. The use of this parameter is dependent on the Pass Type being used.
barcode Barcode Object (Apple Wallet)
nfc NFC Object Note that you need to have a special NFC certificate from Apple in order to enable this feature. Contact us directly with any enquiries regarding custom solutions involving NFC.

Item Field

The json for an item field (header, auxiliary, secondary, primary):

{
    "itemName": "secondaryField1",
    "attributedValue": "<a href=\"https://passkit.com\">PassKit</a>",
    "changeMsg": "Value Changed",
    "defaultLabel": "Item Label",
    "defaultValue": "Item Value",
    "textAlign": "left",
    "format": {
        "type": "text",
        "dateFormat": "short",
        "timeFormat": "long",
        "ignoreTimezone": true,
        "isRelative": false,
        "currencyCode": "HKD",
        "numberFormat": "decimal"
    }
}

Please refer to the Apple Documentation for full details regarding the Apple Wallet template fields. This will help clarify when certain fields should be used.

Parameter Data Type Description
itemName string This is a unique identifier for a template field. This value must not be reused in the same template. If you do not provide an itemName, we will automatically generate one for you.
defaultLabel string Required. This is the field label that is displayed on the pass.
defaultValue string, number or ISO8601 datetime Required. This is the field value displayed on the pass, it must match the field format selected for that field.
attributedValue string The attributed value allows you to enter html links. It will override the default value. The format only allows the <a href=""></a> tag with a href attribute.
changeMsg string This message will be displayed as a notification when this field is updated. If %@ is used in the change message it will be replaced with the new field value when the message is displayed.

Please make sure it contains %@ here. Otherwise, the latest value will not be displayed on the lockscreen.
textAlign string This field sets the alignment of the field, the possible settings are left, center, right, and natural. This field is not used in the primary field(s). Default is left.
format Format Object (Apple Wallet) Required. Specify the format the of item field.

Format Object (Apple Wallet)

Parameter Data Type Description
type string Required. This is the field type.

The possible values are text, number, currency, date, or dateTime
dateFormat string This used when the date, or dateTime field type is selected.

The value can be none, short, medium, long, or full which will affect the length of the date displayed.
timeFormat string This used when the date, or dateTime field type is selected.

The value can be none, short, medium, long, or full which will affect the length of the time section displayed.
ignoreTimezone boolean This is used when the date, or dateTime field type is selected.

If true, the time will display in the given time zone, not the user’s time zone.
isRelative boolean This is used when the date, or dateTime field type is selected.

If true, the time will display as a relative date, otherwise the date is displayed as an absolute date.
currencyCode string ISO 4217 currency code. This is only used when the currency field type is selected, the code must be in the list of currency codes
numberFormat string This is used when the number field type is selected.

The value can be decimal, percent, scientific, or spellout.

Backfield

The json for a template backfield:

{
  "itemName":"backfield1",
  "attributedValue":"<a href=\"https://passkit.com\">PassKit</a>",
  "changeMsg":"Value Changed",
  "defaultLabel":"Item Label",
  "defaultValue":"Item Value",
  "format":{
    "type":"text",
    "dateFormat":"short",
    "timeFormat":"long",
    "ignoreTimezone":true,
    "isRelative":false,
    "currencyCode":"HKD",
    "numberFormat":"decimal"
  },
  "detectorType":[
    "phone",
    "link",
    "address",
    "event"
  ]
}

A template backfield is similar to the fields on the front of the pass and they follow a similar structure to Apple’s Wallet specification, for further details please read the Apple Documentation regarding template fields.

Parameter Data Type Description
itemName string This is a unique identifier for a template field. This value must not be reused in the same template. If you do not provide an itemName, we will automatically generate one for you.
defaultLabel string Required. This is the field label that is displayed on the pass.
defaultValue string, number or ISO8601 datetime Required. This is the field value displayed on the pass, it must match the field format selected for that field.
attributedValue string The attributed value allows you to enter html links. It will override the default value. The format only allows the <a href=""></a> tag with a href attribute.
changeMsg string This message will be displayed as a notification when this field is updated. If %@ is used in the change message it will be replaced with the new field value when the message is displayed.
textAlign string This field sets the alignment of the field, the possible settings are left, center, right, and natural. This field is not used in the primary field(s). Default is left.
format Format Object (Apple Wallet) Required. Specify the format the of item field.

Beacon Object

Parameter Data Type Description
name string Name of the beacon.
uuid string Required. The beacon UUID.
major number Required. This is the major id of the beacon. Valid range is 0 - 65535.
minor number Required. This is the minor id of the beacon. Valid range is 0 - 65535.
relevantText string Required. This is the message is displayed on the device lockscreen when the device is in proximity to a recognised beacon.

Barcode Object (Apple Wallet)

Parameter Data Type Description
format string Required. The format of the barcode.

Available values are aztec, code128, pdf417 and qr.
message string Required. Encoded barcode content.
altText string Human-readable text content.
messageEncoding string Required. This is the text encoding for the barcode, any IANA character set name can be used. UTF-8 is prefered.

NFC Object

Parameter Data Type Description
message string Required. This is the data that is sent to the NFC terminal.
encryptionPublicKey string Required. This is the public encryption key used to ensure the NFC transaction is secure.

Image Types / Layout

The exact specifications relating to using images in Apple wallet can be found in their developer documentation. The list of image types that can be uploaded is as follows:

Image Type Position on the Pass Other Notes Dimensions
IconFile Displayed on the lock screen as part of a notification, and apps like “Mail” when showing that a pass is attached 87 x 87
LogoFile Displayed in the top left corner of the Pass The maximum width is 480 pixels. In most cases it should be narrower. Please note, if you use the full pixel width you may not have room to display the Logo Text or Header Fields. 480 x 150
StripFile Displayed behind the Primary Fields On iPhone 6 and 6 Plus, the space is 1125 x 294 for event tickets, 1125 x 432 for gift cards and coupons, and 1125 x 369 in all other cases.
On earlier models, the space is 640 x 168 for event tickets, 960 x 330 for square barcodes on devices with 3.5 inch screens, and 960 x 369 in all other cases.
FooterFile Displayed directly bove the barcode Available when using the Transport Pass Type 858 x 45
ThumbFile Displayed next to the fields on the front right of the pass The aspect ratio should be in the range of 2:3 to 3:2, otherwise the image is cropped Up to 270 x 270
BgFile Behind the entire front of the pass Available when using Event Pass Type. The image is cropped slightly on all sides and blurred 360 x 440

Pass Layout (Apple Wallet)

Boarding Pass: Layout

Coupon: Layout

Event Ticket: Layout

Generic: Layout

Store Card: Layout

Language

The basic layout in json:

    {
        "lang1": {
            "text": {
                "Original Text1": "Language1 Translated Text1",
                "Original Text2": "Language1 Translated Text2"
            }
        },
        "lang2": {
            "text": {
                "Original Text1": "Language2 Translated Text1",
                "Original Text2": "Language2 Translated Text2"
            }
        }
    }

The basic layout of the passbook language object is shown on the right. The variables in the example are as follows:

Parameter Type Description
lang string Required. lang1 and lang2 in the example should be chosen from the list of supported languages. You can use as many languages as you need as long as they are supported.
Origina Text string Required. The “Original Text” variables should be the text from your original template that you want to translate. They must match the text in the original template exactly.
Translated Text string Required. The “Translated Text” should be translated text from the “Original Text” in the other language you have chosen. The text will be used to exactly replace the corresponding original text when the device is set to that language.

Android Pay Template

Our API follows the original Android Pay structure closely, sometimes it may be necessary to refer back to Android Pay’s doccumentation to understand the true purpose of an optional field, as they are not always immediately obvious. We have left our API as open as possible to allow the full flexibility that Android Pay can provide with their passes.

Overall Structure

The overall json:

{
    "type":"gift|offer|loyalty",
    "issuerName":"Issuer name",
    "homepageUri":{
      "uri":"https://passkit.com",
      "description":"description"
    },
    "wordMark":{
      "imageSource":{
        "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
        "description":"description"
      }
    },
    "heroImage":{
      "imageSource":{
        "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
        "description":"description"
      }
    },
    "hexBackgroundColor":"#ffffff",
    "barcode":{
      "format":"aztec|code128|code39|dataMatrix|pdf417|qrCode|textOnly",
      "altText":"message",
      "message":"message"
    },
    "messages":[
      {
        "id":"1",
        "header":"label",
        "body":"value",
        "displayInterval":{
          "start":{
            "date":"2017-05-24T00:00:00Z"
          },
          "end":{
            "date":"2017-05-24T00:00:00Z"
          }
        }
      }
    ],
    "infoModulesData":{
      "labelValueRows":[
        {
          "columns":[
            {
              "label":"label",
              "value":"value"
            }
          ]
        }
      ],
      "showLastUpdateTime":true
    },
    "imageModulesData":[
      {
        "mainImage":{
          "imageSource":{
            "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
            "description":"description"
          }
        }
      }
    ],
    "textModulesData":[
      {
        "dynamicBackfieldKey":"key1",
        "defaultValue":[
          {
            "header":"label",
            "body":"value"
          }
        ]
      }
    ],
    "linkModulesData":{
      "uris":[
        {
          "uri":"https://passkit.com",
          "description":"passkit link"
        }
      ]
    },
    "giftClass":{
      "programLogo":{
        "imageSource":{
          "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
          "description":"description"
        }
      },
      "allowBarcodeRedemption":"true|false",
      "eventNumberLabel":"eventNumberLabel",
      "eventNumberValue":"eventNumberValue",
      "pinLabel":"pinLabel",
      "pinValue":"pin value",
      "cardNumberValue":"card number",
      "balance":{
        "micros":1000,
        "currencyCode":"currencyCode"
      }
    },
    "offerClass":{
      "title":"offer title",
      "redemptionChannel":"both|instore|online|temporaryPriceReduction",
      "provider":"PassKit Provider",
      "titleImage":{
         "imageSource":{
          "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
          "description":"description"
        }
      },
      "details":"details",
      "finePrint":"finePrint",
      "helpUri":{
        "uri":"https://passkit.com",
        "description":"description"
      }
    },
    "loyaltyClass":{
      "programName":"programName",
      "programLogo":{
        "imageSource":{
          "uri":"images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png",
          "description":"description"
        }
      },
      "accountNameLabel":"accountNameLabel",
      "accountNameValue":"accountNameValue",
      "accountIdLabel":"accountIdLabel",
      "accountIdValue":"accountIdValue",
      "rewardsTierLabel":"rewardsTierLabel",
      "rewardsTier":"rewardsTier",
      "loyaltyPoints":{
        "label":"label",
        "pointsType":"pointsType",
        "balanceValue":2000,
        "balanceType":"string|int|double|money",
        "currencyCode":"currencyCode"
      }
    }
  }

Top Level Fields

Parameter Data Type Description
type string Required. Android Pay type.

Possible values are gift, offer, and loyalty.
issuerName string Required. Issuer name. For gift type, merchantName is the same as issuer name.
giftClass GiftClass Gift type specific data. Required if the type is gift
offerClass OfferClass Offer type specific data. Required if the type is offer
loyaltyClass LoyaltyClass Loyalty type specific data. Required if the type is loyalty
allowMultipleUsersPerObject boolean Identifies whether multiple users will save the same object referencing this class. If true, a single object (identified by instance id) may be saved by multiple users. If false, the object may only be saved by a single user. Default is false.
homepageUri URI Object The URI of your application’s home page. Populating the URI in this field results in the exact same behavior as populating an URI in linksModuleData (when an object is rendered, a link to the homepage is shown in what would usually be thought of as the linksModuleData section of the object).
heroImage Image Object The hero image of the card. The image will display at 100% width.
wordMark Image Object The issuer wordmark. If defined, appears in place of the issuer name.
hexBackgroundColor string The background color of the card in hex (e.g. “#ffffff”).
barcode Barcode Object (Android Pay) The barcode type and value.
messages an array of Message Object An array of messages displayed in the app. All users of this object will receive its associated messages.
infoModulesData Info Module Object Info module data.
imageModulesData an array of Image Objects Image module data. Not all images may be shown; while there is currently no restriction only one image should be specified.
textModulesData an array of Text Module Object Text module data.
linkModulesData Link Module Object Links module data.

Gift Class

Parameter Data Type Description
programLogo Image Object Required. The logo of the gift card program or company. This logo is displayed in both the details and list views of the app.
allowBarcodeRedemption boolean Determines whether the merchant supports gift card redemption using barcode. If true, app displays a barcode for the gift card on the Gift card details screen. If false, a barcode is not displayed.
eventNumberLabel string The label to display for event number, such as “Target Event #”.
eventNumberValue string The card’s event number, an optional field used by some gift cards.
pinLabel string The label to display for the PIN, such as “4-digit PIN”.
pinValue string The issuer wordmark. If defined, appears in place of the issuer name.
cardNumberValue string The card’s number.
balance Money Object The card’s monetary balance.

Offer Class

Parameter Data Type Description
title string Required. The title of the offer, such as “20% off any t-shirt.” Recommended maximum length is 60 characters to ensure full string is displayed on smaller screens.
redemptionChannel string Required. The redemption channels applicable to this offer.

Possible values are both, instore, online and temporaryPriceReduction.
provider string Required. The offer provider (either the aggregator name or merchant name). Recommended maximum length is 12 characters to ensure full string is displayed on smaller screens.
eventNumberValue string The card’s event number, an optional field used by some gift cards.
titleImage Image Object The title image of the offer. This image is displayed in both the details and list views of the app.
details string The details of the offer.
finePrint string The fine print or terms of the offer, such as “20% off any t-shirt at Adam’s Apparel.”
helpUri URI Object The help link for the offer, such as http://myownpersonaldomain.com/help

Loyalty Class

Parameter Data Type Description
programName string Required. The program name, such as “Adam’s Apparel”. The app may display an ellipsis after the first 20 characters to ensure full string is displayed on smaller screens.
programLogo Image Object Required. The logo of the loyalty program or company. This logo is displayed in both the details and list views of the app.
accountNameLabel string The account name label, such as “Member Name.” Recommended maximum length is 15 characters to ensure full string is displayed on smaller screens.
accountNameValue string The loyalty account holder name, such as “John Smith.” Recommended maximum length is 20 characters to ensure full string is displayed on smaller screens.
accountIdLabel string The account ID label, such as “Member ID.” Recommended maximum length is 15 characters to ensure full string is displayed on smaller screens.
accountIdValue string The loyalty account identifier. Recommended maximum length is 20 characters.
rewardsTierLabel string The rewards tier label, such as “Rewards Tier.” Recommended maximum length is 9 characters to ensure full string is displayed on smaller screens.
rewardsTier string The rewards tier, such as “Gold” or “Platinum.” Recommended maximum length is 7 characters to ensure full string is displayed on smaller screens.
cardNumberValue string The card’s number.
loyaltyPoints Loyalty Point Object The loyalty reward points label, balance, and type.

Loyalty Point Object

Parameter Data Type Description
label string The loyalty points label, such as “Points”. Recommended maximum length is 9 characters.
pointType string The type of loyalty points, such as “points” or “miles.”
balanceValue string or number The value of the balance.
balanceType string Required. The type of the balance. Possible value are string, int, double, money
currencyCode string The currency code, such as “USD” or “EUR.” Required if the balance type is money.

Barcode Object (Android Pay)

Parameter Data Type Description
format string Required. The format of the barcode.

Available values are aztec, code128, code39, dataMatrix, pdf417, qrCode and textOnly.
message string Required. Encoded barcode content.
altText string Human-readable text content.

Message Object

Parameter Data Type Description
id string The ID associated with a message. This field is here to enable ease of management of messages. Notice ID values could possibly duplicate across multiple messages in the same class/instance, and care must be taken to select a reasonable ID for each message.
header string Required. The message header.
body string The message body.
displayInterval object The period of time that the message will be displayed to users. You can define both a startTime and endTime for each message. A message is displayed immediately after a Wallet Object is inserted unless a startTime is set. The message will appear in a list of messages indefinitely if endTime is not provided.
displayInterval.start.date string ISO8601 date format. (e.g. 2017-03-28T00:00:00Z)
displayInterval.end.date string ISO8601 date format. (e.g. 2017-03-28T00:00:00Z)

Info Module Object

Parameter Data Type Description
labelValueRows an array of Label Value Objects Required. A list of collections of labels and values. These will be displayed one after the other in a singular column.
showLastUpdateTime boolean Display the last update time of the object. The value will be automatically pre-populated from the pass last updated time. Default is false.

Label Value Object

Parameter Data Type Description
columns an array of objects Required. A list of collections of labels and values. These will be displayed one after the other in a singular column.
columns[].label string Required. The label for a specific row and column. Recommended maximum is 15 characters for a two-column layout and 30 characters for a one-column layout.
columns[].value string The value for a specific row and column. Recommended maximum is 15 characters for a two-column layout and 30 characters for a one-column layout.

Text Module Object

Parameter Data Type Description
dynamicBackfieldKey string An optional string to provide the key name for dynamic backfields. If there is a matching key on the user’s pass, the backfields on the pass will be used instead of the defaultValue backfields for this backfield group. For more detail, please see Backfield Group.
defaultValue an array of object Required. These are the default values for the backfield group . If no dynamicBackfieldKey is provided then these backfields will always be displayed. Fields will appear in order on the text module data of the pass.
defaultValue[].header string Required. The header of the text module
defaultValue[].body string The body of the text module
Parameter Data Type Description
uris an array of URI Objects Required. An optional string to provide the key name for dynamic backfields. If there is a matching key on the user’s pass, the backfields on the pass will be used instead of the

URI Object

Parameter Data Type Description
uri string Required. URI. (e.g. https://passkit.com)
description string Description of the URI.

Money Object

Parameter Data Type Description
amount number Required. The unit of money amount.
currencyCode string Required. Currency code. (e.g. HKD, USD, etc.)

Image Object

Parameter Data Type Description
imageSource object Required. Image object for Android Pay
imageSource.uri string Required. Image path from Upload Image Endpoint.
(e.g. images/dynamic/h583b523fb63c7d538b4b2a63fs6fa0a20ddca8c.png)
imageSource.description string Description of the image.

Image Position / Layout

Please refer to Android Pay official website.

Gift Layout: https://developers.google.com/save-to-android-pay/guides/gift-cards/design

Offer Layout: https://developers.google.com/save-to-android-pay/guides/offers/design

Loytal Layout: https://developers.google.com/save-to-android-pay/guides/loyalty/design

Passes

Create a Pass

Example of a pass creation request

curl https://api-pass.passkit.net/v3/passes
  -X POST 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "campaignName":"campaignName",
  "templateName":"templateName",
  "dynamicData":{
    "name":"Nicholas Bortoluzzi",
    "nickName":"LKF Killer",
    "point":12,
    "balance":952.24
  },
  "dynamicImages":{
    "passbook":{
      "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
      "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
      "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
      "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
      "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
      "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
    }
  },
  "dynamicBackfields":{
    "personalised-offers":[
      {
        "label":"Offer X",
        "value":"Offer X information"
      },
      {
        "label":"Offer Y",
        "value":"Offer Y information"
      },
      {
        "label":"Offer Z",
        "value":"Offer Z information"
      }
    ],
    "birthday-offers":[
      {
        "label":"Happy Birthday",
        "value":"Buy one get two free"
      }
    ]
  },
  "userDefinedId":"E1234567",
  "recoveryEmail":"hello@passkit.com",
  "isVoided":true,
  "isRedeemed":true,
  "isInvalid":true,
  "expiryDate":"2016-04-11T12:59:40Z",
  "passbook":{
    "groupId":"airline-1",
    "bgColor":"#FFFFFF",
    "labelColor":"000000",
    "fgColor":"#E4F9A0",
    "userInfo":{
        "key":"value"
    }
  }
}

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

POST https://api-pass.passkit.net/v3/passes

JSON Payload Parameters

Data type Description
campaignName string Required. This is the name of the campaign you created. For more detail, please see Create Campaign. This value cannot be changed after a pass created.
templateName string Required. This is the name of the template you created. For more detail, please see Create Template.
dynamicData object A key pair value JSON object. This is the user’s unique data. For example, customer name, date of birth, membership number. etc. The data will not show on the pass until it is defined in the template. See the example json for an example of the format.
dynamicImages object This is used to define a dynamic image for a pass, like a profile image on a membership pass. The value is the image path from Images Upload Endpoint. Please also see the sections Passbook Image Types and Dynamic Image Keys for more information regarding pass images.
dynamicBackfields object Please see Backfield Group
userDefinedId string This allows a unique Id to be added to the pass record that can provide easy compatibilty with an existing system using unique customer identifiers (e.g. membership numbers). You can retrieve pass data by using this endpoint via userDefinedId and campaignName instead of pass ID. This value must be unique within a campaign, and once this value is set, it cannot be changed.
recoveryEmail string The user’s email address. If this parameter is used, the user will receive an email containing a link to the pass.
isVoided bool When this field set to true, the pass will be voided. When the pass is voided the barcode will be greyed out and beacon and location notification will be turned off. Default value is false.
isRedeemed bool When this field set to true, the pass will be marked as redeemed. Default value is false
isInvalid bool When this field set to true, the pass is set as invaludated. The barcode, beacon and location messages will be removed and the pass can no longer be communicated with. Once a pass is set as invalidated, it cannot be changed. Default is false.
expiryDate ISO8601 datetime This is the pass expiry date. After the expiry date, the pass is automatically voided (seeisVoided). This value will override the template and campaign end date value.
passbook object This is where the Apple Wallet (Passbook) specific parameters are defined. Please see Passbook

Passbook

This object allow you to define Apple Wallet (Passbook) specific parameters.

JSON Parameters

Data type Description
groupId string This is an optional parameter used only for event tickets and boarding passes. This is the identifier used to group related passes. If a grouping identifier is specified, passes with the same style, pass type identifier, and grouping identifier are displayed as a group within Apple Wallet. Otherwise, passes are grouped automatically. Use this to group passes that are tightly related, such as the boarding passes for different connections of the same trip.
Available in iOS 7.0+ devices
bgColor string This parameter will override background color of the template. For example, If you set this value to #ffffff, this will override the template value of #000000 and the pass will show a background colour of #ffffff.
labelColor string This parameter will override label color set in the template, in the same way as using bgColor.
fgColor string This parameter will override foreground color set in the template, in the same way as using bgColor.
userInfo object Custom information for companion apps. This data is not displayed to the user.
For example, a pass for a cafe could include information about the user’s favorite drink and sandwich in a machine-readable form for the companion app to read, making it easy to place an order for “the usual” from the app.

Retrieve a Pass

Example of a pass retrieve request

curl https://api-pass.passkit.net/v3/passes/RanD0mStr1ng
  -X GET
  -H "Authorization:PKAuth json_web_token"

Example of server response:

{
  "id":"RanD0mStr1ng",
  "campaignName":"campaignName",
  "templateName":"templateName",
  "passbookDevices":0,
  "androidPayDevices":0,
  "updatedAt":"2016-03-15T23:42:56.271326844Z",
  "createdAt":"2016-03-15T23:42:56.271325489Z",
  "dynamicData":{
    "name":"Hello",
    "number":123,
    "float":123.34215
  },
  "dynamicImages":{
    "passbook":{
      "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
      "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
      "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
      "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
      "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
      "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
    }
  },
  "dynamicBackfields":{
    "personalised-offers":[
      {
        "label":"Offer X",
        "value":"Offer X information"
      },
      {
        "label":"Offer Y",
        "value":"Offer Y information"
      },
      {
        "label":"Offer Z",
        "value":"Ohffer Z information"
      }
    ],
    "birthday-offers":[
      {
        "label":"Happy Birthday",
        "value":"Buy one get two free"
      }
    ]
  },
  "userDefinedId":"E1234567",
  "recoveryEmail":"hello@passkit.com",
  "isVoided":true,
  "isRedeemed":true,
  "isInvalid":false,
  "expiryDate":"2016-04-11T12:59:40Z",
  "passbookMeta":{
    "groupId":"airline-1",
    "bgColor":"#000000",
    "labelColor":"#000000",
    "fgColor":"#000000",
     "userInfo":{
        "key":"value"
    }
  }
}

HTTP Request

GET https://api-pass.passkit.net/v3/passes/{passId}

URL Parameters

Parameter Data Type Description
passId string This is the pass Id that was returned when you created the pass.

JSON Response

Data type Description
id string This is the pass Id that was returned when you created the pass.
dynamicData object The dynamic data that the pass contains.
dynamicImages object The dynamic images set in the pass. Please also see the sections Passbook Image Types and Dynamic Image Keys for more information regarding pass images.
dynamicBackfields object Please see Backfield Group
userDefinedId string This displays the user defined ID for the pass, if specified when the pass was created.
campaignName string The campaign name the pass is associated with. Please see Create Campaign.
templateName string The template name that the pass was issued from. Please see Create Template.
passbookDevices integer The number of Passbook (Apple) devices that the pass is registered on.
androidPayDevices integer The number of Android Pay devices that the pass is registered on.
updatedAt ISO8601 datetime The date and time the pass was last updated
createdAt ISO8601 datetime The date and time the pass was created.
firstUnregisteredAt ISO8601 datetime The date and time the pass was first unregistered.
lastUnregisteredAt ISO8601 datetime The date and time the pass was most recently unregistered
firstRegisteredAt ISO8601 datetime The date and time the pass was first registered on a device
lastRegisteredAt ISO8601 datetime The date and time the pass was most recently registered on a device
isVoided bool A true value shows the pass is voided.
isRedeemed bool A true value shows the pass is in a redeemed state, if redeem status is enabled in your template.
isInvalid bool A true value show the pass is invalidated. An invalidated pass will have the barcode, beacon, and location messages removed and the pass can no longer be communicated with.
expiryDate ISO8601 datetime The Pass expiry date. After the expiry date, the pass will automatically be voided (same effect of isVoided). This value will override the template and campaign end date value.
recoveryEmail string This is the recovery email that was added when the pass was created.

Retrieve a Pass with User Defined Id

Example of a pass retrieve request

curl https://api-pass.passkit.net/v3/passes?userDefinedId=12345&campaignName=campaignName
  -X GET
  -H "Authorization:PKAuth json_web_token"

Server response is the same as from a normal retrieve pass

HTTP Request

GET https://api-pass.passkit.net/v3/passes?userDefinedId={userDefinedId}&campaignName={campaignName}

URL Parameters

Parameter Data Type Description
userDefinedId string This is the user defined id that was assigned when the pass was created. If a user defined id was not assigned at pass creation, the pass must be updated to include a user defined id before this method can be used.
campaignName string This is the reference name that you gave your campaign when it was created.

Update a Pass

Example of pass update request

curl https://api-pass.passkit.net/v3/passes/RanD0mStr1ng
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "templateName":"10_percent_off",
  "dynamicData":{
    "name":"Duncan Brown",
    "nickName":"Druncan",
    "points":20
  },
  "dynamicImages":{
    "passbook":{
      "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
      "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
      "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
      "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
      "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
      "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
    }
  },
  "dynamicBackfields":{
    "personalised-offers":[
      {
        "label":"Offer X",
        "value":"Offer X information"
      },
      {
        "label":"Offer Y",
        "value":"Offer Y information"
      },
      {
        "label":"Offer Z",
        "value":"Offer Z information"
      }
    ],
    "birthday-offers":[
      {
        "label":"Happy Birthday",
        "value":"Buy one get two free"
      }
    ]
  },
  "recoveryEmail":"hello@passkit.com",
  "isVoided":true,
  "isRedeemed":true,
  "isInvalid":true,
  "expiryDate":"2016-04-11T12:59:40Z",
  "passbookMeta":{
    "groupId":"airline-1",
    "bgColor":"#000000",
    "labelColor":"#000000",
    "fgColor":"#000000",
    "userInfo":{
        "key":"value"
    }
  }
}

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

PUT https://api-pass.passkit.net/v3/passes/{passId}[?push=1]

URL Parameters

Parameter Data Type Description
passId string This is the pass Id that was returned when you created the pass
push string If the query string push is 0, the API will not send a push to the pass. Default is 1.

JSON Payload Parameters

Data type Description
templateName string This value can be the templateName of any template being used by a campaign. For example, you can update this field from 10_percent_off_coupon to PassKit_membership_card, the pass data will remain the same, but the new template design will be used.

Only template with the same type is allowed to switch in Android Pay (e.g. From offer to gift is not allowed, offer to offer is okay.)
dynamicData object This is the user’s unique data. For example, customer name, date of birth, membership number. etc. The data will not show on the pass until it is defined in the template. See the example json for an example of the format.
dynamicImages object This is used to define a dynamic image for a pass, like a profile image on a membership pass. The value is the image path from Images Upload Endpoint. Please also see the sections Passbook Image Types and Dynamic Image Keys for more information regarding pass images.
dynamicBackfields object Please see Backfields Group
userDefinedId string This allows a unique Id to be added to the pass record that can provide easy compatibilty with an existing system using unique customer identifiers (e.g. membership numbers). You can retrieve pass data by using this endpoint via userDefinedId and campaignName instead of pass ID. This value must be unique within a campaign, and once this value is set, it cannot be changed.
recoveryEmail string The user’s email address. If this parameter is used, the user will receive an email containing a link to the pass.
isVoided bool When this field set to true, the pass will be voided. When the pass is voided the barcode will be greyed out and beacon and location notification will be turned off. Default value is false.
isRedeemed bool When this field set to true, the pass will be marked as redeemed. Default value is false
isInvalid bool When this field set to true, the pass is set as invaludated. The barcode, beacon and location messages will be removed and the pass can no longer be communicated with. Once a pass is set as invalidated, it cannot be changed. Default is false.
expiryDate ISO8601 datetime This is the pass expiry date. After the expiry date, the pass is automatically voided (seeisVoided). This value will override the template and campaign end date value.
passbook object This is where the Apple Wallet (Passbook) specific parameters are defined. Please see Passbook

Updating a Pass with a User Defined Id

Example of pass update request

curl https://api-pass.passkit.net/v3/passes?userDefinedId=12345&campaignName=campaignName
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "templateName":"templateName",
  "dynamicData":{
    "name":"Nicholas Bortoluzzi",
    "nickName":"LKF Killer",
    "point":12,
    "balance":952.24
  },
  "dynamicImages":{
    "passbook":{
      "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
      "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
      "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
      "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
      "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
      "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
    }
  },
  "dynamicBackfields":{
    "personalised-offers":[
      {
        "label":"Offer X",
        "value":"Offer X information"
      },
      {
        "label":"Offer Y",
        "value":"Offer Y information"
      },
      {
        "label":"Offer Z",
        "value":"Offer Z information"
      }
    ],
    "birthday-offers":[
      {
        "label":"Happy Birthday",
        "value":"Buy one get two free"
      }
    ]
  },
  "userDefinedId":"E1234567",
  "recoveryEmail":"hello@passkit.com",
  "isVoided":true,
  "isRedeemed":true,
  "isInvalid":true,
  "expiryDate":"2016-04-11T12:59:40Z",
  "passbook":{
    "groupId":"airline-1",
    "bgColor":"#FFFFFF",
    "labelColor":"000000",
    "fgColor":"#E4F9A0",
    "userInfo":{
        "key":"value"
    }
  }
}

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

PUT https://api-pass.passkit.net/v3/passes?userDefinedId={userDefinedId}&campaignName={campaignName}[&push=1]

URL Parameters

Parameter Data Type Description
userDefinedId string This is the user defined id that was assigned when the pass was created. If a user defined id was not assigned at pass creation, the pass must be updated to include a user defined id before this method can be used.
campaignName string This is the reference name that you gave your campaign when it was created.
push string If the query string push is 0, the API will not send a push to the pass. Default is 1.

JSON Payload Parameters

The JSON parameters are the same as Update Pass Method

Redeem a Pass

This method is a wrapper of Update Pass Method to simplify redemption process. This endpoint will update the pass data - isRedeemed from false to true. You can define a redeem status (e.g. passbookRedeem) in the template record. For more details regarding template records, please see JSON parameters of Template. When you call the endpoint using a pass ID, the redeem status of the template will automatically apply to a pass, instead of using the update pass method to change pass style individually.

Example of pass redeem request

curl https://api-pass.passkit.net/v3/passes/RanD0mStr1ng/redeem
  -X PUT 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

On success the api will respond with the Pass Id in JSON format:

{
  "id": "RanD0mStr1ng"
}

HTTP Request

PUT https://api-pass.passkit.net/v3/passes/{passId}/redeem[?push=1]

URL Parameters

Parameter Data Type Description
passId string This is the pass Id that was returned when you created the pass
push string If the query string push is 0, the API will not send a push to the pass. Default is 1.

JSON parameters

No payload is needed.

Batch Pass Methods

Batch Create Passes

Example of batch pass creation request

curl https://api-pass.passkit.net/v3/passesBatch
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

[
  {
    "campaignName":"campaignName",
    "templateName":"templateName",
    "dynamicData":{
      "name":"Nicholas Bortoluzzi",
      "nickName":"LKF Killer",
      "point":12
    },
    "dynamicImages":{
      "passbook":{
        "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
        "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
        "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
        "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
        "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
        "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
      }
    },
    "dynamicBackfields":{
      "personalised-offers":[
        {
          "label":"Offer X",
          "value":"Offer X information"
        },
        {
          "label":"Offer Y",
          "value":"Offer Y information"
        },
        {
          "label":"Offer Z",
          "value":"Offer Z information"
        }
      ],
      "birthday-offers":[
        {
          "label":"Happy Birthday",
          "value":"Buy one get two free"
        }
      ]
    },
    "userDefinedId":"E1234567",
    "recoveryEmail":"hello@passkit.com",
    "isVoided":true,
    "isRedeemed":true,
    "expiryDate":"2016-04-11T12:59:40Z",
    "passbook":{
      "groupId":"airline-1",
      "bgColor":"#000000",
      "labelColor":"#000000",
      "fgColor":"#000000"
    }
  },
  {
    "campaignName":"campaignName2",
    "templateName":"templateName2",
    "dynamicData":{
      "name":"Patrick Kosterman",
      "nickName":"Kostrgirl",
      "point":99
    },
    "dynamicImages":{
      "passbook":{
        "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9c.png",
        "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9d.png",
        "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9e.png",
        "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9f.png",
        "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9g.png",
        "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca9h.png"
      }
    },
    "dynamicBackfields":{
      "personalised-offers":[
        {
          "label":"Offer X",
          "value":"Offer X information"
        }
      ],
      "birthday-offers":[
        {
          "label":"Happy Birthday",
          "value":"Buy one get two free"
        }
      ]
    },
    "userDefinedId":"E1234568",
    "recoveryEmail":"hello@passkit.com",
    "isVoided":false,
    "isRedeemed":true,
    "expiryDate":"2019-04-11T12:59:40Z",
    "passbook":{
      "groupId":"airline-2",
      "bgColor":"#000000",
      "labelColor":"#000000",
      "fgColor":"#000000",
      "userInfo":{
        "key":"value"
      }
    }
  }
]

On success the api will respond with an array of Pass Ids in JSON format. The order of these Ids will match the order of the passes in the array sent.

{
  "id": [
    "RanD0mStr1ng",
    "IYqwjwde124J"
  ]
}

HTTP Request

POST https://api-pass.passkit.net/v3/passesBatch

JSON Payload Parameters

Type Description
an array of pass data Required. When using the batch create pass method you can specify an array of data for up to 25 passes, containing the same data as found in create a pass

Batch Update Passes

Example of batch pass update request

curl https://api-pass.passkit.net/v3/passesBatch
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"
[
  {
    "id":"RanD0mStr1ng",
    "templateName":"templateName",
    "dynamicData":{
      "points":"10"
    }
  },
  {
    "id":"IYqwjwde124J",
    "passbook":{
      "groupId":"Airline3"
    }
  }
]

On success the api will respond with an array of Pass Ids in JSON format. The order of these Ids will match the order of the passes in the array sent.

[
  "RanD0mStr1ng",
  "IYqwjwde124J"
]

HTTP Request

PUT https://api-pass.passkit.net/v3/passesBatch[?push=1]

URL Parameters

Parameter Data Type Description
push string If the query string push is 0, the API will not send a push to the pass. Default is 1.

JSON Payload Parameters

Type Description
an array of pass data Required. When using the batch update pass method you can specify an array of data for up to 25 passes, containing the same data as found in update a pass. Please note, each pass in the batch update pass call will also need to have their pass id added to the update call.

Batch Get Passes

Example of batch pass get request

curl https://api-pass.passkit.net/v3/passesBatch?id=ABC,CDE
  -X GET
  -H "Authorization:PKAuth json_web_token"

On success the api will respond with an array of Pass Ids in JSON format. The order of these Ids will match the order of the passes in the array sent.

[
  {
    "id":"RanD0mStr1ng",
    "campaignName":"campaignName",
    "templateName":"templateName",
    "passbookDevices":0,
    "androidPayDevices":0,
    "updatedAt":"2016-03-15T23:42:56.271326844Z",
    "createdAt":"2016-03-15T23:42:56.271325489Z",
    "dynamicData":{
      "name":"Hello",
      "number":123,
      "float":123.34215
    },
    "dynamicImages":{
      "passbook":{
        "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
        "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
        "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
        "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
        "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
        "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
      }
    },
    "userDefinedId":"E1234567",
    "recoveryEmail":"hello@passkit.com",
    "isVoided":true,
    "isRedeemed":true,
    "isInvalid":false,
    "expiryDate":"2016-04-11T12:59:40Z",
    "passbookMeta":{
      "groupId":"airline-1",
      "bgColor":"#000000",
      "labelColor":"#000000",
      "fgColor":"#000000"
    }
  },
  {
    "id":"IYqwjwde124J",
    "campaignName":"campaignName",
    "templateName":"templateName",
    "passbookDevices":0,
    "androidPayDevices":0,
    "updatedAt":"2016-03-15T23:42:56.271326844Z",
    "createdAt":"2016-03-15T23:42:56.271325489Z",
    "dynamicData":{
      "name":"Hello",
      "number":123,
      "float":123.34215
    },
    "dynamicImages":{
      "passbook":{
        "background":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png",
        "footer":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8d.png",
        "icon":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8e.png",
        "logo":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8f.png",
        "strip":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8g.png",
        "thumbnail":"images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8h.png"
      }
    },
    "userDefinedId":"E1234567",
    "recoveryEmail":"hello@passkit.com",
    "isVoided":true,
    "isRedeemed":true,
    "isInvalid":false,
    "expiryDate":"2016-04-11T12:59:40Z",
    "passbookMeta":{
      "groupId":"airline-1",
      "bgColor":"#000000",
      "labelColor":"#000000",
      "fgColor":"#000000",
      "userInfo":{
          "key":"value"
      }
    }
  }
]

HTTP Request

GET https://api-pass.passkit.net/v3/passesBatch?id=ABC,CDE

URL Parameters

Parameter Data Type Description
passId string This is the pass Id that was returned when you created the pass. Up to 25 pass IDs per request.

Images

Upload an Image

Upload an Image

curl https://api-pass.passkit.net/v3/images
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

{
  "base64String":"iVBORw0KGgoAAAANSUhEUgAAADIAAAAoCAYAAAC8cqlMAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAB9lpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczpkYz0iaHR0cDovL3B1cmwub3JnL2RjL2VsZW1lbnRzLzEuMS8iIHhtbG5zOnhtcE1NPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvbW0vIiB4bWxuczpzdEV2dD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL3NUeXBlL1Jlc291cmNlRXZlbnQjIiB4bWxuczpzdFJlZj0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL3NUeXBlL1Jlc291cmNlUmVmIyIgeG1sbnM6cGhvdG9zaG9wPSJodHRwOi8vbnMuYWRvYmUuY29tL3Bob3Rvc2hvcC8xLjAvIiB4bXA6Q3JlYXRvclRvb2w9IkFkb2JlIFBob3Rvc2hvcCBDUzYgKFdpbmRvd3MpIiB4bXA6Q3JlYXRlRGF0ZT0iMjAxNS0wNC0wOVQxNDo0NTo0MCswODowMCIgeG1wOk1ldGFkYXRhRGF0ZT0iMjAxNS0wNC0wOVQxNToyNTo1MyswODowMCIgeG1wOk1vZGlmeURhdGU9IjIwMTUtMDQtMDlUMTU6MjU6NTMrMDg6MDAiIGRjOmZvcm1hdD0iaW1hZ2UvcG5nIiB4bXBNTTpJbnN0YW5jZUlEPSJ4bXAuaWlkOkE3NzBGNDkyREU4OTExRTQ4NjkwREUxRkRCOTg5NUJEIiB4bXBNTTpEb2N1bWVudElEPSJ4bXAuZGlkOkE3NzBGNDkzREU4OTExRTQ4NjkwREUxRkRCOTg5NUJEIiB4bXBNTTpPcmlnaW5hbERvY3VtZW50SUQ9InhtcC5kaWQ6QjgwOUFBMEU2Q0RFRTQxMUE4NDY4MzczRkJFNjQ0OEQiPiA8eG1wTU06SGlzdG9yeT4gPHJkZjpTZXE+IDxyZGY6bGkgc3RFdnQ6YWN0aW9uPSJjcmVhdGVkIiBzdEV2dDppbnN0YW5jZUlEPSJ4bXAuaWlkOkI4MDlBQTBFNkNERUU0MTFBODQ2ODM3M0ZCRTY0NDhEIiBzdEV2dDp3aGVuPSIyMDE1LTA0LTA5VDE0OjQ1OjQwKzA4OjAwIiBzdEV2dDpzb2Z0d2FyZUFnZW50PSJBZG9iZSBQaG90b3Nob3AgQ1M2IChXaW5kb3dzKSIvPiA8cmRmOmxpIHN0RXZ0OmFjdGlvbj0ic2F2ZWQiIHN0RXZ0Omluc3RhbmNlSUQ9InhtcC5paWQ6QkQwOUFBMEU2Q0RFRTQxMUE4NDY4MzczRkJFNjQ0OEQiIHN0RXZ0OndoZW49IjIwMTUtMDQtMDlUMTU6MDM6NTcrMDg6MDAiIHN0RXZ0OnNvZnR3YXJlQWdlbnQ9IkFkb2JlIFBob3Rvc2hvcCBDUzYgKFdpbmRvd3MpIiBzdEV2dDpjaGFuZ2VkPSIvIi8+IDxyZGY6bGkgc3RFdnQ6YWN0aW9uPSJzYXZlZCIgc3RFdnQ6aW5zdGFuY2VJRD0ieG1wLmlpZDpEOEY3QkU5Qzg2REVFNDExQTg0NjgzNzNGQkU2NDQ4RCIgc3RFdnQ6d2hlbj0iMjAxNS0wNC0wOVQxNToxMDozOCswODowMCIgc3RFdnQ6c29mdHdhcmVBZ2VudD0iQWRvYmUgUGhvdG9zaG9wIENTNiAoV2luZG93cykiIHN0RXZ0OmNoYW5nZWQ9Ii8iLz4gPC9yZGY6U2VxPiA8L3htcE1NOkhpc3Rvcnk+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAuaWlkOkQ4RjdCRTlDODZERUU0MTFBODQ2ODM3M0ZCRTY0NDhEIiBzdFJlZjpkb2N1bWVudElEPSJ4bXAuZGlkOkI4MDlBQTBFNkNERUU0MTFBODQ2ODM3M0ZCRTY0NDhEIi8+IDxwaG90b3Nob3A6VGV4dExheWVycz4gPHJkZjpCYWc+IDxyZGY6bGkgcGhvdG9zaG9wOkxheWVyTmFtZT0iT0NSIiBwaG90b3Nob3A6TGF5ZXJUZXh0PSJPQ1IiLz4gPHJkZjpsaSBwaG90b3Nob3A6TGF5ZXJOYW1lPSJpIiBwaG90b3Nob3A6TGF5ZXJUZXh0PSJpIi8+IDwvcmRmOkJhZz4gPC9waG90b3Nob3A6VGV4dExheWVycz4gPC9yZGY6RGVzY3JpcHRpb24+IDwvcmRmOlJERj4gPC94OnhtcG1ldGE+IDw/eHBhY2tldCBlbmQ9InIiPz7ITscXAAACl0lEQVR42uyYT4hNURzH35skzUz+FePPQkxioZCZIVkpZDE1ChM2SDSmNKPMYpjBSFmQhbBQbOT/NDRIoyj5s8RCTPlTbHgLDGYwZZ7Pqd/T6XTOfff13pnR6/zqU/fe37nn3e+955zf97xkOp1OFEOUJIokgpAgJAgJQoKQICSfGBW3YbL7ZNz+lsMqqII5ME7dDt/gLTyD+3ALfmTrMF3bWFghWaIcdoH61WmONpOExbBDRFyCI/Dmfxham+A1HI4Q4RK/DV7BMSgbKSHl8kbPQ4Ul/wn2wxKYApWwHm5aRsVueAoLvc8RI6bCbVjgyHfBZpkXeqg5chVWwkWYqOVmw0Oot4j18kXU270XIeI6rLWI0KNHFoUB43opdEKdbyFqBboLcx35z7AFhozrs2Cyce05tFn6GA2XYakvISUyHOZFtDkNX7Xz6fBIVqWPcEEeNBOnoM8hpssx9/IW0gyrs7TpNs7Pam9W1ZIN0K7lf8kXtoX6gsd9COmI0eaddjxBJrUZdZYFwBX1PoQkc5xPg/DHcv1nDn0M+RByJUabmdpxv9QZM85E3JOwDM2CC2mBVJY2tcb5djgBX+A97DGEjHEMv8wK2O5DSErG92BEmwZZojMxIB5MFb4ZcFT5QC2/02j/zyvCVnEHXurIE9gYIUY98LmY/c6HQ45cK9zwXdk7ZQj1O/Jr4BqMjehjhbiDUkvugDjiYTGNymJUy97CJaZXKneN1AQ1qddJrekxfFampig3fHA4TaOKl+Js90GTuGHTk3XErD+PZWF4MVL7kd/y1iulCvfleP8DWUCW5SOikDvElOwp9oqNUc52kZjF8VJMv8MH2Ugpu35HNmQFiWT4Nz4ICUKCkCAkCAlCikjIXwEGAJZ9fFdhcPc9AAAAAElFTkSuQmCC"
}

{
  "imageUrl":"https://my-domain.com/logo.png"
}

On success the api will respond with the Template Name in JSON format:

{
  "path": "images/dynamic/c183b523fb63c7d538b4b2a63446fa0a20ddca8c.png"
}

HTTP Request

POST https://api-pass.passkit.net/v3/images

JSON Payload Parameter

Creating a template requires image files to be uploaded at the same time, this request is sent as multipart form.

Use either base64String or imageUrl to upload an image:

Parameter Type Description
base64String string A base64 string of the image. Image size must be lesser than 1MB.
imageUrl string An image URL. Image size must be lesser than 1MB.


Note: Please make the image as small as possible because big file size significantly slow down the pass download time.

JSON Response

Data type Description
path string A unique path to the image. It can be used as input parameter for anther API method.

Apple Certificates

When issuing passes for Apple Wallet they must be signed with a Pass Certificate (generated from a Pass Type ID) which are used by Apple to verify the data that is being sent to them. To generate a certificate you will need an Apple Developer Account (why?) and a CSR supplied by PassKit.

For detailed instructions regarding generating and uploading your own Pass Certificates, please see our help centre topic. When using the API to upload a Pass Certificate you will need to download a CSR file via the API, and then uploaded with the API using the API when finished.

Generate CSR

Generating CSR

curl https://api-pass.passkit.net/v3/passbookCsrs
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -o /path/to/download.csr

# Using -o with cURL to download the csr file to a specific location and name.

HTTP Request

POST https://api-pass.passkit.net/v3/passbookCsrs

Upload a Certificate

To upload a certificate, the request must be sent via multipart form

curl https://api-pass.passkit.net/v3/passbookCerts
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

JSON Payload

{
  "base64String":"{your .cer file base64 string}",
  "name":"My Certificate",
  "description":"The certificate I created"
}

The above request will return the Certificate ID (generated by PassKit) in JSON format:

{
  "id": "Poxgb4dEJa"
}

HTTP Request

POST https://api-pass.passkit.net/v3/passbookCerts

JSON Body Parameters

Parameter Data Type Description
base64String string Required. Base64 string of your certificate.
name string This is the name of your certificate, this is only used to help you identify the certificate. Maximum characters is 128.
description string This is the description of your certificate, this is only used to help you identify the certificate. Maximum characters is 32.

Renew a Certificate

To new a certificate, the request must be sent via multipart form

curl https://api-pass.passkit.net/v3/passbookCerts/{certificateID}
  -X PUT
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

JSON Payload

{
  "base64String":"{your .cer file base64 string}",
  "name":"My Certificate",
  "description":"The certificate I created"
}

The above request will return the Certificate ID (generated by PassKit) in JSON format:

{
  "id": "Poxgb4dEJa"
}

HTTP Request

PUT https://api-pass.passkit.net/v3/passbookCerts/{certificateID}

JSON Body Parameters

Same as Create Certificate

Retrieve Certificate Information

Retrieving Certificate

curl https://api-pass.passkit.net/v3/passbookCerts/{certificateID}
  -X GET
  -H "Authorization:PKAuth json_web_token"

The above request will return the certificate information in JSON format:

{
  "id":"Poxgb4dEJa",
  "passTypeId":"pass.com.example.app",
  "name":"My Certificate",
  "description":"The certificate I created",
  "validFrom":"2015-08-06T05:19:21Z",
  "validUntil":"2016-08-05T05:19:21Z",
  "teamName":"YourCompany",
  "teamCode":"YourCompanyCode",
  "createdAt":"2016-01-08T11:32:52.57531013Z",
  "updatedAt":"2016-01-08T11:32:52.575311554Z"
}

HTTP Request

GET https://api-pass.passkit.net/v3/passbookCerts/{certificateId}

URL Parameters

Parameter Data Type Description
certificateId string This is the Certificate ID returned when you uploaded a certificate

JSON Response

Parameter Data Type Description
id string This is the Certificate ID returned when you uploaded a certificate
passTypeId string This is the the Pass Type ID that you registered with Apple
name string This is the name of your certificate, this is only used to help you identify the certificate
description string This is the description of your certificate, this is only used to help you identify the certificate
validFrom ISO8601 datetime This is date that your certificate is valid from.
validUntil ISO8601 datetime This is date that your certificate is valid until.
teamName string This is your Apple developer account team name.
teamCode string This is your Apple developer account team code.
createdAt ISO8601 datetime This is the date/time your certificate was uploaded
updatedAt ISO8601 datetime This is the date/time your certificate was last updated.

List Your Certificates

Retrieving All Certificate

$result = $pk.ListCertificates();
curl https://api-pass.passkit.net/v3/passbookCerts
  -X GET
  -H "Authorization:PKAuth json_web_token"

The above request will return an array of certificate information in JSON format:

[
  {
    "id":"Poxgb4dEJa",
    "passTypeId":"pass.com.example.app",
    "name":"My Certificate",
    "description":"The certificate I created",
    "validFrom":"2015-08-06T05:19:21Z",
    "validUntil":"2016-08-05T05:19:21Z",
    "teamName":"YourCompany",
    "teamCode":"YourCompanyCode",
    "createdAt":"2016-01-08T11:32:52.57531013Z",
    "updatedAt":"2016-01-08T11:32:52.575311554Z"
  }
]

HTTP Request

GET https://api-pass.passkit.net/v3/passbookCerts

JSON Response

The response is similar to the one for retrieving a single certificate, but will list an array of this information, one object for each Pass Certificate.

Recovery Email

Resend or Update Recovery Email

This endpoint allows people to send a recovery email based on pass ID. In addition, it also allows to update pass’s recovery email and resend to the new email address at the same time. You can resend emails up to 10 items per request.

Example of a request

curl "https://api-pass.passkit.net/v3/recoveryEmails/resend"
  -X "PUT" 
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Payload example

[
  {
    "passId":"6ddyveV8Ho5xV8",
    "newRecoveryEmail":"kit@passkit.com"
  },
  {
    "passId":"meNyAZnTnbCmWH"
  },
  {
    "passId":"4qgfeKDIuBINHh",
    "newRecoveryEmail":"hello@passkit.com"
  }
]

On success the api will respond with the Pass Id in JSON format:

[
  {
    "passId": "6ddyveV8Ho5xV8",
    "recoveryEmail": "kit@passkit.com",
    "success": true
  },
  {
    "passId": "meNyAZnTnbCmWH",
    "recoveryEmail": "kit@passkit.com",
    "success": true
  },
  {
    "passId":"4qgfeKDIuBINHh",
    "recoveryEmail":"hello@passkit.com",
    "success": true
  }
]

HTTP Request

PUT https://api-pass.passkit.net/v3/recoveryEmails/resend

JSON parameters

Data type Description
passId string Required. Pass ID need to resend recovery email.
newRecoveryEmail string If this value is specified, it will update current pass’s recovery email and resend a recovery email to the new email address.

Search

Example of a search initiation request:

curl https://search.passkit.net/v1/passes
  -X POST
  -H "Authorization:PKAuth json_web_token"
  -H "Content-Type: application/json"

Search input in JSON format:

{
  "size":2,
  "from":0,
  "passFilter":{
    "id":"passId123",
    "templateName":"templateName",
    "campaignName":"campaignName",
    "userDefinedId":"myPass123",
    "isRedeemed":false,
    "isInvalid":false,
    "isVoided":false,
    "expiryDate":{
      "gte":"2016-04-11T12:59:59Z"
    },
    "updatedAt":{
      "eq":"2015-04-11T13:00:00Z"
    },
    "createdAt":{
      "eq":"2015-04-11T13:00:00Z"
    },
    "firstUnregisterAt":{
      "exists":false
    },
    "lastUnregisterAt":{
      "exists":false
    },
    "firstRegisterAt":{
      "exists":false
    },
    "lastRegisterAt":{
      "exists":false
    },
    "lastRedeemAt":{
      "exists":false
    },
    "recoveryEmail":{
      "exists":false
    },
    "dynamicData":{
      "name":{
        "eq":"MrAwesome"
      },
      "point":{
        "lte":12
      },
      "balance":{
        "gt":900,
        "lt":1500
      }
    },
    "androidPayDevices":{
      "gte":5000,
      "lte":10000
    },
    "passbookDevices":{
      "gte":5000,
      "lte":10000
    }
  }
}

Search output in JSON format:

{
  "data":[
    {
      "androidPayDevices":0,
      "campaignName":"campaign",
      "createdAt":"2016-06-17T07:08:53.627020984Z",
      "dynamicBackfields":null,
      "dynamicData":{},
      "id":"8HcmhZ7xu6rmUQ",
      "isInvalid":false,
      "isRedeemed":false,
      "isVoided":false,
      "passbookDevices":0,
      "recoveryEmail":"test@passkit.com",
      "templateName":"Test_Run",
      "updatedAt":"2016-06-17T07:08:53.627022014Z"
    },
    {
      "androidPayDevices":0,
      "campaignName":"campaign2",
      "createdAt":"2016-06-27T08:35:33.820605955Z",
      "dynamicBackfields":null,
      "dynamicData":{},
      "id":"WA4CICRvomIM0X",
      "isInvalid":false,
      "isRedeemed":false,
      "isVoided":false,
      "passbookDevices":0,
      "recoveryEmail":"test@passkit.com",
      "templateName":"Test_Run2",
      "updatedAt":"2016-06-27T08:35:33.820605955Z"
    }
  ],
  "nextFrom": 3,
  "totalCount": 4
}

HTTP Request

POST https://search.passkit.net/v1/passes

Query

The attributes of the search are to be defined here

JSON Parameters

Data Type Description
size integer The size of the search result
from integer The starting index of the search
passFilter pass filter The filter criteria of the search

JSON Response

Data Type Description
data an array of passes shows each pass and their related fields
nextFrom int allows the user to paginate for a certian number of values
totalCount int references the number of passes in the entire search

CSV Request

CSV input request for fields in JSON in format:

{
  "dynamicFields":["Email"],
  "standardFields":["id","isRedeemed"],
  "email":"johndoe@example.com",
  "customSubject": "CSV EMAIL"
}

CSV output in JSON format:

{
  "fileID": "6s8K5aSVtFKGpO8LChkgleaQllBIMq6n",
  "fileName": "2017_02_06_1633_6s8K5aSVtFKGpO8LChkgleaQllBIMq6n.zip",
  "password": "D0opQZwrjqZ8bZGy",
  "totalCount": 2
}

Error example input:

{
  "dynamicFields":[],
  "standardFields":[],
  "email":"jlangford@pga.com"
}

Error output

{
  "error": "Can not have both dynamicFields and 
            standardFields as empty arrays"
}

Error example input:

{
  "dynamicFields":["Email"],
  "standardFields":["incorrectName"],
  "email":"jlangford@pga.com"
}

Error output

{
  "error": "Your key/keys: (incorrectName) do not match our pre-defined key names"
}

We offer the ability to send a custom CSV file containing information on up to a million customers to a specified email. The CSV file will be held inside a password protected zipfile.

Note(s):

1) The CSV function only allows 1 million entries per file.

2) UTF-8 characters are supported by this function; however, certian programs may not fully support all characters available.

3) Processing time may vary based on number of passes and usage rate.

HTTP Request

POST https://search.passkit.net/v1/passes/csv

JSON parameters

Data Type Description
dynamicFields an array of strings Refers to the dynamic data that the pass contains. This field is not case sensitive. See Operation for further details.
standardFields an array of strings
Standard Fields
If you specify any number of fields here, they will be the only ones written to the CSV. If it is an empty array, none will be used. If you leave it blank, we will send you all fields.
email
(required)
string This is the email that you wish the CSV to be sent to.
passFilter PassFilter The filter criteria of the search.
customSubject string Custom email subject.

JSON response

Data Type Description
fileID string Refers to the ID of the file.
fileName string Refers to the name of the file. Contains the fileID.
password string Refers to the password needed to open the zipfile.
totalCount int Refers to the total number of entries in the csv.

Error handling

Below are the custom errors we have included when requesting a CSV file.

Description Status
Both dynamicFields and standardFields can not be empty arrays. 400
Values in standardFields must match our pre-defined list. All values can be found here 400
You have requested over a million pass records. 400

Standard Fields

Name Type
id string
campaingName string
templateName string
userDefinedId operation
passbookDevices operation
androidPayDevices operation
updatedAt operation
createdAt operation
firstUnregisterAt operation
lastUnregisterAt operation
lastRegisterAt operation
lastRedeemAt operation
firstRegisterUserAgent operation
lastRegisterUserAgent operation
expiryDate operation
isInvalid bool
isRedeemed bool
isVoided bool
recoveryEmail operation

Pass Filter

The specific search criteria of the search are to be defined here

Note(s):

1) To filter by date, follow YYYY-MM-DDTHH:MM:SSZ format. Also, note that defining the full date format is not requried. For example, date in YYYY-MM format is also a valid search filter.

JSON Parameters

Data Type Description
id string Refers to the auto-generated passId of the issued pass.
templateName string The template name that the pass was issued from. Please see Create Template.
campaignName string Refers to the campaign name the pass is associated with. Please see Create Campaign.
userDefinedId Operation Refers to the passId given by the issuer of the issued pass
isRedeemed bool A true value shows that the pass has been redeemed, if redeem status is enabled in your template.
isInvalid bool A true value shows that the pass is invalidated. An invalidated pass will have the barcode, beacon, and location messages removed and the pass can no longer be communicated with.
isVoided bool A true value shows that the pass is voided.
expiryDate Operation Refers to the expiry date of the pass. After the expiry date, the pass will automatically be voided (same effect of isVoided). This value will override the template and campaign end date value. See Operation for further details.
updatedAt Operation Refers to the date and time the pass was last updated. See Operation for further details.
createdAt Operation Refers to the date and time the pass was created. See Operation for further details.
firstUnregisterAt Operation Refers to the first date and time the pass was unregistered at. See Operation for further details.
lastUnregisterAt Operation Refers to the last date and time the pass was unregistered at. See Operation for further details.
firstRegisterAt Operation Refers to the first date and time the pass was registered at. See Operation for further details.
lastRegisterAt Operation Refers to the last date and time the pass was registered at. See Operation for further details.
lastRedeemAt Operation Refers to the date and time the pass was redeemed at. See Operation for further details.
recoveryEmail Operation Refers to the recovery email that was added when the pass was created. See Operation for further details.
dynamicData map of Operation Refers to the dynamic data that the pass contains. See Operation for further details.
androidPayDevices Operation Refers to the number of Android Pay devices that the pass is registered on. See Operation for further details.
passbookDevices Operation Refers to the number of Apple devices that the pass is registered on. See Operation for further details.

Operation

The range of the search are to be defined here.

Note(s):

1) Either of “gt” or “gte” can be used to filter the search of an operation.

2) Either of “lt” or “lte” can be used to filter the search of an operation.

3) “eq” can only be used alone to define the search range for an operation.

4) “exists” can only be used alone to define the search range for an operation.

JSON parameters

Data Type Description
gt string or number Returns search results that is greater than the stated value.
gte string or number Returns search results that is greater than and equal to the stated value.
lt string or number Returns search results that is smaller than the stated value.
lte string or number Returns search results that is smaller than and equal to the stated value.
eq string or number Returns search results that is equal to the stated value.
exists bool A true value will return search results that have a previously defined value.

General

Supported Languages

Language Code Language
ar (Arabic) العربية
ca Català (Catalan)
zh-Hans 简体中文 (Simplified Chinese)
zh-Hant 繁體中文 (Traditional Chinese)
hr Hrvatski (Croatian)
cs Čeština (Czech)
da Dansk (Danish)
nl Nederlands (Dutch)
en English
en-GB English (British)
fi Suomi (Finnish)
fr Français (French)
de Deutsch (German)
el Ελληνικά (Greek)
he (Hebrew) עברית
hu Magyar (Hungarian)
id Bahasa Indonesia (Indonesian)
it Italiano (Italian)
ja 日本語 (Japanese)
ko 한국어 (Korean)
ms Bahasa Melayu (Malay)
nb Norsk Bokmål (Norwegian)
pl Polski (Polish)
pt-BR Português (Brazilian Portuguese)
pt Português de Portugal (Portuguese)
ro Română (Romanian)
ru Русский (Russian)
sk Slovenčina (Slovakian)
es Español (Spanish)
sv Svenska (Swedish)
th ภาษาไทย (Thai)
tr Türkçe (Turkish)
uk Українська (Ukranian)
vi Tiếng Việt (Vietnamese)

Currency Codes

All the available currency codes (ISO 4217) are listed here:

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STD, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, USS, UYI, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XFU, XOF, XPD, XPF, XPT, XTS, XXX, YER, ZAR, ZMK, ZWL

Campaign Callbacks (Webhook)

When a callback object is defined in Campaign record. The following pass activites will trigger webhook and send a POST HTTP requset to the URL.

onIssueCallbackUrl - An event will fire when a pass is created.
onUpdateCallbackUrl - An event will fire when a pass is updated
onRegisterCallbackUrl - An event will fire when a pass is installed on the Phone
onDeregisterCallbackUrl - An event will fire when a pass is uninstalled the on the Phone (only available for iOS, Pass2U and mWallet App)

For the HTTP request, it contain a JWT in the HTTP header - Authorization so that you can use the following information to authenticate the request.

exp - Unix timestamp of expiry time
key - Your API key
iat - Unix timestamp of create time

The JWT will be signed by API secret. So, you can verify the JWT by your API key and secret.

Change Log

Date Notes
29 March, 2017 Added v3 endpoint information
13 Oct, 2016 Added disableWebServiceUrl in Apple Wallet model.
3 October, 2016 Added new JWT format for authorization, and subuser management endpoints