Reach API

Attention

Urban Airship Wallet is now Urban Airship Reach. Though the product name has changed, the features and functionality remain the same. All /wallet-api.urbanairship.com/ endpoints will continue to function as before. For more information about Urban Airship Reach, please see our news release.

Version 1.2 of the Urban Airship Reach API supports Apple Wallet and Android Pay.

Overview

Here’s what you need to do to get started with the Urban Airship Reach 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 Platform Management section of Account Settings. See: Credentials: Apple Wallet to learn how to generate a certificate.
  4. Create a Project using the Reach 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 templates.

Passes can then be:

  • Created with your custom data.
  • Completely changed and re-added to an existing user’s Apple Wallet or Android Pay.
  • 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.

A project may include a number of templates. You can also have tags that apply to one or more passes.

Specifying a Version

The current version of the Reach API is 1.2. The versioning for the Reach API is currently distinct from the versioning for the Urban Airship Engage API.

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.2 is for the /v1 API, revision 2.

Example

curl -X POST "https://wallet-api.urbanairship.com/v1/pass/12345" \
   -H "Authorization: Basic <Base64 key>" \
   -H "Api-Revision: 1.2" \
   -H "Content-Type: application/json" \
   -d '{"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 Reach 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. Here’s an example for how you might get this in bash (may vary based on your system setup):
echo -n "[YOUR_EMAIL]:[YOUR_KEY]" | base64
  • The authorization method and a space are then added before the encoded string i.e “Basic ”.
curl -X POST "https://wallet-api.urbanairship.com/v1/pass/12345" \
    -H "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" \
    -H "Api-Revision: 1.2" \
    -H "Content-Type: application/json" \
    -d '{"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

HTTP Response Codes

400 Invalid Request Parameters
This error happens when basic input parameters checks fail, such as a data types mismatch.
401 Unauthorized
The authentication check failed.
406 Not Acceptable Request
This error happens on higher-level validation checks, such as if a required input field is missing, and a list of field-level errors are then returned in 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 for error codes 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 API key which we provide to you in your Reach dashboard. It is your responsibility to keep this key well-guarded as it represents your identity.
  • You will use your own Apple or Android Pay certificate to sign production passes.

Projects

Create Project

POST /v1/project
POST /v1/project/id/(projectExternalId)

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

Example request:

POST /v1/project HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
  "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"
  }
}
curl -X POST https://wallet-api.urbanairship.com/v1/project \
    -H "Authorization: Basic <Base64 key>" \
    -H "Content-Type: application/json" \
    -H "Api-Revision: 1.2" \
    -d '{
          "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:
  • projectExternalId – The external ID you wish to use for the project.
JSON Parameters:
  • nameRequired. The name of the project.
  • projectTypeRequired. The project type, can be any one of loyalty, coupon, giftCard, memberCard, eventTicket, boardingPass, generic.
  • descriptionRequired. The description of the project.

Example response:

{
  "updatedAt": "2013-07-01T19:57:36.190Z",
  "id": "12345",
  "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"
}

Get Project

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

Get the project with the specified ID.

Example request:

GET /v1/project/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/project/12345 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • projectId – The ID of the project you are looking for.
  • projectExternalId – The external ID of the project you are looking for.

Example response:

{
  "updatedAt": "2013-06-27T20:55:06.000Z",
  "id": "12345",
  "templates": [
    {
      "vendor": "Apple",
      "projectType": "loyalty",
      "projectId": "12345",
      "type": "Store Card",
      "vendorId": "1",
      "deleted": "False",
      "id": "1234",
      "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": "12345",
      "type": "Loyalty1",
      "vendorId": "2",
      "deleted": "False",
      "id": "1235",
      "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": "12345",
    "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
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/project \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • pageSize – Number of projects per page, default is 10.
  • 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 DESC.

Example response:

{
  "projects":[
    {
      "updatedAt": "2013-06-27T20:55:06.000Z",
      "id": "12345",
      "description": "Aztec Barcode",
      "createdAt": "2013-06-27T20:51:02.000Z",
      "settings": {
        "id": "12345",
        "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": "12346",
      "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
  }
}

Update Project

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

Update the human-friendly name and/or description of a project.

Example request:

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

{
  "name": "New And Improved Name",
  "description": "Significantly more detailed description"
}
curl -X PUT https://wallet-api.urbanairship.com/v1/project/10058 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Content-Type: application/json" \
    -H "Api-Revision: 1.2" \
    -d '{
          "name": "New And Improved Name",
          "description": "Significantly more detailed description"
        }'
Query Parameters:
  • projectId – The ID of the project you wish to update.
  • projectExternalId – The external ID of the project you wish to update.
JSON Parameters:
  • nameOptional. Provide the new name for the project.
  • descriptionOptional. Provide the new description of the project.

Example response:

{
  "updatedAt": "2013-07-01T19:57:36.000Z",
  "id": 12345,
  "templates": [
  ],
  "description": "Significantly more detailed description",
  "createdAt": "2013-07-01T19:57:36.000Z",
  "settings": {
  },
  "name": "New And Improved Name",
  "projectType": "loyalty"
}

Templates

If you are creating one template from another, or updating a template based on the response from a “Get Template” call, please note that the “Create Template” and “Update Template” calls expect a different data structure than what “Get Template” returns. Depending on your project type and the particulars of your template, you may also have different keys than the examples below. Please see the detailed examples in individual sections for examples of standard metadata keys and other typical keys for each platform.

Create and Update Template request simplified JSON example:

  • Apple
  • Google (Loyalty)
{
   "userlocations":{},
   "headers":{},
   "fields":{},
   "beacons":[],
   "metadatakey1": "value",
   "metadatakey2": "value"
}
{
   "userlocations":{},
   "headers":{},
   "linksModuleData":{},
   "pointsModule":{},
   "titleModule":{},
   "infoModuleData":{},
   "textModulesData":{},
   "imageModulesData":{},
   "notAssigned":{},
   "acctModule":{},
   "metadataKey1": "value",
   "metadataKey2": "value"
}

Get Template response simplified JSON example:

  • Apple
  • Google (Loyalty)
{
   "userlocations":{},
   "fieldsModel":{
      "headers":{},
      "fields":{},
      "beacons":[]
   },
   "templateHeader":{
      "metadatakey1": "value",
      "metadatakey2": "value"
   }
}
{
   "userlocations":{},
   "fieldsModel":{
      "headers":{},
      "linksModuleData":{},
      "pointsModule":{},
      "titleModule":{},
      "vendor":"Google",
      "infoModuleData":{},
      "textModulesData":{},
      "imageModulesData":{},
      "notAssigned":{},
      "acctModule":{}
   },
   "templateHeader":{
      "metadataKey1": "value",
      "metadataKey2": "value"
   }
}

Note

Some values received in Get Template responses may need to be modified before being passed back in Create/Update Template calls. If this is the case, the API will respond with an error message that includes the location of the issue. For example, values that begin with “PK” for the “numberStyle” key, such as “PKNumberStyleDecimal”, need to be modified to remove “PK” and lowercase the first character (“numberStyleDecimal”).

Create Template

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

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

Example request:

  • Apple
  • Google
POST /v1/template HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
  "headers": {
    "logo_color": {
      "formatType":1,
      "fieldType":"topLevel",
      "value":"rgb(24,86,148)"
    },
    "icon_image":{
      "formatType":1,
      "fieldType":"image",
      "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/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_prod\/1\/images\/default-pass-logo.png"
    },
    "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":1234,
  "type":"Store Card",
  "vendorId":1,
  "deleted":"False",
  "description":"Description",
  "name":"Loyalty Card",
  "disabled":"False"
}
curl -X POST https://wallet-api.urbanairship.com/v1/template \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
          "headers": {
            "logo_color": {
              "formatType":1,
              "fieldType":"topLevel",
              "value":"rgb(24,86,148)"
            },
            "icon_image":{
              "formatType":1,
              "fieldType":"image",
              "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/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_prod\/1\/images\/default-pass-logo.png"
            },
            "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":1234,
          "type":"Store Card",
          "vendorId":1,
          "deleted":"False",
          "description":"Description",
          "name":"Loyalty Card",
          "disabled":"False"
        }'
POST /v1/template HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
  "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_prod\/1\/images\/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"
}
curl -X POST https://wallet-api.urbanairship.com/v1/template \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
          "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_prod\/1\/images\/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"
        }'
Query Parameters:
  • templateExternalId – 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 Response:

{
   "templateId": 12345
}

Note

See the Reach Reference for image size specifications.

Get Template

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

Get the template specified by the ID.

Example request:

GET /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/template/12345 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • templateId – The ID of the template you wish to retrieve.
  • templateExternalId – The external ID of the template you wish to retrieve.

Example response:

  • Apple
  • Google
{
   "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_prod\/1\/images\/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_prod\/1\/images\/default-pass-logo.png"
         },
         "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":1234,
      "type":"Store Card",
      "vendorId":1,
      "deleted":"False",
      "id":"12345",
      "updatedAt":"2013-07-01T18:28:33.000Z",
      "description":"Description",
      "createdAt":"2013-07-01T18:28:33.000Z",
      "name":"Loyalty Card",
      "disabled":"False"
   }
}
{
   "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_prod\/1\/images\/default-titlestring.png",
            "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":1234,
      "type":"Loyalty1",
      "vendorId":2,
      "deleted":"False",
      "id":"12345",
      "updatedAt":"2013-06-25T18:00:31.000Z",
      "description":"description",
      "createdAt":"2013-02-01T09:02:03.000Z",
      "name":"Loyalty Card",
      "disabled":"False"
   }
}

Update Template

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

Update the specified template. You can also add or remove fields from the template with this call by adding or omitting those fields.

Warning

You should include all keys and fields that you wish to keep in the template when updating it, otherwise they may be removed.

Example request:

  • Apple
  • Google
PUT /v1/template/12345 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
   "headers":{
      "logo_color":{
         "formatType":"1",
         "fieldType":"topLevel",
         "value":"rgb(24,86,148)"
      },
      "icon_image":{
         "formatType":"1",
         "fieldType":"image",
         "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/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_prod\/1\/images\/default-pass-logo.png"
      },
      "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":"1234",
   "type":"Store Card",
   "vendorId":"1",
   "deleted":"False",
   "description":"Description",
   "name":"Loyalty Card (Edited)",
   "disabled":"False"
}
curl -X PUT https://wallet-api.urbanairship.com/v1/template/12345 \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
           "headers":{
              "logo_color":{
                 "formatType":"1",
                 "fieldType":"topLevel",
                 "value":"rgb(24,86,148)"
              },
              "icon_image":{
                 "formatType":"1",
                 "fieldType":"image",
                 "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/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_prod\/1\/images\/default-pass-logo.png"
              },
              "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":"1234",
           "type":"Store Card",
           "vendorId":"1",
           "deleted":"False",
           "description":"Description",
           "name":"Loyalty Card (Edited)",
           "disabled":"False"
        }'
PUT /v1/template/12345 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
   "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_prod\/1\/images\/default-titlestring.png",
            "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"
   }
}
curl -X PUT https://wallet-api.urbanairship.com/v1/template/12345 \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
           "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_prod\/1\/images\/default-titlestring.png",
                    "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"
           }
        }'
Query Parameters:
  • templateId – The ID of the existing template that you want to update
  • templateExternalId – The external ID of the existing template that you want to update

Example response:

{
   "templateId":"12345"
}

Duplicate Template

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

/v1/template/duplicate/(templateId) duplicates the specified template and put it in the same project. /v1/template/duplicate/id/(templateExternalId) 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
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X POST https://wallet-api.urbanairship.com/v1/template/duplicate/12345 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -H "Content-Length: 0"
Query Parameters:
  • templateId – The ID of the existing template that you want to duplicate
  • templateExternalId – The external ID of the existing template that you want to duplicate

Example response:

{
   "templateId": 12346
}

Add Locations to Template

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

Add locations to the specified template.

Example request:

POST /v1/template/12345/locations HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
   "locations":[
      {
         "longitude":-122.374,
         "latitude":37.618,
         "relevantText":"Hello loc0",
         "streetAddress1":"address line #1",
         "streetAddress2":"address line #2",
         "city":"Palo Alto",
         "region":"CA",
         "regionCode":"94404",
         "country":"US"
      }
   ]
}
curl -X POST https://wallet-api.urbanairship.com/v1/template/12345/locations \
    -H "Authorization: Basic <Base64 key>" \
    -H "Content-Type: application/json" \
    -H "Api-Revision: 1.2" \
    -d '{
           "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.
  • templateExternalId – The external ID of the template to which you are adding locations.
JSON Parameters:
  • longitudeRequired: Longitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
  • latitudeRequired: Latitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
  • 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/(templateExternalId)/location/(locationId)

Delete location from template.

Example request:

DELETE /v1/template/123/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X DELETE https://wallet-api.urbanairship.com/v1/template/123/location/456 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • templateId – The ID of the template you’d like to delete a location from.
  • templateExternalId – 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.

List Templates

GET /v1/template/headers

List the headers for templates belonging to you.

Example request:

GET /v1/template/headers HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/template/headers
    -H "Authorization: Basic <Base64 key>"
    -H "Api-Revision: 1.2"
Query Parameters:
  • pageSize – Number of projects per page, default is 10.
  • page – Page you want to retrieve, default is 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 DESC.

Example response:

{
   "count": "133",
   "templateHeaders": [
      {
         "vendor": "Google",
         "projectType": "memberCard",
         "projectId": "12345",
         "type": "Loyalty1",
         "vendorId": "2",
         "deleted": "False",
         "id": "12344",
         "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": "12346",
         "type": "Store Card",
         "vendorId": "1",
         "deleted": "False",
         "id":"12345",
         "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"
   }
}

Delete Template

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

Delete the specified template.

Example request:

DELETE /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X DELETE https://wallet-api.urbanairship.com/v1/template/12345 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • templateId – The ID of the template you wish to delete.
  • templateExternalId – The external ID of the template you wish to delete.

Example response:

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

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 passExternalId. 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.

Note

Calls to create Android Pay passes must include the “fields” key.

Example request:

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

{
    "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"
    }
}
curl -X POST https://wallet-api.urbanairship.com/v1/pass/123 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Content-Type: application/json" \
    -H "Api-Revision: 1.2" \
    -d '{
           "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": 12345,
    "templateId": 123,
    "createdAt":"2012-11-01 12:37:07.0",
    "url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/888\/download",
    "publicUrl":{
          "path":"https:\/\/wallet-api.urbanairship.com\/v1\/download\/pass\/9c9c9c7d-c6b6-9c9c-9d2b-9c9c9c54c89c",
          "used":false,
          "type":"Single",
          "installs":0
    },
    "passFields": {
        "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:

Required for Android. Optional on iOS to request a publicly accessible URL for the pass

  • type - single or multiple use, depending on how many times it can be downloaded. All Android pass URLs are single. multiple only applicable on iOS.
  • path - Pass URL returned in response
  • used - Returns true or false for iOS, N/A for Android
  • installs - Returns number of pass installs for a multiple use iOS pass, N/A for Android

Pass Deep Linking

In order for a user to download a pass that you have created, you must provide a URL to facilitate the download. From the user’s perspective, the outcome is the same on either iOS or Android—the pass is downloaded directly to either the Apple Wallet or Android Pay app. In the Urban Airship Reach API however, there are minor differences worth calling out below.

Android Deep Linking

For Android, we refer to the create pass »» user downloads pass to Android Pay flow as deep linking, because the URL returned in the response deep links to the Google Play store with user credentials. iOS behavior is slightly different, as described below.

Specify a single publicUrl in the create pass request, as described above.

For passes pointing to Android templates, you will receive a very long URL in the response; here is a shortened example of the publicUrl that is returned:

 {
    "publicUrl":{
       "path":"https:\/\/goo.gl\/app\/pay?link=https:\/\/www.android.com\/payapp\/savetoandroidpay\/some-_ver_long_URL&apn=com.google.android.apps.walletnfcrel&amv=930006084&pcampaignid=s2ap_2931580989855247863.android_template_test_50827",
       "type":"Single"
    },
    "id":"12345",
    "templateId":"123456",
    "fields":{
       "image":{
          "title.string":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-coupon-logo.png",
          "hideEmpty":false,
          "formatType":"String",
          "fieldType":"titleModule",
          "description.string":"Logo Image"
       }
    }
 }

The URL provides a deep link from Google into the Android Pay app so that the pass can be downloaded directly without requiring a browser window to facilitate the request.

Warning

If you do not specify "publicUrl": {"type": "single"} in the request, no URL will be created which means the pass will be inaccessible.

iOS Pass Downloads

On iOS you can specify either a single or multiple use publicUrl. Failure to include the publicUrl parameter results in a URL that requires the API key to download a pass.

iOS URLs aren’t technically deep links; they point to a stored pkpass file.

Get Pass

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

Get the specified pass.

Example request:

GET /v1/pass/1234 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/pass/1234 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"

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_prod\/1\/images\/default-pass-icon.png",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "barcode_value":{
         "formatType":"String",
         "changeMessage":null,
         "fieldType":"barcode",
         "value":"123456789",
         "label":"",
         "required":false,
         "hideEmpty":false
      },
      "logo_text":{
         "formatType":"String",
         "changeMessage":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
      },
      "relevantDate":{
         "changeMessage":null,
         "label":"relevantDate",
         "hideEmpty":false,
         "formatType":"String",
         "value":"2015-12-31T23:00:00-08:00",
         "fieldType":"topLevel",
         "required":false
      }
   },
   "id":"1234",
   "templateId":"12345",
   "updatedAt":"2013-06-19T01:06:23.000Z",
   "createdAt":"2013-06-19T01:06:17.000Z",
   "serialNumber":"14f94898-2f5e-46f5-925c-7e29fa9a0508",
   "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
      },
      "Seat":{
         "textAlignment":"textAlignmentNatural",
         "changeMessage":"",
         "numberStyle":"PKNumberStyleDecimal",
         "label":"Seat",
         "hideEmpty":false,
         "formatType":"Number",
         "value":1.0,
         "fieldType":"auxiliary",
         "required":false,
         "order":3
      },
      "Row":{
         "textAlignment":"textAlignmentNatural",
         "changeMessage":"",
         "numberStyle":"PKNumberStyleDecimal",
         "label":"Row",
         "hideEmpty":false,
         "formatType":"Number",
         "value":1.0,
         "fieldType":"auxiliary",
         "required":false,
         "order":2
      },
      "Section":{
         "textAlignment":"textAlignmentLeft",
         "changeMessage":"",
         "label":"Section",
         "hideEmpty":false,
         "formatType":"String",
         "value":"1",
         "fieldType":"auxiliary",
         "required":true,
         "order":1
      }
   }
}
JSON Parameters:
  • passId – The ID of the pass you wish to retrieve.
  • passExternalId – The external ID of the pass you wish to retrieve.

List Passes

GET /v1/pass
GET /v1/pass?templateId=(id)
GET /v1/template/(templateId)/passes

List your passes. When using the /v1/pass endpoint, the templateId specification is optional. The /v1/template/ endpoint however, requires a templateId.

Example request:

GET /v1/pass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/pass \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • templateId – integer (optional) - Return passes associated with a specific template.
  • status

    string (optional) - Filter the returned passes based on install status. Valid status values include:

    • "installed": all installed passes
    • "uninstalled": all uninstalled passes
    • "been_installed": all passes that have at one point been installed
    • "not_been_installed": all passes that have never been installed
  • pageSize – string (optional) - Number of passes per page, default 10.
  • page – string (optional) - Page you wish to retrieve, starting with 1.
  • order – string (optional) - The order you want the passes returned in. Can be any one of id, createdAt, or updatedAt. Default is id.
  • direction – string (optional) - Whether you want the values ordered ascending or descending. Can be either ASC or DESC, default is DESC.

Example response:

{
   "count":1043,
   "passes":[
      {
         "id":"12345",
         "templateId":"12345",
         "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":"12346",
         "templateId":"12346",
         "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": 2
   }
}

Update Pass

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

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

Note

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

Example request:

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

{
    "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"
       }
    ]
}
curl -X PUT https://wallet-api.urbanairship.com/v1/pass/123 \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
            "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"
               }
            ]
        }'
JSON Parameters:
  • passId – The ID of the pass you wish to update.
  • passExternalId – 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.

Note

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

Example response:

{
    "ticketId": 1234
}

Bulk Update Passes (iOS Only)

Warning

Changes will only affect the following shared fields on your customers passes:

  • logo
  • colors
  • full width image
  • all fields on the back of the pass

Contact your Urban Airship Technical Account Manager before using the bulk update API.

PUT /v1/template/(templateId)/passes
PUT /v1/template/(passExternalId)/passes

In order to update all passes for a given template, make a PUT call to one of the above endpoints, passing the templateId or passExternalId.

The response will be a ticketId for the bulk update.

Example request:

PUT /v1/template/(templateId)/passes HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
   "fields": {
      "Member Name": {
         "value": "Jack Handey"
      },
      "barcode_value": {
         "value": "55555"
      },
      "Points": {
         "value": 1000
      }
   }
}
curl -X PUT https://wallet-api.urbanairship.com/v1/template/(templateId)/passes \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
           "fields": {
              "Member Name": {
                 "value": "Jack Handey"
              },
              "barcode_value": {
                 "value": "55555"
              },
              "Points": {
                 "value": 1000
              }
           }
        }'
JSON Parameters:
  • templateId – The ID of the template for which you are updating all passes.
  • passExternalId – Alternative to templateId if you are referencing an external template ID

Example response:

{
   "ticketId": 56789
}

To query the ticketId, see below.

Query Ticket ID

GET /v1/template/ticket/(ticketId)

Query the status of a ticketId received in the bulk update response.

Example response:

{
   "Status": "COMPLETED",
   "createdAt":"2016-12-28 21:53:34.0",
   "ID":66644895,
   "children":{
   }
}

Expire Pass

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

Example request (update expiration date):

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

{
    "headers": {
        "expirationDate": {
            "value": "2014-08-20T9:41-08:00"
        }
    },
    "fields": {
        "Seat": {
            "value": "26E"
        }
    }
}
curl -X PUT https://wallet-api.urbanairship.com/v1/pass/123 \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
            "headers": {
                "expirationDate": {
                    "value": "2014-08-20T9:41-08:00"
                }
            },
            "fields": {
                "Seat": {
                    "value": "26E"
                }
            }
        }'

Example (render pass void):

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

{
    "headers": {
        "expirationDate": {
            "label": "voided"
        }
    },
    "fields": {
        "Seat": {
            "value": "26E"
        }
    }
}
curl -X PUT https://wallet-api.urbanairship.com/v1/pass/123 \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
            "headers": {
                "expirationDate": {
                    "label": "voided"
                }
            },
            "fields": {
                "Seat": {
                    "value": "26E"
                }
            }
        }'

Get Apple JSON for a Pass

GET /v1/pass/(passId)/viewJSONPass
GET /v1/pass/id/(passExternalId)/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
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/pass/123/viewJSONPass \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"

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 Reach",
            "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
  • passExternalId – The external ID of the pass you wish to retrieve

Download Apple Pass Contents

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

Download the contents of an Apple Wallet .pkpass file with the specified ID as a zipped file. You will want to direct the output to a file with a .zip extension. This is a utility API to help debug your passes.

Example request:

GET /v1/pass/123/download HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/pass/123/download \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
JSON Parameters:
  • passId – The ID of the pass you wish to retrieve.
  • passExternalId – The external ID of the pass you wish to retrieve.

Google Save to Android Pay

POST /v1/pass/(templateId)/saveToWallet

Create a pass from the specified template and prepares to save to Android Pay. Returns JavaScript example code for you to use for a “Save to Android Pay” button.

Example request:

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

{
  "fields": {
    "Points": {
      "value": "600"
    }
  },
  "tag": "abc",
  "externalId": "UserName",
  "onSuccess": "mySuccessFunc()",
  "onFail": "myFailureFunc()"
}
curl -X POST https://wallet-api.urbanairship.com/v1/pass/123/saveToWallet \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
          "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 to be added to the pass
  • externalId – An ID that can be used to update the pass 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 pass is successfully added to Android Pay
  • onFail – JavaScript function you create that is called when the card fails to be added to Android Pay

Add Locations to Pass

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

Add the locations to the specified pass

Example request:

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

{
  "locations": [
    {
      "longitude": "-122.374",
      "latitude": "37.618",
      "relevantText": "Hello loc0",
      "streetAddress1": "address line #1",
      "streetAddress2": "address line #2",
      "city": "Palo Alto",
      "region": "CA",
      "regionCode": "94404",
      "country": "US"
    },
    { "...": "..." }
  ]
}
curl -X POST https://wallet-api.urbanairship.com/v1/pass/123/locations \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
          "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.
  • passExternalId – The external ID of the pass you want to add locations to.
  • longitudeRequired Longitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
  • latitudeRequired Latitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
  • 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/(passExternalId)/location/(locationId)

Delete the specified location from the specified pass.

Example request:

DELETE /v1/pass/123/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X DELETE https://wallet-api.urbanairship.com/v1/pass/123/location/456 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • passId – The ID of the pass you want to delete the location from.
  • passExternalId – 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/(passExternalId)

Delete the specified pass.

Example request:

DELETE /v1/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X DELETE https://wallet-api.urbanairship.com/v1/pass/123 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • passId – The ID of the pass you wish to delete.
  • passExternalId – The external ID of the pass you wish to delete.

Example response:

{
    "Status":"Deleted",
    "PassID":"123"
}
Status Codes:
  • 200 – Success

Tags

Add Tags to Pass

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

Add tags to the specified pass, limited to 15 tags per pass.

Example request:

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

{
    "tags": ["tag-name"]
}
curl -X PUT https://wallet-api.urbanairship.com/v1/pass/123/tags \
    -H "Authorization: Basic <Base64 key>" \
    -H "Content-Type: application/json" \
    -H "Api-Revision: 1.2" \
    -d '{
          "tags": ["tag-name"]
        }'
Query Parameters:
  • passId – The ID of the pass you want to add tags to.
  • passExternalId – The external ID of the pass you want to add tags to.

Example response:

{
  "newTags": ["tag-name"],
  "mappings":1
}
JSON Parameters:
  • newTags – The tags that were added to this pass. Does not include tags that you requested be added but already existed on the pass.
  • mappings – The number of tags added to the pass.

List Tags for Pass

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

Get the tags that the specified pass has.

Example request:

GET /v1/pass/123/tags HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/pass/123/tags \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • passId – The ID of the pass you wish to retrieve.
  • passExternalId – 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
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/tag \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • pageSize – Number of tags per page, default is 10.
  • page – Page you want to retrieve, starting with 1.
  • order – The order you want the tags returned in. Can be id or createdAt; default is id.
  • direction – Whether you want the values ordered ascending or descending. Can be either ASC or DESC, default is DESC.

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
}

List Passes for Tag

GET /v1/tag/(tag)/passes

List the passes with this tag.

Example request:

GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/tag/tag-name/passes \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • tag – The tag that you want the passes for.
  • pageSize – Number of tags per page, default 10.
  • 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 DESC.

Example response:

{
  "count": 28,
  "passes": [
    {
      "id": "10",
      "templateId": "20",
      "updatedAt": "2013-03-29T01:19:12.000Z",
      "createdAt": "2013-03-26T21:51:50.000Z",
      "serialNumber": "bac32f59-18bb-41d6-a450-813ae28fccba",
      "externalId": "12340",
      "url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/635\/download"
    },
    {
      "id": "11",
      "templateId": "21",
      "updatedAt": "2013-03-29T01:19:12.000Z",
      "createdAt": "2013-03-26T21:52:00.000Z",
      "serialNumber": "0533ab08-271b-453f-998a-66d51fe40aa2",
      "externalId": "12341",
      "url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/636\/download"
    },
    {
      "id": "12",
      "templateId": "22",
      "updatedAt": "2013-03-29T01:19:12.000Z",
      "createdAt": "2013-03-26T21:52:35.000Z",
      "serialNumber": "e83e28cb-6429-43d6-96ee-55e39f294117",
      "externalId": "12342",
      "url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/637\/download"
    },
    {
      "id": "13",
      "templateId": "23",
      "updatedAt": "2013-03-29T01:18:42.000Z",
      "createdAt": "2013-03-28T21:24:17.000Z",
      "serialNumber": "94129123-b86b-4caa-8a6a-4b01a132e33a",
      "url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/641\/download"
    },
    {
      "id": "14",
      "templateId": "24",
      "updatedAt": "2013-03-29T22:35:45.000Z",
      "createdAt": "2013-03-29T22:35:43.000Z",
      "serialNumber": "9d916ffe-c481-46d3-8433-5ddf06a5e28f",
      "externalId": "12344",
      "url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/665\/download"
    }
  ],
  "pagination": {
    "order": "createdAt",
    "page": 1,
    "start": 0,
    "direction": "ASC",
    "pageSize": 5
  }
}

Update Passes by Tag

PUT /v1/tag/(tag)/passes

Update all of the passes that have a given tag.

Example request:

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

{
    "fields":{
        "secondary1":{
            "value":"12/31/2013"
        },
        "primary1":{
            "value":"$2 Off"
        }
    }
}
curl -X PUT https://wallet-api.urbanairship.com/v1/tag/tag-name/passes \
    -H "Authorization: Basic <Base64_KEY>" \
    -H "Api-Revision: 1.2" \
    -d '{
          "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": 123
}

Remove Tag from Pass

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

Remove the tag from the specified pass.

Example request:

DELETE /v1/tag/tag-name/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X DELETE https://wallet-api.urbanairship.com/v1/tag/tag-name/pass/123 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • tag – The tag you wish to remove from the pass.
  • passId – The ID of the pass you wish to remove the tag from.
  • passExternalId – The external ID of the pass you wish to remove the tag from.

Example response:

{
   "passId":123,
   "status":"success",
   "tagId":70
}

Delete Tag

DELETE /v1/tag/(tag)

Delete the specified tag and remove it from all passes.

Example request:

DELETE /v1/tag/tag-name HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X DELETE https://wallet-api.urbanairship.com/v1/tag/tag-name \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
Query Parameters:
  • tag – The tag you wish to delete

Example response:

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

Statistics

The stats endpoint returns counts for the number of installed and uninstalled passes, either on a per-template or per-project basis.

Template Statistics

By Template ID

GET /v1/template/(templateId)/stats

Return template statistics for a given template ID.

Example Request

GET /v1/template/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/template/12345/stats \
   -H "Authorization: Basic <Base64 key>" \
   -H "Api-Revision: 1.2"
Query Parameters:
  • templateId – The template ID.

Example Response

{
    "id": 12345,
    "vendor": "Apple",
    "lastUpdated": "2015-10-01T20:15:28.000-07:00",
    "total": 7,
    "installed": 0,
    "uninstalled": 0
}
JSON Parameters:
  • id – The template ID.
  • vendor – The template vendor.
  • lastUpdated – The date the template was last updated.
  • total – The total number of passes generated from this template.
  • installed – The number of passes generated from this template that were installed.
  • uninstalled – The number of passes generated from this template that were uninstalled.

By Template External ID

GET /v1/template/id/(templateExternalId)/stats

Return template statistics for a given template external ID.

Example Request

GET /v1/template/id/ext_54321/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/template/id/ext_54321/stats \
   -H "Authorization: Basic <Base64 key>" \
   -H "Api-Revision: 1.2"
Query Parameters:
  • templateExternalId – The template external ID.

Example Response

{
    "id": 12345,
    "vendor": "Apple",
    "lastUpdated": "2015-10-01T20:15:28.000-07:00",
    "total": 7,
    "installed": 0,
    "uninstalled": 0
}

Template Activity

GET /v1/template/(templateId)/activity
GET /v1/template/(templateId)/activity/(startDate)/(endDate)
GET /v1/template/id/(templateExternalId)/activity
GET /v1/template/id/(templateExternalId)/activity/(startDate)/(endDate)

Returns template activities for a specified time period. If you omit the startDate and endDate, the response defaults to the past 30 days of activity, including today. The endpoint can target either a template ID or a template external ID.

Example Request

GET /v1/template/1234/activity/2015-08-19/2015-08-25 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/template/1234/activity/2015-08-19/2015-08-25 \
   -H "Authorization: Basic <Base64 key>" \
   -H "Api-Revision: 1.2"

Example Response

{
    "id": 1234,
    "vendor": "Apple",
    "startDate": "2015/08/19",
    "endDate": "2015/08/25",
    "summary": {
        "created": 113,
        "installed": 0,
        "uninstalled": 0
    },
    "details": [
        {
            "date": "2015/08/19",
            "activity": {
                "created": 111,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/20",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/21",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/22",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/23",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/24",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/25",
            "activity": {
                "created": 2,
                "installed": 0,
                "uninstalled": 0
            }
        }
    ]
}
JSON Parameters:
  • id – The template ID.
  • vendor – The template vendor.
  • startDate – The start date of the returned data.
  • endDate – The end date of the returned data.
  • summary

    An object containing the total number of passes created, installed, and uninstalled.

    created:The number of passes, generated from this template, that were created in this time period.
    installed:The number of passes, generated from this template, that were installed in this time period.
    uninstalled:The number of passes, generated from this template, that were uninstalled within this time period.
  • details – An array of template activity detail objects. Each object contains a date, and then the activity (passes created, installed, and uninstalled) that occurred on that day.

Project Statistics

By Project ID

GET /v1/project/(projectId)/stats

Return project statistics for a given project ID.

Example Request

GET /v1/project/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/project/12345/stats \
   -H "Authorization: Basic <Base64 key>" \
   -H "Api-Revision: 1.2"
Query Parameters:
  • ID – The project ID.

Example Response

{
    "id": 12345,
    "lastUpdated": "2015-10-01T20:15:29.000-07:00",
    "templates": [
        {
            "id": 1234
            "vendor": "Apple",
            "lastUpdated": "2015-10-01T20:15:29.000-07:00",
            "total": 2194,
            "installed": 2,
            "uninstalled": 7
        }
    ],
    "total": 2194,
    "installed": 2,
    "uninstalled": 7
}
JSON Parameters:
  • id – The project ID.
  • lastUpdated – The date the project was last updated.
  • templates – An array of template statistic objects.
  • total – The total number of passes generated by this project.
  • installed – The number of passes generated by this project that were installed.
  • uninstalled – The number of passes generated by this project that were uninstalled.

By Project External ID

GET /v1/project/id/(projectExternalId)/stats

Return project statistics for a given project external ID.

Example Request

GET /v1/project/id/ext_54321/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/project/id/ext_54321/stats \
   -H "Authorization: Basic <Base64 key>" \
   -H "Api-Revision: 1.2"
Query Parameters:
  • projectExternalId – The project external ID.

Example Response

{
    "id": 12345,
    "lastUpdated": "2015-10-01T20:15:29.000-07:00",
    "templates": [
        {
            "id": 1234,
            "vendor": "Apple",
            "lastUpdated": "2015-10-01T20:15:29.000-07:00",
            "total": 2194,
            "installed": 2,
            "uninstalled": 7
        }
    ],
    "total": 2194,
    "installed": 2,
    "uninstalled": 7
}

Project Activity

GET /v1/project/(projectId)/activity
GET /v1/project/(projectId)/activity/(startDate)/(endDate)
GET /v1/project/id/(projectExternalId)/activity
GET /v1/project/id/(projectExternalId)/activity/(startDate)/(endDate)

Returns project activities for a specified time period. If you omit the startDate and endDate, the response defaults to the past 30 days of activity, including today. The endpoint can target either a project ID or a project external ID.

Example Request

GET /v1/project/12345/activity/2015-08-19/2015-08-25 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/project/12345/activity/2015-08-19/2015-08-25 \
   -H "Authorization: Basic <Base64 key>" \
   -H "Api-Revision: 1.2"

Example Response

{
    "id": 12345,
    "startDate": "2015/08/19",
    "endDate": "2015/08/25",
    "summary": {
        "created": 113,
        "installed": 0,
        "uninstalled": 0
    },
    "details": [
        {
            "date": "2015/08/19",
            "activity": {
                "created": 111,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/20",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/21",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/22",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/23",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/24",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/25",
            "activity": {
                "created": 2,
                "installed": 0,
                "uninstalled": 0
            }
        }
    ]
}
JSON Parameters:
  • id – The project ID.
  • startDate – The start date of the returned data.
  • endDate – The end date of the returned data.
  • summary

    An object containing the total number of passes created, installed, and uninstalled.

    created:The number of passes, generated within this project, that were created in this time period.
    installed:The number of passes, generated within this project, that were installed in this time period.
    uninstalled:The number of passes, generated within this project, that were uninstalled within this time period.
  • details – An array of project activity detail objects. Each object contains a date, and then the activity (passes created, installed, and uninstalled) that occurred on that date.

Tickets

Get Ticket Status

GET /v1/ticket/(ticketId)

Get the status of a ticket

Path Parameter:
  • ticketId – The ID of the ticket you want the status for.

Example request:

GET /v1/ticket/123 HTTP/1.1
Authorization: Basic <Base64 key>
curl -X GET https://wallet-api.urbanairship.com/v1/ticket/123 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"

Example response:

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

Get System Status

GET /v1/system/status

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

Example request:

GET /v1/system/status HTTP/1.1
curl -X GET https://wallet-api.urbanairship.com/v1/system/status \
    -H "Api-Revision: 1.2"

Example response:

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

Cert Management

The certificate management API manages certificates for Apple Wallet.

Certificates are managed using the /v1/certificates/ endpoints and linked to templates through the template object endpoints /v1/template/.

A successful operation returns HTTP OK and a JSON response depending on the particular operation.

Add New Certificate

POST /v1/certificates/

Adds a new Apple Wallet certificate to the Reach system. If the specified certificate exists in our system, we will renew/update the existing one.

Example Request:

POST /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json

{
    "vendor" : "Apple",
    "name" : "editable name",
    "certificate" : "NTUtNDc2Ni1hMzI4LWEwOGU3YWI2ZDk3Mg==",
    "comment" : "something about this cert",
    "enabled" : true,
    "default" : false,
    "password" : "secret"
}

Example responses:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id":"40adce15-5c52-479d-8620-54c21cd851a6",
    "vendor": "Apple",
    "name":"editable name",
    "baseName":"internal cert name",
    "comment":"something about this cert",
    "teamIdentifier" : "XYZ",
    "enabled":true,
    "default":false,
    "createdAt":"2016-05-26T23:23:21Z",
    "updatedAt":"2016-05-26T22:23:21Z",
}
HTTP/1.1 400 BAD_REQUEST
Content-Type: application/json

{
    "error" : {
        "code": 123,
        "message":"descriptive error message"
    }
}
Status Codes:
  • 200 OK – The certificate was added successfully (see JSON above).
  • 400 BAD REQUEST – Internal code 1201 Specified vendor does not match the p12 file content.
  • 400 BAD REQUEST – Internal code 1202 Invalid p12 file. The provided p12 is can not be opene because it does not contain the proper information.
  • 400 BAD REQUEST – Internal code 1203 We could not open the p12 file with the specified password.

Update Certificate

Note

This PUT request will update an existing certificate. Take note of the following behaviors before using this endpoint in production:

  • The following fields can be updated directly: enabled, default, comment and name.
  • If fields enabled and default are not specified they won’t be changed.
  • If fields comment and name are not specified, we assume the value needs to be removed. If you don’t want to change the value, specify "comment": null or "name": null.
  • Some of the fields will be extracted from the certificate and will be updated indirectly: teamIdentifier and baseName.
  • The field updatedAt will change with each update.
  • The field createdAt cannot be changed.
  • If the user specifies an invalid id in the path or no certificate can be found we will return an error (see below).
  • Changing the default certificate is done by setting the new certificate "default" : true.
  • Setting default to false on the default certificate will throw an exception.
PUT /v1/certificates/{id}

Example Request:

PUT /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json

Payload is identical to the create call. If p12 is specified password is required.

Example Response:

HTTP/1.1 400 BAD_REQUEST
Content-Type: application/json

{
    "error" : {
        "code": 123,
        "message":"Major fail"
    }
}
Status Codes:
  • 200 OK – The certificate update was successful (see JSON above)
  • 400 BAD REQUEST – Internal code 1201 Specified vendor does not match the p12 file content.
  • 400 BAD REQUEST – Internal code 1203 Invalid p12 file. The provided p12 cannot be opened because it does not contain the proper information.
  • 400 BAD REQUEST – Internal code 1101 invalid id, the id has to be a valid UUID (the id from the path).
  • 404 NOT FOUND – Internal code 1204 The specified certificate could not be found.
  • 400 BAD REQUEST – Internal code 1205 Could not replace the specified p12 file; it does not match the existing one.
  • 400 BAD REQUEST – Internal code 1206 We could not open the p12 file with the specified password.

Get Certificate

GET /v1/certificates/{id}

Example response:

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

{
    "id":"40adce15-5c52-479d-8620-54c21cd851a6"
    "vendor":"Apple",
    "baseName","xyz1"
    "name":"editable name",
    "comment":"something about this cert",
    "teamIdentifier" : "XYZ",
    "enabled":false,
    "createdAt":"2016-05-26T23:23:21Z",
    "updatedAt":"2016-05-26T22:23:21Z",
    "templates" : [
        {"id":123,"name":"templateName1"},
        {"id":221,"name":"templateName2"}
    ]
}
HTTP/1.1 404 NOT_FOUND
Content-Type: application/json

{
    "error" : {
        "code": 123,
        "message":"Could not find the specified certificate"
    }
}
Status Codes:
  • 200 OK – We found the specified certificate (see JSON above)
  • 400 BAD REQUEST – Internal code 1101 Invalid id, the id has to be a valid UUID.
  • 404 NOT FOUND – Internal code 1204 The specified certificate could not be found.

List Certificates

Returns a list of all the certificates that are owned by the api user calling this endpoint.

To specify pagination use standard optional wallet page, direction and pageSize URL parameters.

GET /v1/certificates?vendor=Apple&page=0&pageSize=10

Request Parameters:

  • vendor string (optional) - If specified, it returns only certificates for the specified vendor.
  • page number (optional) - Page you wish to retrieve, starting with 1.
  • pageSize number (optional) - Number of certificates per page
  • direction string (optional) - Whether you want the values ordered ascending or descending. Can be either ASC or DESC, default is DESC.
  • order string (optional) - Indicates which field to order by.
  • enabled boolean (optional) - If specified, only enabled certificates will be returned.

Example response:

HTTP/1.1 201 List
Content-Type: application/json

{
    "nextPage":"https://wallet.urbanairship.com/v1/certificates/list/?page=11&pageSize=10"
    "count":2,
    "pagination":{
        "order": "name",
        "page": "1",
        "start": "0",
        "direction": "DESC",
        "pageSize":10
    },
    "certificates":[
        {
            "id":"40adce15-5c52-479d-8620-54c21cd851a6",
            "vendor":"Apple",
            "baseName","xyz1"
            "name":"editable name1",
            "comment":"something about this cert",
            "teamIdentifier" : "XYZ",
            "enabled":true,
            "default":true,
            "createdAt":"2016-05-26T22:23:21Z",
            "updatedAt":"2016-05-26T22:23:21Z",
            "templates" : [
                {"id":123,"name":"templateName1"},
                {"id":221,"name":"templateName2"}
            ]
        },
        {
            "id":"12adce15-5c52-479d-8620-54c21cd851aa",
            "vendor":"Apple",
            "baseName","xyz2"
            "name":"editable name1",
            "comment":"something about this cert",
            "teamIdentifier" : "XYZ",
            "enabled":false,
            "default":false,
            "createdAt":"2016-05-26T23:23:21Z",
            "updatedAt":"2016-05-27T17:22:00Z",
            "templates" : [
                {"id":123,"name":"templateName1"},
                {"id":221,"name":"templateName2"}
            ]
        }
    ]
}
Status Codes:
  • 200 OK – We found the specified certificate (see JSON above)
  • 400 BAD REQUEST – Internal code 1205 Specified vendor is not supported.

Delete Certificate

Deletes the specified certificate. The certificate to be deleted is specified by its id (UUID).

DELETE /v1/certificates/{id}

Example response:

HTTP/1.1 201 Deleted

Upon successful certificate deletion, we return the proper HTTP status for success (HTTP/1.1 201). The success response does not contain any JSON payload.

In the case of an error, we return the appropriate error message as described in the Error Response Fields section and directly below.

HTTP/1.1 404 NOT_FOUND
Content-Type: application/json

{
    "error" : {
        "code": 304,
        "message":"Could not find the specified certificate"
    }
}
Status Codes:
  • 201 Deleted – We found the specified certificate and deleted it
  • 404 NOT FOUND – Internal code 1204 The specified certificate could not be found.
  • 400 BAD REQUEST – Internal code 1101 Invalid id, the id has to be a valid UUID.

JSON Fields Description

This section explains the various JSON fields in detail.

Certificate Fields
  • id - string (optional, read only) - certificate id; it is optional because when we add a certificate we don’t have an id yet.
  • vendor string - “Apple” is the only vendor currently supported
  • cert string base64 encoded (optional) - p12 file base64 encoded in json
  • baseName string (read only) - this name is extracted from the certificate and cannot be changed
  • name string (optional, read only) - the user can provide an additional name; if it is not provided, the filename of the p12 file will be used.
  • comment string (optional) - text to describe the certificate
  • enabled boolean (optional) - true to have this certificate enabled false to have this certificate disabled
  • default boolean (optional) - indicates whether this certificate is used as the default certificate. If the user has multiple certificates and he/she sets a new default, the previously default certificate will be changed to default false.
  • templates list (optional) - a list of of templates that are associated with this certificate. Each entry has the members specified below.
  • teamIdentifier string (optional, read only) - required for the Apple certificate but not used for the Google certificate
  • createdAt date (optional, read only) - the date of creation
  • updatedAt date (optional, read only) - the date of update; when the certificate is added/created the updateAt is set to the same date as the createdAt
General Response Fields
  • nextPage string (optional)
  • certificates list of Certificates (optional) - used for list certificates endpoint
  • count number (optional) - used for the list certificates endpoint
  • pagination pagination fields (optional) - all the fields used for pagination (see below)
  • error error response fields (optional) - used in the case of an error
Pagination Fields
  • page number (optional) - used for the list certificates endpoint; the page number
  • start number (optional) - start index of the page
  • pageSize number (optional) - used for the list certificates endpoint
  • direction number (optional) - used for the list certificates endpoint; direction of the order ASC or DESC
  • order string (optional) - defines on which provided field you want to order the list of certificates The following fields may be used for ordering: name, baseName, createdAt, updatedAt
Template List Contents
  • id number - the template id
  • name string - the name of the template
Error Response Fields
  • code number - error code
  • message string - some details about this error