Base URL for requests

https://verizonventures-prod.apigee.net/ua-wallet

Wallet API

Version 1.2 of the Wallet Studio API supports Apple Passbook and Google Wallet.

Overview

Here’s what you need to do to get started with the Wallet Studio API:

  1. Request access to the API by contacting the Urban Airship Sales team. Once approved, you’ll find additional configuration features in Account Settings.
  2. Get your API key :Your private API key is located under Account Settings. Keep it safe, and treat it like a password. You’ll need it to access the API.
  3. Upload your Certificate (optional): If you want to use your own Apple Pass Type certificate, upload it in the Certificate Management section of Account Settings. See the instructions to learn how to generate a certificate.
  4. Create a Project using the Wallet Studio interface. You will then be guided through the creation of a template layout for your project. The API is template-based.

Fundamental Concepts

The primary concept is that passes are created from pass templates.

Passes can then be:

  • Created with your custom data.
  • Completely changed and re-added to an existing user’s Passbook.
  • Updated with certain field changes, so the user’s pass would be updated automatically via push notification.
  • Distributed through your own systems (email, SMS, URL) to your customers.

Specifying a Version

The current version of the Wallet Studio API is 1.2. The versioning for the Wallet Studio is currently different than the versioning for the Urban Airship API.

Past versions are 1.0 and 1.1. Documentation for those old version can be found on the old GitHub project here.

You should always specify the version of the API you want to use by adding an HTTP header called Api-Revision. The value of that header should be in the format x.y where x is the API version and y the sub-revision. For instance 1.1 is for the /v1 API and revision 1.

Example:

curl -X POST "https://verizonventures-prod.apigee.net/ua-wallet/v1/pass/28504" -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2" -d 'json={"fields": {"Name": {"value": "John Doe"}}}'

Authentication

All of our API calls (except “Get System Status”) require authentication via HTTP basic authentication. The username portion is the email address of your account. The password portion is your API key. Your API key is listed in the Wallet Studio web interface under Account > API Management > API Key.

The Authorization header is constructed as follows:

  • Email and API key are combined into a string “[YOUR_EMAIL]:[YOUR_KEY]”.
  • The resulting string is then Base64 encoded.
  • The authorization method and a space are then added before the encoded string i.e “Basic ”.
curl -X POST "https://verizonventures-prod.apigee.net/ua-wallet/v1/pass/28504" -H "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" -H "Api-Revision:1.2" -d 'json={"fields": {"Name": {"value": "John Doe"}}}'

Date/Time Format

All date/time values are represented according to ISO 8601 in UTC. A T separator is preferred but not required; it will be included in all date/time values generated by the API.

Example:

2015-01-28T15:00-05:00

Posting JSON in the Request Body

A historical idiosyncrasy to the Wallet Studio API is the way JSON is sent in the request body. Instead of specifying the Content-Type: application/json header and posting JSON directly in the body, the Wallet Studio API instead requires you to specify the Content-Type: application/x-www-form-urlencoded header and put the JSON in a field name called json.

Example:

curl -X POST "https://verizonventures-prod.apigee.net/ua-wallet/v1/pass/28504" -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2" -d 'json={"fields": {"Name": {"value": "John Doe"}}}'

Note that the data posted in the request body is not pure JSON, it’s json=<your_json_here>. Also note that curl defaults to the Content-Type: application/x-www-form-urlencoded header, and we haven’t specified the Content-Type: application/json header. We recognize that this method of posting JSON within HTTP forms is out of style and may change this in a future revision of the API.

HTTP Response Codes

400 Invalid Request Parameters
This error happens when basic input parameters check fail (such as data types mismatch..)
401 Unauthorized
The authentication check failed.
406 Not Acceptable Request
This error happens on higher level validation checks, such as required input field is missing... and a list of field level error are then returned on the JSON response as a JSON array (see example below).
429 Too Many Requests
We throttle requests to a limited amount of API calls/sec per account in order to prevent system overloads. If you encounter this error, please reduce the concurrency. We will soon expose your account quota to let you know how many requests remain per account within a time interval.
500 Internal Server Error
Our servers encountered an error not necessarily caused by the API call.

The http response body on error code has the following JSON format:

{
   "code": 406,
   "description": "Not Acceptable Request",
   "details": "field errors",
   "fieldErrors": [{"fieldName":"coupon_price", "message": " required field missing!"}]
}

code matches the HTTP response code. fieldErrors is optional.

Security

  • Our APIs only work under 2048 bit HTTPS encrypted connections to ensure your data is private from client to server connections.
  • Access is authenticated through a unique secret key which we provide to you during the onboarding process. It is your responsibility to keep this key well guarded as it represents your identity.
  • You can either use your own Apple’s certificate to sign passes, or we will assign a unique certificate to your account.

Version Changelog

Revision 1.0 Changes

This represents the start of our platform and basically enables you to create, update passes as well as add locations.

Revision 1.1 Changes

  • New revision scheme whereby api revisions can be served per end point with user level passing http header.
  • New asynchronous updates for improved performance from the API client caller and better delivery.
  • Ticketing service to check on the status of asynchronous requests.
  • Updates now automatically does push as well.
  • New tags functionality whereby tags can be associated to tags and updates can be done for a given tag and update change fields set.
  • Ability to pass an external Id during the create pass flow and look up those passes by external Id. This is based on customer requests wanting to pass us their own pass UUID in order to avoid managing the book-keeping of our passId on the client side.
  • New input JSON model for create/update passes whereby header fields are now moved into a headers json object , and accommodate for new input such as tags objects. We are starting to model a wallet more generically to soon support cross platform digital wallets.

Projects

Create Project

POST /v1/project/
 
POST /v1/project/id/(externalId)

Create an empty project. If the /v1/project/id/(externalId) URL is used, the project will be created with the associated external id.

Example request:

POST /v1/project HTTP/1.1
Content-Type: application/x-www-form-urlencoded

json=<json>
{
  "name": "Aztec Barcode",
  "projectType": "loyalty",
  "description": "Aztec Barcode",
  "settings": {
    "barcode_alt_text": "123json=456789",
    "barcode_label": "Member ID",
    "barcode_default_value": "123456789",
    "barcode_encoding": "iso-8859-1",
    "barcode_type": "pdf417"
  },
}


Query Parameters:
  • externalId – The external id you wish to use for the project.
JSON Parameters:
  • name – Required. The name of the project.
  • projectType – Required. The project type, can be any one of loyalty, coupon, giftCard, memberCard, eventTicket, boardingPass, generic.
  • description – Required. The description of the project.

Example response:

{
   "updatedAt": "2013-07-01T19:57:36.190Z",
   "id": "10058",
   "templates": [
   ],
   "description": "Aztec Barcode",
   "createdAt": "2013-07-01T19:57:36.190Z",
   "settings": {
      "barcode_alt_text": "123json=456789",
      "barcode_default_value": "123456789",
      "barcode_encoding": "iso-8859-1",
      "barcode_label": "Member ID",
      "barcode_type": "pdf417"
   },
   "name": "Aztec Barcode",
   "projectType":"loyalty",
}

CURL example:

curl -X POST
https://verizonventures-prod.apigee.net/ua-wallet/v1/project -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2" -d 'json={"name":"Aztec Barcode","projectType":"loyalty","description":"Aztec Barcode","settings":{"barcode_alt_text":"123json=456789","barcode_label":"Member ID","barcode_default_value":"123456789","barcode_encoding":"iso-8859-1","barcode_type":"pdf417"}}'

Get Project

GET /v1/project/(projectId)
 
GET /v1/project/id/(externalId)

Get the project with the specified id.

Example request:

GET /v1/project/1 HTTP/1.1


Query Parameters:
  • projectId – The id of the project you are looking for.
  • externalId – The external id of the project you are looking for.

Example response:

{
   "updatedAt": "2013-06-27T20:55:06.000Z",
   "id": "10041",
   "templates" :[
      {
         "vendor": "Apple",
         "projectType": "loyalty",
         "projectId": "10041",
         "type": "Store Card",
         "vendorId": "1",
         "deleted": "False",
         "id": "23573",
         "updatedAt": "2013-06-27T20:58:05.000Z",
         "description": "Template 1",
         "createdAt": "2013-06-27T20:51:09.000Z",
         "name": "Template 1",
         "disabled": "False"
      },
      {
         "vendor": "Google",
         "projectType": "loyalty",
         "projectId": "10041",
         "type": "Loyalty1",
         "vendorId": "2",
         "deleted": "False",
         "id": "23576",
         "updatedAt": "2013-06-27T20:55:23.000Z",
         "description": "GW Template1",
         "createdAt": "2013-06-27T20:55:06.000Z",
         "name": "GW Template1",
         "disabled": "False"
      },
   ],
   "description": "Aztec Barcode",
   "createdAt": "2013-06-27T20:51:02.000Z",
   "settings": {
      "id": "10041",
      "passbook_count": "2",
      "barcode_alt_text": "123456789",
      "barcode_default_value": "123456789",
      "barcode_encoding": "iso-8859-1",
      "google_count": "1",
      "barcode_label": "Member ID",
      "barcode_type_text": "Aztec",
      "barcode_type": "aztec"
   },
   "name": "Aztec Barcode",
   "projectType": "loyalty"
}

List Projects

GET /v1/project/

List the projects belonging to you.

Example request:

GET /v1/project/ HTTP/1.1


Query Parameters:
  • pageSize – Number of projects per page.
  • page – Page you want to retrieve, starting with 1.
  • order – The order you want the projects returned in. Can be any one of id, name, createdAt or updatedAt. Default is id.
  • direction – Whether you want the values ordered ascending or descending. Can be either asc or desc; default is asc

Example response:

{
   "projects":[
      {
         "updatedAt": "2013-06-27T20:55:06.000Z",
         "id": "10041",
         "description": "Aztec Barcode",
         "createdAt": "2013-06-27T20:51:02.000Z",
         "settings": {
            "id": "10041",
            "passbook_count": "2",
            "barcode_alt_text": "123456789",
            "barcode_default_value": "123456789",
            "barcode_encoding": "iso-8859-1",
            "google_count": "1",
            "barcode_label": "Member ID",
            "barcode_type_text": "Aztec",
            "barcode_type": "aztec"
         },
         "name": "Aztec Barcode",
         "projectType": "loyalty"
      },
      {
         "updatedAt": "2013-06-27T01:38:21.000Z",
         "id": "10040",
         "description": "Apple Templates",
         "createdAt": "2013-06-26T18:43:07.000Z",
         "settings": {
            "passbook_count": "3",
            "barcode_alt_text": "123456789",
            "barcode_default_value": "123456789",
            "barcode_encoding": "iso-8859-1",
            "google_count": "1",
            "barcode_label": "Member ID",
            "barcode_type": "pdf417"
         },
         "name": "Apple Templates",
         "projectType": "loyalty"
      }
  ],
  "count": "89",
  "pagination": {
     "order": "id",
     "page": "1",
     "start": "0",
     "direction": "DESC",
     "pageSize":10
  }
}

CURL example:

curl https://verizonventures-prod.apigee.net/ua-wallet/v1/project -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2"

Update Project

PUT /v1/project/(projectId)
 
PUT /v1/project/id/(externalId)

Update a project.

Example request:

PUT /v1/project/12345 HTTP/1.1
Content-Type: application/x-www-form-urlencoded

json=<json>
{
  "name": "Updated Name"
}


Query Parameters:
  • projectId – The id of the project you wish to update.
  • externalID – The external id of the project you wish to update.
JSON Parameters:
  • name – Required. The name of the project.
  • description – Required. The description of the project.
  • projectType – Required. The project type, can be any one of loyalty, coupon, giftCard, memberCard, eventTicket, boardingPass, generic.

Example response:

{
   "updatedAt": "2013-07-01T19:57:36.000Z",
   "id": 10058,
   "templates": [
   ],
   "description": "Aztec Barcode",
   "createdAt": "2013-07-01T19:57:36.000Z",
   "settings": {
   },
   "name": "Updated Name",
   "projectType": "loyalty"
}

CURL example:

curl -X PUT https://verizonventures-prod.apigee.net/ua-wallet/v1/project/10058 -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2" -d 'json={"name":"Updated Name"}'

Templates

Create Template

POST /v1/template
 
POST /v1/template/id/(externalId)
 
POST /v1/template/(projectId)
 
POST /v1/template/(projectId)/id/(externalId)

/v1/template simply creates a template. /v1/template/id/(externalId) creates a template with an external id. /v1/template/(projectId) creates a template and adds it to the specified project. /v1/template/(projectId)/id/(externalId) creates a template with an external id and adds it to the specified project.

Example request:

POST /v1/template HTTP/1.1


Query Parameters:
  • externalId – A unique external id that you will use to reference this template in the future.
  • projectId – The id of the project you’d like to add the template to.

Example request body: Apple

{
   "headers":{
      "logo_color":{
         "formatType":1,
         "fieldType":"topLevel",
         "value":"rgb(24,86,148)"
      },
      "icon_image":{
         "formatType":1,
         "fieldType":"image",
         "value":"https://s3.amazonaws.com/passtools-localhost/1/images/b2233b504a7cc852477543a7cd6aa2362b863e63_/default-pass-icon.png"
      },
      "logo_text":{
         "formatType":1,
         "fieldType":"topLevel",
         "value":"Logo Text"
      },
      "barcode_encoding":{
         "formatType":1,
         "fieldType":"topLevel",
         "value":"iso-8859-1"
      },
      "suppress_strip_shine":{
         "formatType":1,
         "fieldType":"topLevel",
         "value":"true"
      },
      "logo_image":{
         "formatType":1,
         "fieldType":"image",
         "value":"https://s3.amazonaws.com/passtools-localhost/1/images/67a8575b631c10da02b40a4d88fabfbbcd1434a2_54659f6c-9d90-11e2-b861-22000a98b3f2-large.jpg"
      },
      "foreground_color":{
         "formatType":1,
         "fieldType":"topLevel",
         "value":"rgb(255,255,255)"
      },
      "background_color":{
         "formatType":1,
         "fieldType":"topLevel",
         "value":"rgb(49,159,196)"
      }
   },
   "fields":{
      "Text":{
         "formatType":"String",
         "changeMessage":"Edited",
         "order":1,
         "fieldType":"primary",
         "textAlignment":"textAlignmentRight",
         "value":"",
         "label":"Text",
         "required":false,
         "hideEmpty":true
      },
      "spelledOut":{
         "formatType":"Number",
         "changeMessage":"888",
         "order":2,
         "numberStyle":"numberStyleSpellOut",
         "fieldType":"secondary",
         "value":888.0,
         "label":"Spelled Out Edited",
         "required":false,
         "hideEmpty":true
      },
      "Apple 2":{
         "formatType":"String",
         "changeMessage":"888",
         "order":1,
         "fieldType":"secondary",
         "value":"",
         "label":"Apple 2",
         "required":false,
         "hideEmpty":false
      }
   },

   "vendor":"Apple",
   "projectType":"memberCard",
   "projectId":1001,
   "type":"Store Card",
   "vendorId":1,
   "deleted":"False",
   "description":"Description",
   "name":"Loyalty Card",
   "disabled":"False"
}

Example request body: Google

{
   "infoModuleData": {
      "hexFontColor": "#666666",
      "hexBackgroundColor": "#0096e1",
      "Program ID": {
         "label": "Program ID",
         "value": "12345678",
         "row": 0,
         "col": 0,
         "formatType": "String"
      },
      "Tier Name": {
         "label": "Tier Name",
         "value": "Silver",
         "row": 0,
         "col": 1,
         "formatType": "String"
      },
      "Last Updated": {
         "label": "Last Updated",
         "value": "Five days ago",
         "row": 1,
         "col": 0,
         "formatType": "String"
      }
   },
   "headers": {
      "barcode_type": {
         "fieldType": "barcode",
         "value": "",
         "notShared": true
      },
      "barcode_value": {
         "fieldType": "barcode",
         "value": "",
         "notShared": true
      },
      "barcode_label": {
         "fieldType": "barcode",
         "value": "",
         "notShared": true
      },
      "barcode_encoding": {
         "fieldType": "barcode",
         "value": "",
         "notShared": true
      },
      "barcodeAltText": {
         "fieldType": "barcode",
         "value": "",
         "notShared": true
      }
   },
   "textModulesData": {
      "Program Details": {
         "header": "Program Details",
         "body": "Some Basic Text",
         "row": 0,
         "col": 0,
         "formatType": "String"
      }
   },
   "linksModuleData": {
      "Merchant Website": {
         "description": "Merchant Website",
         "uri": "http://www.test.com",
         "order": 1,
         "formatType": "URL"
      }
   },
   "messageModule": {
   },
   "imageModulesData": {
   },
   "pointsModule": {
      "Tier": {
         "label": "Tier",
         "value": 2,
         "row": 0,
         "col": 1,
         "formatType": "Number",
         "numberStyle": "PKNumberStyleDecimal"
      },
      "Points": {
         "label": "Points",
         "value": 1234,
         "row": 0,
         "col": 0,
         "formatType": "Number"
      }
   },
   "notAssigned": {
   },
   "titleModule": {
      "image":"https://s3.amazonaws.com/passtools-localhost/1/images/b2233b504a7cc852477543a7cd6aa2362b863e63_/default-pass-icon.png",
      "imageDescription": "Logo Image",
      "Program Name": {
         "label": "Program Name",
         "value": "UA",
         "row": 0,
         "col": 0,
         "formatType": "String"
     }
   },
   "vendor": "Google",
   "projectType":"memberCard",
   "type": "Loyalty1",
   "vendorId":2,
   "deleted":"False",
   "description": "description",
   "name": "Adding Google"
}

Example Response:

{
   "templateId": 23598
}

Get Template

GET /v1/template/(templateId)
 
GET /v1/template/id/(externalId)

Get the template specified by the id.

Example request:

GET /v1/template/12345 HTTP/1.1


Query Parameters:
  • templateId – The id of the template you wish to retrieve.
  • externalId – The external id of the template you with to wish to retrieve.

Example response: Apple

{
   "fieldsModel":{
      "headers":{
         "logo_color":{
            "formatType":1,
            "fieldType":"topLevel",
            "value":"rgb(24,86,148)"
         },
         "icon_image":{
            "formatType":1,
            "fieldType":"image",
            "value":"https:\/\/s3.amazonaws.com\/passtools-localhost\/1\/images\/b2233b504a7cc852477543a7cd6aa2362b863e63_\/default-pass-icon.png"
         },
         "logo_text":{
            "formatType":1,
            "fieldType":"topLevel",
            "value":"Logo Text"
         },
         "barcode_encoding":{
            "formatType":1,
            "fieldType":"topLevel",
            "value":"iso-8859-1"
         },
         "suppress_strip_shine":{
            "formatType":1,
            "fieldType":"topLevel",
            "value":"true"
         },
         "logo_image":{
            "formatType":1,
            "fieldType":"image",
            "value":"https:\/\/s3.amazonaws.com\/passtools-localhost\/1\/images\/67a8575b631c10da02b40a4d88fabfbbcd1434a2_54659f6c-9d90-11e2-b861-22000a98b3f2-large.jpg"
         },
         "foreground_color":{
            "formatType":1,
            "fieldType":"topLevel",
            "value":"rgb(255,255,255)"
         },
         "background_color":{
            "formatType":1,
            "fieldType":"topLevel",
            "value":"rgb(49,159,196)"
         }
      },
      "fields":{
         "Text":{
            "formatType":"String",
            "changeMessage":"Edited",
            "order":1,
            "fieldType":"primary",
            "textAlignment":"textAlignmentRight",
            "value":"",
            "label":"Text",
            "required":false,
            "hideEmpty":true
         },
         "spelledOut":{
            "formatType":"String",
            "changeMessage":"888",
            "order":2,
            "numberStyle":"PKNumberStyleSpellOut",
            "fieldType":"secondary",
            "value":888.0,
            "label":"Spelled Out Edited",
            "required":false,
            "hideEmpty":true
         },
         "Apple 2":{
            "formatType":"String",
            "changeMessage":"888",
            "order":1,
            "fieldType":"secondary",
            "value":"",
            "label":"Apple 2",
            "required":false,
            "hideEmpty":false
         }
      }
   },
   "templateHeader":{
      "vendor":"Apple",
      "projectType":"memberCard",
      "projectId":10057,
      "type":"Store Card",
      "vendorId":1,
      "deleted":"False",
      "id":"23593",
      "updatedAt":"2013-07-01T18:28:33.000Z",
      "description":"Description",
      "createdAt":"2013-07-01T18:28:33.000Z",
      "name":"Loyalty Card",
      "disabled":"False"
   }
}

Example response: Google

{
   "fieldsModel":{
      "infoModule":{
         "Time":{
            "formatType":"Date",
            "changeMessage":null,
            "col":0,
            "dateStyle":"dateStyleShort",
            "fieldType":"infoModule",
            "value":"2013-05-30T19:00:00Z",
            "timeStyle":"dateStyleShort",
            "label":"Time",
            "required":false,
            "hideEmpty":false,
            "row":1
         },
         "backgroundColor":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"infoModule",
            "value":"#0096e1",
            "label":"",
            "required":false,
            "hideEmpty":false
         },
         "AddedNumber":{
            "formatType":"Number",
            "changeMessage":null,
            "col":0,
            "fieldType":"infoModule",
            "value":"123",
            "label":"AddedNumber",
            "required":false,
            "hideEmpty":false,
            "row":0
         },
         "Currency":{
            "formatType":"Currency",
            "changeMessage":null,
            "col":1,
            "currencyCode":"USD",
            "fieldType":"infoModule",
            "value":888.0,
            "label":"Currency",
            "required":false,
            "hideEmpty":false,
            "row":0
         }
      },
      "headers":{
         "barcodeAltText":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"topLevel",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         },
         "barcode_value":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"topLevel",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         },
         "barcode_encoding":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"topLevel",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         },
         "barcode_label":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"topLevel",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         },
         "barcode_type":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"topLevel",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         }
      },
      "textModule":{
         "textModule":{
            "formatType":"String",
            "body":"",
            "Basic Text 3":{
               "col":0,
               "order":1,
               "value":"",
               "label":"Basic Text 3",
               "row":0
            },
            "fieldType":"textModule",
            "hideEmpty":false,
            "header":"Basic Text 3"
         }
      },
      "linkModule":{
         "Link":{
            "formatType":"URL",
            "order":1,
            "description":"http:\/\/www.meanPurnima.com",
            "fieldType":"linksModule",
            "uri":"Link",
            "hideEmpty":false
         }
      },
      "messageModule":{

      },
      "imageModule":{
         "imageModule":{
            "formatType":"String",
            "fieldType":"imageModule",
            "image":"",
            "hideEmpty":false,
            "imageDescription":"Logo Image"
         }
      },
      "vendor":"Google",
      "pointsModule":{
         " Number":{
            "formatType":"String",
            "balance":123.0,
            "col":0,
            "fieldType":"loyaltyPoints",
            "label":" Number",
            "hideEmpty":false,
            "row":0
         },
         "Two":{
            "formatType":"Number",
            "balance":2.0,
            "col":0,
            "fieldType":"loyaltyPoints",
            "label":"Two-edited",
            "hideEmpty":false,
            "row":0
         }
      },
      "notAssigned":{
         "Text":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"notAssigned",
            "value":"",
            "label":"Text",
            "required":false,
            "hideEmpty":false
         },
         "spelledOut":{
            "formatType":"Number",
            "changeMessage":null,
            "fieldType":"notAssigned",
            "value":"888",
            "label":"Spelled Out Edited",
            "required":false,
            "hideEmpty":false
         },
         "Apple 2":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"notAssigned",
            "value":"",
            "label":"Apple 2",
            "required":false,
            "hideEmpty":false
         }
      },
      "titleModule":{
         "Basic Text 4":{
            "formatType":"String",
            "description.string":"",
            "col":0,
            "title.string":"Basic Text 4",
            "fieldType":"titleModule",
            "hideEmpty":false,
            "row":0
         },
         "image":{
            "formatType":"String",
            "description.string":"Logo Image",
            "title.string":"https:\/\/s3.amazonaws.com\/passtools-localhost\/1\/images\/67a8575b631c10da02b40a4d88fabfbbcd1434a2_54659f6c-9d90-11e2-b861-22000a98b3f2-large.jpg",
            "fieldType":"titleModule",
            "hideEmpty":false
         },
         "One":{
            "formatType":"String",
            "description.string":"1",
            "col":0,
            "title.string":"One",
            "fieldType":"titleModule",
            "hideEmpty":false,
            "row":0
         }
      }
   },
   "templateHeader":{
      "vendor":"Google",
      "projectType":"memberCard",
      "projectId":1001,
      "type":"Loyalty1",
      "vendorId":2,
      "deleted":"False",
      "id":"1002",
      "updatedAt":"2013-06-25T18:00:31.000Z",
      "description":"description",
      "createdAt":"2013-02-01T09:02:03.000Z",
      "name":"Loyalty Card",
      "disabled":"False"
   }
}

CURL example:

curl https://verizonventures-prod.apigee.net/ua-wallet/v1/template/123 -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2"

List Templates

GET /v1/template/headers

List the headers for templates belonging to you.

Example request:

GET /v1/template/headers HTTP/1.1


Query Parameters:
  • pageSize – Number of projects per page
  • page – Page you want to retrieve, starting with 1
  • order – The order you want the projects returned in. Can be any one of id, name, createdAt or updatedAt. Default is id.
  • direction – Whether you want the values ordered ascending or descending. Can be either asc or desc, default is asc.

Example response:

{
   "count": "133",
   "templateHeaders": [
      {
         "vendor": "Google",
         "projectType": "memberCard",
         "projectId": "10057",
         "type": "Loyalty1",
         "vendorId": "2",
         "deleted": "False",
         "id": "23595",
         "updatedAt": "2013-07-01T18:28:54.000Z",
         "description": "description",
         "createdAt": "2013-07-01T18:28:54.000Z",
         "name": "New Wallet Template",
         "disabled": "False"
      },
      {
         "vendor": "Apple",
         "projectType": "memberCard",
         "projectId": "10057",
         "type": "Store Card",
         "vendorId": "1",
         "deleted": "False",
         "id":"23593",
         "updatedAt": "2013-07-01T18:28:33.000Z",
         "description": "Description",
         "createdAt": "2013-07-01T18:28:33.000Z",
         "name": "Loyalty Card",
         "disabled": "False"
      }
   ],
   "pagination": {
      "order": "id",
      "page": "1",
      "start": "0",
      "direction": "DESC",
      "pageSize": "10"
   }
}

CURL example:

curl https://verizonventures-prod.apigee.net/ua-wallet/v1/template/headers -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2"

Update Template

PUT /v1/template/(templateId)
 
PUT /v1/template/id/(externalId)

Update the specified template.

Example request:

PUT /v1/template/12345 HTTP/1.1


Query Parameters:
  • templateId – The id of the existing template that you want to duplicate
  • externalId – The external id of the existing template that you want to duplicate

Example request body: Apple

{
   "headers":{
      "logo_color":{
         "formatType":"1",
         "fieldType":"topLevel",
         "value":"rgb(24,86,148)"
      },
      "icon_image":{
         "formatType":"1",
         "fieldType":"image",
         "value":"https://s3.amazonaws.com/passtools-localhost/1/images/b2233b504a7cc852477543a7cd6aa2362b863e63_/default-pass-icon.png"
      },
      "logo_text":{
         "formatType":"1",
         "fieldType":"topLevel",
         "value":"Logo Text"
      },
      "barcode_encoding":{
         "formatType":"1",
         "fieldType":"topLevel",
         "value":"iso-8859-1"
      },
      "suppress_strip_shine":{
         "formatType":"1",
         "fieldType":"topLevel",
         "value":"true"
      },
      "logo_image":{
         "formatType":"1",
         "fieldType":"image",
         "value":"https://s3.amazonaws.com/passtools-localhost/1/images/67a8575b631c10da02b40a4d88fabfbbcd1434a2_54659f6c-9d90-11e2-b861-22000a98b3f2-large.jpg"
      },
      "foreground_color":{
         "formatType":"1",
         "fieldType":"topLevel",
         "value":"rgb(255,255,255)"
      },
      "background_color":{
         "formatType":"1",
         "fieldType":"topLevel",
         "value":"rgb(49,159,196)"
      }
   },
   "fields":{
      "Text":{
         "formatType":"String",
         "changeMessage":"Edited",
         "order":"1",
         "fieldType":"primary",
         "textAlignment":"textAlignmentRight",
         "value":"some value",
         "label":"Text",
         "required":"false",
         "hideEmpty":"true"
      },
      "spelledOut":{
         "formatType":"Number",
         "changeMessage":"888",
         "order":"2",
         "numberStyle":"numberStyleSpellOut",
         "fieldType":"secondary",
         "value":"888.0",
         "label":"Spelled Out Edited",
         "required":"false",
         "hideEmpty":"true"
      },
      "Apple 2":{
         "formatType":"String",
         "changeMessage":"888",
         "order":"1",
         "fieldType":"secondary",
         "value":"Edited",
         "label":"Apple 2(Edited)",
         "required":"false",
         "hideEmpty":"false"
      }
   },
   "beacons":[
      {
         "uuid" : "55502220-A123-A88A-F321-555A444B333C",
         "relevantText" : "You are near the Ship",
         "major":2,
         "minor":346
      }
   ],
   "vendor":"Apple",
   "projectType":"memberCard",
   "projectId":"10059",
   "type":"Store Card",
   "vendorId":"1",
   "deleted":"False",
   "description":"Description",
   "name":"Loyalty Card (Edited)",
   "disabled":"False"
}

Example request body: Google:

{
   "fieldsModel":{
      "infoModule":{
         "Time":{
            "formatType":"Date",
            "changeMessage":"null",
            "col":"0",
            "dateStyle":"dateStyleShort",
            "fieldType":"infoModule",
            "value":"2013-05-30T19:00:00Z",
            "timeStyle":"dateStyleShort",
            "label":"Time",
            "required":"false",
            "hideEmpty":"false",
            "row":"1"
         },
         "backgroundColor":{
            "formatType":"String",
            "changeMessage":"null",
            "fieldType":"infoModule",
            "value":"#0096e1",
            "label":"some_label",
            "required":"false",
            "hideEmpty":"false"
         },
         "AddedNumber":{
            "formatType":"Number",
            "changeMessage":"null",
            "col":"0",
            "fieldType":"infoModule",
            "value":"123",
            "label":"AddedNumber",
            "required":"false",
            "hideEmpty":"false",
            "row":"0"
         },
         "Currency":{
            "formatType":"Currency",
            "changeMessage":"null",
            "col":"1",
            "currencyCode":"USD",
            "fieldType":"infoModule",
            "value":"888.0",
            "label":"Currency",
            "required":"false",
            "hideEmpty":"false",
            "row":"0"
         }
      },
      "headers":{
         "barcodeAltText":{
            "formatType":"String",
            "changeMessage":"new message",
            "fieldType":"topLevel",
            "value":"some value",
            "label":"some label",
            "required":"false",
            "hideEmpty":"false"
         },
         "barcode_value":{
            "formatType":"String",
            "changeMessage":"some message",
            "fieldType":"topLevel",
            "value":"some value",
            "label":"some message",
            "required":"false",
            "hideEmpty":"false"
         },
         "barcode_encoding":{
            "formatType":"String",
            "changeMessage":"some message",
            "fieldType":"topLevel",
            "value":"",
            "label":"",
            "required":"false",
            "hideEmpty":"false"
         },
         "barcode_label":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"topLevel",
            "value":"",
            "label":"",
            "required":"false",
            "hideEmpty":"false"
         },
         "barcode_type":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"topLevel",
            "value":"",
            "label":"",
            "required":"false",
            "hideEmpty":"false"
         }
      },
      "textModule":{
         "textModule":{
            "formatType":"String",
            "body":"",
            "Basic Text 3":{
               "col":"0",
               "order":"1",
               "value":"",
               "label":"Basic Text 3",
               "row":"0"
            },
            "fieldType":"textModule",
            "hideEmpty":false,
            "header":"Basic Text 3"
         }
      },
      "linkModule":{
         "Link":{
            "formatType":"URL",
            "order":"1",
            "description":"http://www.meanPurnima.com",
            "fieldType":"linksModule",
            "uri":"Link",
            "hideEmpty":false
         }
      },
      "messageModule":{
      },
      "imageModule":{
         "imageModule":{
            "formatType":"String",
            "fieldType":"imageModule",
            "image":"",
            "hideEmpty":"false",
            "imageDescription":"Logo Image"
         }
      },
      "vendor":"Google",
      "pointsModule":{
         " Number":{
            "formatType":"String",
            "balance":"123.0",
            "col":"0",
            "fieldType":"loyaltyPoints",
            "label":"Number",
            "hideEmpty":"false",
            "row":"0"
         },
         "Two":{
            "formatType":"Number",
            "balance":"2.0",
            "col":"0",
            "fieldType":"loyaltyPoints",
            "label":"Two-edited",
            "hideEmpty":"false",
            "row":"0"
         }
      },
      "notAssigned":{
         "Text":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"notAssigned",
            "value":"",
            "label":"Text",
            "required":"false",
            "hideEmpty":"false"
         },
         "spelledOut":{
            "formatType":"Number",
            "changeMessage":null,
            "fieldType":"notAssigned",
            "value":"888",
            "label":"Spelled Out Edited",
            "required":"false",
            "hideEmpty":"false"
         },
         "Apple 2":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"notAssigned",
            "value":"",
            "label":"Apple 2",
            "required":"false",
            "hideEmpty":"false"
         }
      },
      "titleModule":{
         "Basic Text 4":{
            "formatType":"String",
            "description.string":"",
            "col":"0",
            "title.string":"Basic Text 4",
            "fieldType":"titleModule",
            "hideEmpty":"false",
            "row":"0"
         },
         "image":{
            "formatType":"String",
            "description.string":"Logo Image",
            "title.string":"https://s3.amazonaws.com/passtools-localhost/1/images/67a8575b631c10da02b40a4d88fabfbbcd1434a2_54659f6c-9d90-11e2-b861-22000a98b3f2-large.jpg",
            "fieldType":"titleModule",
            "hideEmpty":"false"
         },
         "One":{
            "formatType":"String",
            "description.string":"1",
            "col":"0",
            "title.string":"One",
            "fieldType":"titleModule",
            "hideEmpty":"false",
            "row":"0"
         }
      }
   },
   "templateHeader":{
      "vendor":"Google",
      "projectType":"memberCard",
      "type":"Loyalty1",
      "vendorId":2,
      "deleted":"False",
      "description":"description",
      "name":"Adding Google",
   }
}

Example response:

{
   "templateId":"23596"
}

Duplicate Template

POST /v1/template/duplicate/(templateId)
 
POST /v1/template/duplicate/id/(externalId)

/v1/template/duplicate/(templateId) duplicates the specified template and put it in the same project. /v1/template/duplicate/id/(externalId) duplicate the template specified by the external id, and puts the newly created template in the same project.

Example request:

POST /v1/template/duplicate/12345 HTTP/1.1


Query Parameters:
  • templateId – The id of the existing template that you want to duplicate
  • externalId – The external id of the existing template that you want to duplicate

Example response:

{
   "templateId": 23596
}

Add Locations to Template

POST /v1/template/(templateId)/locations
 
POST /v1/template/id/(externalId)/locations

Add locations to the specified template.

Example request:

POST /v1/template/12345/locations HTTP/1.1

Sample Request Body:

{
   "locations":[
      {
         "longitude":-122.374,
         "latitude":37.618,
         "relevantText":"Hello loc0",
         "streetAddress1":"address line #1",
         "streetAddress2":"address line #2",
         "city":"Palo Alto",
         "region":"CA",
         "regionCode":"94404",
         "country":"US"
      }
   ]
}


Query Parameters:
  • templateId – The id of the template to which you are adding locations.
  • externalId – The external id of the template to which you are adding locations.
JSON Parameters:
  • longitudeRequired: Longitude of the location
  • latitudeRequired: Latitude of the location
  • relevantText – Text to display to the user when close to this location
  • streetAddress1 – Street address
  • streetAddress2 – Street address (continued)
  • city – City that the address is in
  • region – Region (state) that the address is in
  • regionCode – Postal code for this location
  • country – Country that the location is in

Example response:

[
   {
      "value":{
         "region":"CA",
         "regionCode":"94404",
         "relevantText":"Hello loc0",
         "streetAddress1":"address line #1",
         "streetAddress2":"address line #2",
         "longitude":-122.374,
         "latitude":37.618,
         "city":"Palo Alto"
      },
      "locationId":65,
      "fieldId":1842
   }
]

Delete Location from Template

DELETE /v1/template/(templateId)/location/(locationId)
 
DELETE /v1/template/id/(externalId)/locations/(locationId)

Delete location from template.

Example request:

DELETE /v1/template/123/location/456 HTTP/1.1
 



Query Parameters:
  • templateId – The id of the template you’d like to delete a location from.
  • externalId – The external id of the template you’d like to delete a location from.
  • locationId – The location id of the location you’d like to delete from the template.

Delete Template

DELETE /v1/template/(templateId)
 
DELETE /v1/template/id/(externalId)

Delete the specified template.

Example request:

DELETE /v1/template/12345 HTTP/1.1


Query Parameters:
  • templateId – The id of the template you wish to delete.
  • externalId – The external id of the template you wish to delete.

Example response:

{
   "status": "Deleted",
   "TemplateID": "23593"
}

Passes

Create Pass

POST /v1/pass/(templateId)
 
POST /v1/pass/id/(templateExternalId)
 
POST /v1/pass/(templateId)/id/(passExternalId)
 
POST /v1/pass/id/(templateExternalId)/id/(passExternalId)

Create a pass from the specified template. Optionally, give the pass an externalId. Note that this example includes a value for expirationDate which can be updated later. The example also includes the barcodeAltText and barcode_value headers; these objects must be included if you wish to push dynamic barcodes with your passes, or barcodes that vary with each pass.

Example request:

POST /v1/pass/123 HTTP/1.1
{
    "headers":{
        "expirationDate":{
           "value":"2014-08-20T9:41-08:00"
         },
         "barcodeAltText":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"barcode",
            "value":"abc1234567890",
            "label":"",
         },
         "barcode_value":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"barcode",
            "value":"abc1234567890",
            "label":"",
         }
    },
    "fields":{
        "Text":{
           "changeMessage":"edited text value",
           "value":"Text Value",
           "label":"Text Label"
        },
        "spelledOut":{
           "changeMessage":"spelled out changed",
           "value":"888",
           "label":"Spelled Out Edited"
        },
        "Apple 2":{
           "changeMessage":"Apple 2 Changed",
           "value":"Apple 2-value",
           "label":"Apple 2-label"
        },
        "thumbnail_image":{
           "value":"https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
        }
    },
    "beacons":[
        {
           "uuid":"55502220-A123-A88A-F321-555A444B333C",
           "relevantText":"You are near the Ship",
           "major":2,
           "minor":346
        }
    ],
    "publicURL" : {
        "type" : "single"
    }
}

Example response:

{
    "id": 888,
    "templateId": 64,
    "createdAt":"2012-11-01 12:37:07.0",
    "url": "https://wallet-api.urbanairship.com/v1/pass/888/download",
    "publicUrl":{
          "path":"https:\/\/wallet-api.urbanairship.com\/v1\/download\/pass\/9c9c9c7d-c6b6-9c9c-9d2b-9c9c9c54c89c",
          "used":false,
          "type":"Single",
          "installs":0
    },
    "passFields":{
        "header1":{
            "changeMessage":"",
            "fieldType":"HEADER",
            "value":"signature regression test",
            "label":"my value",
            "required":false
        },
        "logo_text":{
            "changeMessage":null,
            "fieldType":"TOP_LEVEL",
            "value":"Test Value",
            "label":"",
            "required":false
        },
        "primary1" {
            "changeMessage":"",
            "fieldType":"PRIMARY",
            "value":"Welcome",
            "label":"",
            "required":false
        },
        "thumbnail_image":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"image",
            "value":"https:\/\/s3.amazonaws.com\/passtools...0bb4_favicon.png",
            "label":"",
            "required":false,
            "hideEmpty":false
        }
    },
    "beacons":[
        {
            "uuid":"55502220-A123-A88A-F321-555A444B333C",
            "relevantText":"You are near the Ship",
            "major":2,
            "minor":346
        }
    ]
}


Query Parameters:
  • templateId – The ID of the template you are using to create this pass
  • templateExternalId – The External ID of the template you are using to create this pass
  • passExternalId – The external id you want associated with the newly created pass
JSON Parameters:

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

  • barcode_value - May contain the following fields:

    • formatType: Specify the formatting type
    • changeMessage: Notify the user if the barcode value changes, see the Apple docs for more information.
    • fieldType: Specify the field type (set to "barcode" by default)
    • value: Barcode value
    • label: Human-readable label for this barcode, displayed above the barcode
  • barcodeAltText - May contains the same fields as barcode_value.

fields:

An unordered set of named JSON objects containing pass field information

  • changeMessage - The change message associated with this field
  • value - Value for this field
  • label - Label for this field
beacons:

A JSON array of beacons, each containing the following information:

  • uuid - Unique identifier of a beacon
  • relevantText - Text displayed on the lock screen
  • major - Major identifier of a beacon
  • minor - Minor identifier of a beacon
publicURL:

Option to request a publicly accessible URL for the pass

  • type - single or multiple use, depending on how many times it can be downloaded

Warning

Failure to include the publicURL parameter results in a URL that requires the api key to download a pass.

Get Pass

GET /v1/pass/(passId)
 
GET /v1/pass/id/(externalId)

Get the specified pass.

Example request:

GET /v1/pass/123 HTTP/1.1

Example response:

{
   "tags":[

   ],
   "headers":{
      "barcodeAltText":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"barcode",
         "value":"123456789",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "logo_color":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"topLevel",
         "value":"rgb(24,86,148)",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "icon_image":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"topLevel",
         "value":"https://s3.amazonaws.com/passtools-localhost/1/images/3e4300b95680a39c595bed893822f0c42dae0d8c_starbucks-icon.png",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "barcode_value":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"barcode",
         "value":"123456789",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "logo_text":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"topLevel",
         "value":"Logo",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "barcode_encoding":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"barcode",
         "value":"iso-8859-1",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "suppress_strip_shine":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"topLevel",
         "value":"true",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "barcode_label":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"barcode",
         "value":"Member ID",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "barcode_type":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"barcode",
         "value":"PKBarcodeFormatPDF417",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "foreground_color":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"topLevel",
         "value":"rgb(255,255,255)",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "background_color":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"topLevel",
         "value":"rgb(0,147,201)",
         "label":"",
         "required":false,
         "hideEmpty":false
      }
   },
   "id":"1249",
   "templateId":"23524",
   "updatedAt":"2013-06-19T01:06:23.000Z",
   "createdAt":"2013-06-19T01:06:17.000Z",
   "serialNumber":"14f94898-2f5e-46f5-925c-7e29fa9a0508",
   "url":"https://wallet-api.urbanairship.com/v1/pass/1249/download",
   "fields":{
      "Merchant Website":{
         "formatType":"URL",
         "changeMessage":"",
         "order":2,
         "fieldType":"back",
         "value":"http://www.test.com",
         "label":"Merchant Website",
         "required":false,
         "hideEmpty":false
      },
      "More Details":{
         "formatType":"String",
         "changeMessage":"",
         "order":1,
         "fieldType":"back",
         "value":"More details about how to use this event ticket. Additional terms and support information.",
         "label":"More Details",
         "required":false,
         "hideEmpty":false
      }
   }
}


JSON Parameters:
  • passId – The id of the pass you wish to retrieve.
  • externalId – The external id of the pass you wish to retrieve.

List Passes

GET /v1/pass

List your passes

Example request:

GET /v1/pass HTTP/1.1

Example response:

{
   "count":1043,
   "passes":[
      {
         "id":"1273",
         "templateId":"23573",
         "updatedAt":"2013-06-27T20:58:20.000Z",
         "createdAt":"2013-06-27T20:58:18.000Z",
         "serialNumber":"ff9db2ed-37aa-4691-a3b6-240108ac31f9",
         "url":"https://wallet-api.urbanairship.com/v1/pass/1273/download"
      },
      {
         "id":"1272",
         "templateId":"23574",
         "updatedAt":"2013-06-27T20:56:07.000Z",
         "createdAt":"2013-06-27T20:56:03.000Z",
         "serialNumber":"a2ea965a-0917-461d-ac67-749639831818",
         "url":"https://wallet-api.urbanairship.com/v1/pass/1272/download"
      },
      {"..."}
   ],
   "pagination":{
      "order":"id",
      "page":1,
      "start":0,
      "direction":"DESC",
      "pageSize":10
   }
}


Query Parameters:
  • pageSize – Number of passes per page
  • page – Page you wish to retrieve, starting with 1.
  • order – The order you want the passes returned in. Can be any one of id, name, createdAt or updatedAt. Default is id.
  • direction – Whether you want the values ordered ascending or descending. Can be either ASC or DESC, default is DESC.

Update Pass

PUT /v1/pass/(passId)
 
PUT /v1/pass/id/(externalId)

Update the specified pass. Optionally, update the pass with the specified externalId.

Note

Include only parameters you wish to update in the target pass.

Example request:

PUT /v1/pass/123 HTTP/1.1
{
    "fields":{
        "Text":{
           "changeMessage":"edited text value",
           "value":"Text Value",
           "label":"Text Label"
        },
        "spelledOut":{
           "changeMessage":"spelled out changed",
           "value":"888",
           "label":"Spelled Out Edited"
        },
        "Apple 2":{
           "changeMessage":"Apple 2 Changed",
           "value":"Apple 2-value",
           "label":"Apple 2-label"
        },
        "thumbnail_image":{
           "value":"https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
        }
    },
    "beacons" : [
       {
          "uuid" : "55502220-A123-A88A-F321-555A444B333C",
          "relevantText" : "You are near the Ship",
          "major" : 1,
          "minor" : 777
       },
       {
          "uuid" : "55502220-A123-A88A-F321-555A444B333C",
          "relevantText" : "You are near the Ship"
       }
    ]
}

Note

Updating an expired pass with "label" : "valid" under the expirationDate key will once again make the pass useable.



JSON Parameters:
  • passId – The id of the pass you wish to update.
  • externalId – The external id of the pass you wish to update.
  • fields – a JSON object containing the field information
  • changeMessage – The change message associated with this field.
  • value – Value for this field.
  • label – Label for this field.

Example response:

{
    "ticketId": 1200
}

Expire Pass

You may add an expiration date (or update the existing expiration) to a pass with the Update Pass (PUT) endpoint.

Example
Update expiration date:
PUT /v1/pass/123 HTTP/1.1
{
    "headers": {
        "expirationDate": {
            "value": "2014-08-20T9:41-08:00"
        }
    },
    "fields": {
        "Seat": {
            "value": "26E"
        }
    }
}
Example
Void pass, i.e., render it expired immediately
PUT /v1/pass/123 HTTP/1.1
{
    "headers": {
        "expirationDate": {
            "label": "voided"
        }
    },
    "fields": {
        "Seat": {
            "value": "26E"
        }
    }
}

Get Apple JSON for a Pass

GET /v1/pass/(passId)/viewJSONPass
 
GET /v1/pass/id/(externalId)/viewJSONPass

View pass.json as per the Apple’s Passbook spec. This is a utility API to help debug your passes.

Example request:

GET /v1/pass/123/viewJSONPass HTTP/1.1

Example response:

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


JSON Parameters:
  • passId – The id of the pass you wish to retrieve
  • externalId – The external id of the pass you wish to retrieve

Google Save to Wallet

POST /v1/pass/(templateId)/saveToWallet

Create a pass from the specified template

Example request:

POST /v1/pass/123/saveToWallet HTTP/1.1
{
   "fields":{
      "Points":{
         "value":"600"
      }
   },
   "tag":"abc",
   "externalId":"UserName",
   "onSuccess":"mySuccessFunc",
   "onFail":"myFailureFunc"
}

Example response:

<script src="https://apis.google.com/js/plusone.js" type="text/javascript"></script>
<script type="text/javascript">
function urban_airship_callback(path) {
   var script = document.createElement('script');
   script.src = path
   document.getElementsByTagName('head')[0].appendChild(script);
}
var successHandler = function (params) {
   urban_airship_callback('https://wallet-api.urbanairship.com/v1/card/register/2931580989855247863.31885_34ab7304-0148-407f-9e4a-69ae30c1efd1')
}
var failureHandler = function (params) {
   urban_airship_callback('https://wallet-api.urbanairship.com/v1/card/register/2931580989855247863.31885_34ab7304-0148-407f-9e4a-69ae30c1efd1')
}
</script><g:savetowallet
   jwt="eyJhbGciOiJSUzI1NiJ9..."
   onsuccess="mySuccessFunc"
   onfailure="myFailureFunc" size="small" theme="gray">
</g:savetowallet>


JSON Parameters:
  • templateId – The ID of the template you are using to create this pass
  • tag – A single tag the card will be added to
  • ExternalId – An ID that can be used to update the card in the future
  • fields – a JSON object containing the field information
  • field.value – Value for this field
  • field.label – Label for this field
  • onSuccess – Javascript function you create that is called when the card is successfully added
  • onFail – Javascript function you create that is called when the card fails to be added

Download Pass

GET /v1/pass/(passId)/download
 
GET /v1/pass/id/(externalId)/download

Download the pass with the specified id.

Example request:

GET /v1/pass/123/download HTTP/1.1


JSON Parameters:
  • passId – The id of the pass you wish to retrieve.
  • externalId – The external id of the pass you wish to retrieve.

Add Locations to Pass

POST /v1/pass/(passId)/locations
 
POST /v1/pass/id/(externalId)/locations

Add the locations to the specified pass

Example request:

POST /v1/pass/123/locations HTTP/1.1
{
   "locations":[
      {
         "longitude":"-122.374",
         "latitude":"37.618",
         "relevantText":"Hello loc0",
         "streetAddress1":"address line #1",
         "streetAddress2":"address line #2",
         "city":"Palo Alto",
         "region":"CA",
         "regionCode":"94404",
         "country":"US"
      },
      { "..." },
   ]
}

Example Response:

The API will return status code 200 if successful.

[
   {
      "passLocationId":65,
      "value":{
         "region":"CA",
         "regionCode":"94404",
         "relevantText":"Hello loc0!",
         "streetAddress1":"add11",
         "streetAddress2":"add22",
         "longitude":"-122.3742",
         "latitude":"37.618",
         "city":"FC"
      }
   },
   {
      "passLocationId":66,
      "value":{
         "region":"CA",
         "regionCode":"94404",
         "relevantText":"Hello loc1!",
         "streetAddress1":"add12",
         "streetAddress2":"add23",
         "longitude":"-123.374",
         "latitude":"38.618",
         "city":"FC"
      }
   }
]


JSON Parameters:
  • passId – The id of the pass you want to add locations to.
  • externalId – The external id of the pass you want to add locations to.
  • longitudeRequired Longitude of the location.
  • latitudeRequired Latitude of the location.
  • relevantText – Text to display to the user when close to this location.
  • streetAddress1 – Street Address
  • streetAddress2 – Street Address (continued)
  • city – City that the address is in
  • region – Region (state) that the address is in
  • regionCode – Postal code for this location
  • country – Country that the location is in

Delete Location from Pass

DELETE /v1/pass/(passId)/location/(locationId)
 
DELETE /v1/pass/id/(externalId)/location/(locationId)

Delete the specified location from the specified pass.

Example request:

DELETE /v1/pass/123/location/456 HTTP/1.1


Query Parameters:
  • passId – The id of the pass you want to delete the location from
  • externalId – The external id of the pass you want to delete the location from
  • locationId – The id of the location you want to delete from the pass
Status Codes:
  • 200 – Success

Delete Pass

DELETE /v1/pass/(passId)
 
DELETE /v1/pass/id/(externalId)

Delete the specified pass.

Example request:

DELETE /v1/pass/123 HTTP/1.1

Example response:

{
    "Status":"Deleted",
    "PassID":"1274"
}


Query Parameters:
  • passId – The id of the pass you wish to delete.
  • externalId – The external id of the pass you wish to delete.
Status Codes:
  • 200 – Success

Tags

Add Tags to Pass

PUT /v1/pass/(passId)/tags
 
PUT /v1/pass/id/(externalId)/tags

Add tags to the specified pass.

Example request:

PUT /v1/pass HTTP/1.1


Query Parameters:
  • passId – The id of the pass you want to add tags to.
  • externalId – The external id of the pass you want to add tags to.

Sample Request Body:

{
    "tags": ["aaa-bbb-ccc"]
}

Example response:

{
   "newTags":[
      "aaa-bbb-ccc"
   ],
   "mappings":1
}


JSON Parameters:
  • newTags – The tags that were added to this pass. Doesn’t count tags that were requested to be added but already existed on the pass.
  • mappings – The number of tags added to the pass.

CURL Example:

curl -X put https://verizonventures-prod.apigee.net/ua-wallet/v1/pass/1274/tags -H "Authorization: Basic [Base64_KEY]" -H
"Api-Revision:1.2" -d 'json={"tags": ["aaa-bbb-ccc"]}'

List Tags for Pass

GET /v1/pass/(passId)/tags
 
GET /v1/pass/id/(externalId)/tags

Get the tags that the specified pass is a member of.

Example request:

GET /v1/pass/123/tags HTTP/1.1


Query Parameters:
  • passId – The id of the pass you wish to retrieve.
  • externalId – The external id of the pass you wish to retrieve.

Example response:

{
   "tags":[
      {
         "id":72,
         "createdAt":"2013-07-10 11:38:06.0",
         "name":"tag-2971-4280-479"
      },
      {
         "id":73,
         "createdAt":"2013-07-10 11:52:20.0",
         "name":"tag-1049-2951-9529"
      },
      {
         "id":74,
         "createdAt":"2013-07-10 11:59:32.0",
         "name":"tag-385-9612-723"
      },
      {
         "id":75,
         "createdAt":"2013-07-10 12:00:18.0",
         "name":"tag-5784-6282-8767"
      },
      {
         "id":76,
         "createdAt":"2013-07-10 12:00:55.0",
         "name":"tag-1050-1982-8211"
      },
      {
         "id":77,
         "createdAt":"2013-07-10 12:02:09.0",
         "name":"tag-5040-8715-7744"
      }
   ]
}

List All Tags

GET /v1/tag

List all tags.

Example request:

GET /v1/tag HTTP/1.1


Query Parameters:
  • pageSize – Number of tags per page.
  • page – Page you want to retrieve, starting with 1.
  • order – The order you want the tags returned in. Can be any one of id, createdAt or updatedAt; default is id
  • direction – Whether you want the values ordered ascending or descending. Can be either asc or desc, default is asc.

Example response:

{
   "tags":[
      {
         "id":2,
         "tag":"Gold"
      },
      {
         "id":3,
         "tag":"Silver"
      },
      {
         "id":4,
         "tag":"Platinum"
      },
      {
         "id":5,
         "tag":"Enterprise"
      }
   ],
   "Pagination":{
      "order":"ID",
      "page":1,
      "start":0,
      "direction":"DESC",
      "pageSize":10
   },
   "count":4
}

CURL example:

curl https://verizonventures-prod.apigee.net/ua-wallet/v1/tag -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2"

List Passes for Tag

GET /v1/tag/(tag)/passes

List the passes on this tag.

Example request:

GET /v1/tag/ABCDEFG-12345/passes HTTP/1.1


Query Parameters:
  • tag – The tag that you want the passes for.
  • pageSize – Number of tags per page.
  • page – Page you want to retrieve, starting with 1.
  • order – The order you want the tags returned in. Can be any one of id, createdAt or updatedAt, default is id.
  • direction – Whether you want the values ordered ascending or descending. Can be either asc or desc, default is asc.

Example response:

{
   "count":28,
   "passes":[
      {

         "id":"635",
         "templateId":"1",
         "updatedAt":"2013-03-29T01:19:12.000Z",
         "createdAt":"2013-03-26T21:51:50.000Z",
         "serialNumber":"bac32f59-18bb-41d6-a450-813ae28fccba",
         "externalId":"external1",
         "url":"https:\/\/localhost\/v1\/pass\/635\/download"
      },
      {
         "id":"636",
         "templateId":"1",
         "updatedAt":"2013-03-29T01:19:12.000Z",
         "createdAt":"2013-03-26T21:52:00.000Z",
         "serialNumber":"0533ab08-271b-453f-998a-66d51fe40aa2",
         "externalId":"external2",
         "url":"https:\/\/localhost\/v1\/pass\/636\/download"
      },
      {
         "id":"637",
         "templateId":"1",
         "updatedAt":"2013-03-29T01:19:12.000Z",
         "createdAt":"2013-03-26T21:52:35.000Z",
         "serialNumber":"e83e28cb-6429-43d6-96ee-55e39f294117",
         "externalId":"external3",
         "url":"https:\/\/localhost\/v1\/pass\/637\/download"
      },
      {
         "id":"641",
         "templateId":"1",
         "updatedAt":"2013-03-29T01:18:42.000Z",
         "createdAt":"2013-03-28T21:24:17.000Z",
         "serialNumber":"94129123-b86b-4caa-8a6a-4b01a132e33a",
         "url":"https:\/\/localhost\/v1\/pass\/641\/download"
      },
      {
         "id":"665",
         "templateId":"1",
         "updatedAt":"2013-03-29T22:35:45.000Z",
         "createdAt":"2013-03-29T22:35:43.000Z",
         "serialNumber":"9d916ffe-c481-46d3-8433-5ddf06a5e28f",
         "externalId":"EXTERNAL_1",
         "url":"https:\/\/localhost\/v1\/pass\/665\/download"
      }
   ],
   "pagination":{
      "order":"createdAt",
      "page":1,
      "start":0,
      "direction":"ASC",
      "pageSize":5
   }
}

CURL example:

curl https://verizonventures-prod.apigee.net/ua-wallet/v1/tag/tag-name/passes -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2"

Update Passes by Tag

PUT /v1/tag/(tag)/passes

Update all of the passes on a tag.

Example request:

PUT /v1/tag/GOLD/passes HTTP/1.1

Sample Request Body:

{
    "fields":{
        "secondary1":{
            "value":"12/31/2013"
        },
        "primary1":{
            "value":"$2 Off"
        }
    }
}


Query Parameters:
  • tag – The tag you wish to update the passes for
JSON Parameters:
  • fields – A JSON Object containing the fields you want to update on the passes.

Example response:

{
   "ticketId":732
}

CURL example:

curl -X PUT https://verizonventures-prod.apigee.net/ua-wallet/v1/tag/GOLD/passes -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2" -d 'json={"fields":{"secondary1":{"value":"12/31/2013"},"primary1":{"value":"$2 Off"}}}'

Remove Tag from Pass

DELETE /v1/tag/(tag)/pass/(passId)
 
DELETE /v1/tag/(tag)/pass/id/(externalId)

Remove the tag from the specified pass.

Example request:

DELETE /v1/tag/ABCDEFG-12345/pass/123 HTTP/1.1


Query Parameters:
  • tag – The tag you wish to remove the pass from
  • passId – The id of the pass you wish to remove from the tag
  • externalId – The external id of the pass you wish to remove from the tag

Example response:

CURL example:

curl -X DELETE https://verizonventures-prod.apigee.net/ua-wallet/v1/tag/GOLD/pass/123 -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2"

Remove Tag from All Passes

DELETE /v1/tag/(tag)/passes

Remove this tag from all of its passes.

Example request:

DELETE /v1/tag/ABCDEFG-12345/passes HTTP/1.1


Query Parameters:
  • tag – The tag you wish to remove all passes from.

Example response:

{
   "count":38,
   "status":"success",
   "tagId":2
}

CURL example:

curl -X DELETE https://verizonventures-prod.apigee.net/ua-wallet/v1/tag/ABC-123/passes -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2"

Delete Tag

DELETE /v1/tag/(tag)

Delete the specified tag and remove it from all passes.

Example request:

DELETE /v1/tag/ABCDEFG-12345 HTTP/1.1


Query Parameters:
  • tag – The tag you wish to delete

Example response:

{
    "status":"success",
    "tagId":5,
    "count":93
}

CURL example:

curl -X DELETE https://verizonventures-prod.apigee.net/ua-wallet/v1/tag/ABC-123 -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2"

Tickets

Get Ticket Status

GET /v1/ticket/(ticketId)

Get the status of a ticket

Example request:

GET /v1/ticket/12345 HTTP/1.1


Query Parameters:
  • ticketId – The id of the ticket you want the status for

Example response:

{
   "Status":"COMPLETED",
   "createdAt":2013-03-28 18:18:36.0,
   "ID":123,
   "children":{
      "..."
   }
}

CURL example:

curl https://verizonventures-prod.apigee.net/ua-wallet/v1/ticket/123 -H "Authorization: Basic [Base64_KEY]" -H "Api-Revision:1.2"

Get System Status

GET /v1/system/status

Check if a connection can be made to the Wallet Studio API.

Example request:

GET /v1/system/status HTTP/1.1

Example response:

{
    "Hello": "World"
}


JSON Parameters:
  • Hello – { “Hello”: “World” } response available solely for communication/status checks
-->