map-o file-code-o arrow-directionplatform-webreach-project-type-boarding-passreach-project-type-couponreach-project-type-event-ticketreach-project-type-genericreach-project-type-gift-cardreach-project-type-loyalty-cardreach-project-type-member-card pictures more_vert chain keyboard_arrow_down keyboard_arrow_right

Reach API

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.

Use the HTTP and cURL tabs on the right to toggle between response/request formats. Note that cURL request examples do not include responses.

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

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

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.

Authentication

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

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:

echo -n "[YOUR_EMAIL]:[YOUR_KEY]" | base64
  • 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):

  • The authorization method and a space are then added before the encoded string i.e “Basic “.

Date/Time Format

Example:

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

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.

HTTP Response Codes

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

JSON Parameters

code
matches the HTTP response code
fieldErrors
Optional.

Response Codes

400
Invalid Request Parameters
401
Unauthorized
406
Not Acceptable Request
429
Too Many Requests
500
Internal Server Error

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

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

Example Response:

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

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

Query Parameters

projectExternalId
The external ID you wish to use for the project.

JSON Parameters

name
Required. The name of the project.
projectType
Required. The project type, can be any one of loyalty, coupon, giftCard, memberCard, eventTicket, boardingPass, generic.
description
Required. The description of the project.

Get Project

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"

Example Response:

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

{
  "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"
}
GET /v1/project/(projectId)

GET /v1/project/id/(projectExternalId)

Get the project with the specified ID.

Query Parameters

projectId
The ID of the project you are looking for.
projectExternalId
The external ID of the project you are looking for.

List Projects

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"

Example Response:

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

{
  "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
  }
}
GET /v1/project?pageSize=(int)&page=(int)&order=(str)&direction=(str)

List projects belonging to you.

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
Choose ascending (ASC) or descending (DESC) order for the returned values; default is DESC

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

Example Response:

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

{
  "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"
}
PUT /v1/project/(projectId)
PUT /v1/project/id/(projectExternalId)

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

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

name
Optional. Provide the new name for the project.
description
Optional. Provide the new description of the project.

Templates

Create and Update Template request simplified JSON example:

Apple

{
   "userlocations":{},
   "headers":{},
   "fields":{},
   "beacons":[],
   "metadatakey1": "value",
   "metadatakey2": "value"
}

Google (Loyalty)

{
   "userlocations":{},
   "headers":{},
   "linksModuleData":{},
   "pointsModule":{},
   "titleModule":{},
   "infoModuleData":{},
   "textModulesData":{},
   "imageModulesData":{},
   "notAssigned":{},
   "acctModule":{},
   "metadataKey1": "value",
   "metadataKey2": "value"
}

Get Template response simplified JSON example:

Apple

{
   "userlocations":{},
   "fieldsModel":{
      "headers":{},
      "fields":{},
      "beacons":[]
   },
   "templateHeader":{
      "metadatakey1": "value",
      "metadatakey2": "value"
   }
}

Google (Loyalty)

{
   "userlocations":{},
   "fieldsModel":{
      "headers":{},
      "linksModuleData":{},
      "pointsModule":{},
      "titleModule":{},
      "vendor":"Google",
      "infoModuleData":{},
      "textModulesData":{},
      "imageModulesData":{},
      "notAssigned":{},
      "acctModule":{}
   },
   "templateHeader":{
      "metadataKey1": "value",
      "metadataKey2": "value"
   }
}

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.

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

Example Request:

POST /v1/template/(projectId) 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/(projectId) \
    -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/(projectId)/id/(templateExternalId) 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/(projectId)/id/(templateExternalId) \
    -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"
        }'

Example Response:

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

{
   "templateId": 12345
}
POST /v1/template/(projectId)

Create a template and add the template to the specified project

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

Create a template with an external ID and add the template to the specified project

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.

See the Reach Reference for image size specifications.

Get Template

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"

Example Response:

{
   "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"
   }
}
GET /v1/template/(templateId)
GET /v1/template/id/(templateExternalId)

Get the template specified by the ID.

Query Parameters

templateId
The ID of the template you wish to retrieve.
templateExternalId
The external ID of the template you wish to retrieve.

Update Template

Example Request:

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

Example Response:

{
   "templateId":"12345"
}
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.

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

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

Duplicate Template

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"

Example Response:

HTTP/1.1 200 OK

{
   "templateId": 12346
}
POST /v1/template/duplicate/(templateId)

Duplicates the specified template and puts the newly created template it in the same project

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

Duplicates the template specified by the external id, and puts the newly created template in the same project

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

Add Locations to 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":"San Francisco",
         "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":"San Francisco",
                 "region":"CA",
                 "regionCode":"94404",
                 "country":"US"
              }
           ]
        }'

Example Response:

HTTP/1.1 200 OK

[
   {
      "locationId":65,
      "value":{
         "region":"CA",
         "regionCode":"94404",
         "relevantText":"Hello loc0",
         "streetAddress1":"address line #1",
         "streetAddress2":"address line #2",
         "longitude":-122.374,
         "latitude":37.618,
         "city":"San Francisco"
      },
      "fieldId":1842
   }
]
POST /v1/template/(templateId)/locations
POST /v1/template/id/(templateExternalId)/locations

Add locations to the specified template.

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

longitude
Required: Longitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
latitude
Required: 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 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"

Example Response:

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

{

}

Upon success, a 200 OK response is returned with an empty JSON object to indicate that the resource has been deleted.

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

Delete location from template.

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

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"

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"
   }
}
GET /v1/template/headers

List the headers for templates belonging to you.

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.

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

Example Response:

HTTP/1.1 200 OK

{
   "status": "Deleted",
   "TemplateID": "12345"
}
DELETE /v1/template/(templateId)
DELETE /v1/template/id/(templateExternalId)

Delete the specified template.

Query Parameters

templateId
The ID of the template you wish to delete.
templateExternalId
The external ID of the template you wish to delete.

Passes

Once you have created your Reach template, generating and distributing passes is a two-step process using the Reach API dynamic link endpoint described below. The links are dynamic because passes are installed on the devices only at the time when a user interacts with the add to Android Pay/Apple Wallet workflow.

Step 1: POST to /v1/pass/(templateId)/dynamic?expiry=YYYY-MM-DD which generates a URL that you will use to distribute passes. The URL that is returned contains the serialNumber parameter that you will use to reference the pass later.

Step 2: Distribute the provided URL to users via email or the method of your choosing. See Pass Deep Linking for specifics on how URLs behave on Android vs. iOS. There are minor differences between the two platforms in the way the URLs are handled, but the user experience is the same: a “Save” button for Android Pay and an “Add” button for Apple Wallet.

Example Request:

POST /v1/pass/(templateId)/dynamic&expiry=2017-05-18 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

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

Example Response:

{
   "url" : "https://reach-api.urbanairship.com/v1/pass/dynamic/44e128a5-ac7a-4c9a-be4c-224b6bf81b20"
}

The final URI parameter in the response (44e128a5-ac7a-4c9a-be4c-224b6bf81b20 in the example above) is the serialNumber.

POST /v1/pass/(templateId)/dynamic?expiry=YYYY-MM-DD

Generate Dynamic Link. This call takes an existing iOS or Android template ID, along with an optional expiry argument, and returns a URL that includes a reference to the the pass in the Reach database.

JSON Parameters

templateId
Integer, Template ID
expiry
Optional. UTC Date on which this link will no longer be valid. Default value is 6 months from creation.
externalId
Optional, An external ID for your pass.

Response Codes

400 Bad Request
if templateId is not included
400 Bad Request
if no request body
401 Unauthorized
if invalid user
400 Bad Request
if template does not belong to user

The payload in the Generate Dynamic Link call is nearly identical to the Create Pass call, with one exception:

You may include an externalId as a top-level key in the JSON body. Once the pass is installed, you may continue to use the externalId to reference the pass in the future.

Create Pass

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
        }
    ]
}
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.

JSON Parameters

headers
one of the following fields:
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

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

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

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.

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

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
      }
   }
}
GET /v1/pass/(passId)
GET /v1/pass/id/(passExternalId)

Get the specified pass.

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

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"
GET /v1/pass
GET /v1/pass?templateId=(id)

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

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.

Update 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"
               }
            ]
        }'
PUT /v1/pass/(passId)

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

Example Response:

{
    "ticketId": 1234
}
PUT /v1/pass/id/(passExternalId)

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

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.

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

Bulk Update Passes

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

Example Response:

{
   "ticketId": 56789
}
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.

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

Any data sent via the Bulk Pass Update API will replace that same data for all passes under that template ID. This can refer to:

  • Membership ID fields

  • Coupon Codes

  • Barcode values or alternative text

  • Any other field or image on the pass

The only fields, images or barcode data that will be modified on passes under that template ID are those fields, images or barcode data sent in the Bulk Pass Update API.

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

To query the ticketId, see below.

Query Ticket ID

Example Response:

{
   "Status": "COMPLETED",
   "createdAt":"2016-12-28 21:53:34.0",
   "ID":66644895,
   "children":{
   }
}
GET /v1/template/ticket/(ticketId)

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

Expire Pass

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

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

Get Apple JSON for a Pass

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

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

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

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

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

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

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": "San Francisco",
      "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": "San Francisco",
              "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"
      }
   }
]
POST /v1/pass/(passId)/locations
POST /v1/pass/id/(passExternalId)/locations

Add the locations to the specified pass

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.
longitude
Required Longitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
latitude
Required 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

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"
DELETE /v1/pass/(passId)/location/(locationId)
DELETE /v1/pass/id/(passExternalId)/location/(locationId)

Delete the specified location from the specified pass.

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.

Response Codes

code 200
Success

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

Example Response:

{
    "Status":"Deleted",
    "PassID":"123"
}
DELETE /v1/pass/(passId)
DELETE /v1/pass/id/(passExternalId)

Delete the specified pass.

Query Parameters

passId
The ID of the pass you wish to delete.
passExternalId
The external ID of the pass you wish to delete.

Response Codes

code 200
Success

Tags

Add Tags to 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"]
        }'
PUT /v1/pass/(passId)/tags

Example Response:

{
  "newTags": ["tag-name"],
  "mappings":1
}
PUT /v1/pass/id/(passExternalId)/tags

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

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.

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

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"
GET /v1/pass/(passId)/tags

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"
    }
  ]
}
GET /v1/pass/id/(passExternalId)/tags

Get the tags that the specified pass has.

Query Parameters

passId
The ID of the pass you wish to retrieve.
passExternalId
The external ID of the pass you wish to retrieve.

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"

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
}
GET /v1/tag

List all tags.

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.

List Passes for 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"

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
  }
}
GET /v1/tag/(tag)/passes

List the passes with this tag.

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.

Update Passes by 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"}
          }
        }'

Example Response:

{
   "ticketId": 123
}
PUT /v1/tag/(tag)/passes

Update all of the passes that have a given tag.

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.

Remove Tag from 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"
DELETE /v1/tag/(tag)/pass/(passId)

Example Response:

{
   "passId":123,
   "status":"success",
   "tagId":70
}
DELETE /v1/tag/(tag)/pass/id/(passExternalId)

Remove the tag from the specified pass.

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.

Delete Tag

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"

Example Response:

{
    "status": "success",
    "tagId": 5,
    "count": 93
}
DELETE /v1/tag/(tag)

Delete the specified tag and remove it from all passes.

Query Parameters

tag
The tag you wish to delete

Segments

A Segment identifies a group/set of wallet passes that contains a tag or combination of tags, using boolean and, or, and not operators.

Create Segment

Example Request:

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

{
   "criteria": {
      "and": [
         {
            "tag": "TZ_PST"
         },
         {
            "not": {
               "tag": "TZ_ET"
            }
         }
      ]
   },
   "display_name": "timezone"
}
 

Example Response:

   
{
   "ok":true,
   "segmentId":"b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
   "operationId":"dd2f1d32-aca9-4463-91c2-a3420bbcd489"
}
POST /v1/segments/(projectId)

Create a segment for the project.

Query Parameters

projectId
Project ID for which you want to get the list of segments

List Segments

Example Request:

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

Example Response:

   
{
   "segments": [
      {
         "creation_date": "2017-03-17T05:45:21Z",
         "display_name": "timezone",
         "id": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
         "modification_date": "2017-03-17T05:45:21Z"
      },
      {
         "creation_date": "2017-03-17T23:29:06Z",
         "display_name": "my testing segment",
         "id": "5eae7f52-3dc7-4a67-8a89-9b357815e7f7",
         "modification_date": "2017-03-17T23:29:06Z"
      }
   ]
}
GET /v1/segments/(projectId)

List segments. Returns list of segments (segment metadata) for a project.

Query Parameters

projectId
Project ID for which you want to get the list of segments

Get Segment

Example Request:

GET /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

Example Response:

{
   "criteria": {
      "and": [
         {
            "tag": "TZ_PST"
         },
         {
            "not": {
               "tag": "TZ_ET"
            }
         }
      ]
   },
   "display_name": "timezone"
}
GET /v1/segments/(projectId)/(segmentId)

Get segment data for a project’s segment.

Query Parameters

projectId
Project ID for which you want to get the list of segments
segmentId
Segment ID

Update Segment

Example Request:

PUT /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

{
   "criteria": {
      "and": [
         {
            "tag": "TZ_PST"
         },
         {
            "not": {
               "tag": "TZ_ET"
            }
         }
      ]
   },
   "display_name": "timezone_info"
}

Example Response:

{
 "ok": true,
 "segmentId": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
 "operationId": "f573b3c5-b0ee-4461-a179-2e78aab20400"
}
PUT /v1/segments/(projectId)/(segmentId)

Update segment. Update the segement data for a project’s segment.

Query Parameters

projectId
Project ID for which you want to get the list of segments
segmentId
Segment ID

Delete Segment

Example Request:

DELETE /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

Example Response:

HTTP/1.1 204 No Content 
DELETE /v1/segments/(projectId)/(segmentId)

Delete project’s segment.

Query Parameters

projectId
Project ID for which you want to get the list of segments
segmentId
Segment ID

Schedules

A schedules object describes an update to a pass or group of passes using the /schedules endpoint.

name
string, required | the human-friendly name of the pass update
schedule
object, required | Key/value pair consisting of scheduled_time key and the corresponding value for the update in UTC timestamp form, e.g., "scheduled_time": "2017-04-10T18:45:00"
update
object, required | A single update object that passes the audience parameters, pass values and template ID for the targeted update.

Schedule an Update

Example request:

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

{
   "name": "New Offer Update",
   "schedule": {
      "scheduled_time": "2017-04-10T18:45:00"
   },
   "update": {
      "audience": {
         "tag": "TZ_ET"
      },
      "pass": {
         "fields": {
            "primary1": {
               "value": "$20 Off"
            },
            "secondary1": {
               "value": "Mega Offer"
            }
         }
      },
      "template": "12345"
   }
}

Example response:

{
  "ok": true,
  "operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
  "schedule_urls": [
     "https://reach-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
  ],
  "schedules": [
     {
        "url": "https://reach-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109",
        "ticket": "https://reach-api.urbanairship/v1/ticket/6789"
        "name": "New Offer Update",
        "schedule": {
           "scheduled_time": "2017-04-10T18:45:00"
        },
        "update": {
           "template": "12345",
           "audience": {
              "tag": "TZ_ET"
           },
           "pass": {
              "fields": {
                 "secondary1": {
                    "value": "Mega Offer"
                 },
                 "primary1": {
                    "value": "$20 Off"
                 }
              }
           }
        }
     }
  ]
}
POST /v1/schedules/(projectId)

Schedule an update

JSON Parameters

body
A JSON Object containing the name, schedule and update JSON (template(id of template), audience(tag/segment) and pass fields) for pass update.

List Schedules

Example request:

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

Example response:

{
   "count": 2,
   "next_page": "https://reach-api.urbanairship.com/v1/schedules/12345?start=5c69320c-3e91-5241-fad3-248269eed104&limit=2&order=asc",
   "ok": true,
   "schedules": [
      {
         "schedule": {
            "scheduled_time": "2017-04-10T18:45:00"
         },
         "update": {
            "audience": {
               "tag": "TZ_ET"
            },
            "pass": {
               "fields": {
                  "primary1": {
                     "value": "$20 Off"
                  },
                  "secondary1": {
                     "value": "Mega Offer"
                  }
               }
            },
            "template": "12345"
         },
         "url": "http://reach-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
      },
      {
         "schedule": {},
         "update": {},
         "url": "http://reach-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed10A"
      }
   ],
   "total_count": 4
}
GET /v1/schedules/(projectId)

Returns list of schedules for a project

Query Parameters

projectId
Project ID for which you want to get the list of schedules

Get Schedule

Example request:

 
GET /v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

Example response:

HTTP/1.1 200 OK
{
  "name": "New Offer Update",
  "schedule": {
     "scheduled_time": "2017-04-10T18:45:00"
  },
  "update": {
     "audience": {
        "tag": "TZ_ET"
     },
     "pass": {
        "fields": {
           "primary1": {
              "value": "$20 Off"
           },
           "secondary1": {
              "value": "Mega Offer"
           }
        }
     },
     "template": "12345"
  }
}
GET /v1/schedules/(projectId)/(scheduleId)

Get schedule data for a project’s schedule

Query Parameters

projectId
Project ID for which you want to get the list of schedules
scheduleId
Schedule ID

Update Schedule

Example request:

PUT /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
   
{
   "name": "New Offer Update",
   "schedule": {
      "scheduled_time": "2017-04-11T18:45:00"
   },
   "update": {
      "audience": {
         "tag": "TZ_ET"
      },
      "pass": {
         "fields": {
            "primary1": {
               "value": "$20 Off"
            },
            "secondary1": {
               "value": "Mega Offer"
            }
         }
      },
      "template": "12345"
   }
}

Example response:

{
  "ok": true,
  "operation_id": "efb18e92-9a60-6689-45c2-82fedab36490",
  "schedule_urls": [
     "https://reach-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
  ],
  "schedules": [
     {
        "url": "https://reach-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109",
        "name": "New Offer Update",
        "schedule": {
           "scheduled_time": "2017-04-11T18:45:00"
        },
        "update": {
           "template": "12345",
           "audience": {
              "tag": "TZ_ET"
           },
           "pass": {
              "fields": {
                 "secondary1": {
                    "value": "Mega Offer"
                 },
                 "primary1": {
                    "value": "$20 Off"
                 }
              }
           }
        }
     }
  ]
}
PUT /v1/schedules/(projectId)/(scheduleId)

Update project’s schedule (identified by scheduleId)

Query Parameters

projectId
Project ID for which you want to get the list of schedules
scheduleId
Schedule ID

Delete Schedule

Example request:

 
DELETE /v1/schedules/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

Example response:

HTTP/1.1 204 No Content
DELETE /v1/schedule/(projectId)/(scheduleId)

Delete project’s schedule

Query Parameters

projectId
Project ID for which you want to get the list of schedules
scheduleId
Schedule ID

Data Formats

Audience Selection

An audience selector forms the expression that determines the set of passes (objects) to which an update will be applied. A valid audience selector is a JSON expression which can identify a pass by means of one of the following three types:

  • Atomic selector
  • Compound selector
  • Location expression

Atomic Selectors

Example 1 : Tag

   

   {
      "audience": {
         "tag": "TZ_PST"
      }
   }

Example 2: Segment

   

   {
      "audience": {
         "segment": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a"
      }
   }

Atomic selectors may be one of “tag” or “segment.”

Compound selectors

Example 1: Implicit OR

   

   {
      "audience": {
         "tag": [
            "apples",
            "oranges",
            "bananas"
         ]
      }
   }

Example 2: Explicit OR

   

   {
      "audience": {
         "OR": [
            {
               "tag": "apples"
            },
            {
               "tag": "oranges"
            },
            {
               "tag": "bananas"
            }
         ]
      }
   }

Compound selectors combine boolean operators (AND, OR, or NOT) with one or more of the atomic expressions mentioned above. The syntax can be either implicit, using an array of values associated with an atomic selector (example 1) or explicit, employing a boolean operator followed by an array of atomic expression objects (example 2).

Logical Expressions

Example 1:

Select pass objects which are tagged for baseball or basketball, in timezone PST (TZ_PDT):

   
   {
      "audience": {
         "AND": [
            {
               "OR": [
                  {
                     "tag": "baseball"
                  },
                  {
                     "tag": "basketball"
                  }
               ]
            },
            {
               "tag": "TZ_PST"
            }
         ]
      }
   }

Example 2

Select pass objects which are tagged for timezone EST (TZ_EST) and not for timezone PDT (TZ_PDT):

   
   {
      "audience": {
         "AND": [
            {
               "tag": "TZ_EST"
            },
            {
               "NOT": {
                  "tag": "TZ_PDT"
               }
            }
         ]
      }
   }

An explicit logical expression is a JSON object consisting of a logical operator as the key, and an array of one or more expressions (which can be atomic, implicit OR, or other explicit logical expressions – anything except “all”).

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

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"

Example Response

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

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

Example Response

{
    "id": 12345,
    "vendor": "Apple",
    "lastUpdated": "2015-10-01T20:15:28.000-07:00",
    "total": 7,
    "installed": 0,
    "uninstalled": 0
}
GET /v1/template/(templateId)/stats

Return template statistics for a given template ID.

Query Parameters

templateId
The template ID.

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.
GET /v1/template/id/(templateExternalId)/stats

Return template statistics for a given template external ID.

Query Parameters

templateExternalId
The template external ID.

Template Activity

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
            }
        }
    ]
}
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.

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

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"

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
}

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

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
}
GET /v1/project/(projectId)/stats

Return project statistics for a given project ID.

Query Parameters

ID
The project ID.

JSON Parameters

id
The project ID.
lastUpdated
The date the project was last updated.
templates
An array of .
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.
GET /v1/project/id/(projectExternalId)/stats

Return project statistics for a given project external ID.

Query Parameters

projectExternalId
The project external ID.

Project Activity

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
            }
        }
    ]
}
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.

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

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 /v1/ticket/(ticketId)

Get the status of a ticket

JSON Parameters

ticketId
The ID of the ticket you want the status for

Get System Status

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"
}
GET /v1/system/status

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

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

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

Response 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

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"
    }
}
PUT /v1/certificates/{id}

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

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.

Get Certificate

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"
    }
}
GET /v1/certificates/{id}

Response 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

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"}
            ]
        }
    ]
}
GET /v1/certificates?vendor=Apple&page=0&pageSize=10

Query Parameters

vendor
string (optional) - If specified, it returns only certificates for the specified vendor
page
integer (optional) - Page you wish to retrieve, starting with 1
pageSize
integer (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

Response Codes

200 OK
We found the specified certificate (see JSON above)
400 BAD REQUEST
Internal code 1205 Specified vendor is not supported.

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.

Delete Certificate

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"
    }
}
DELETE /v1/certificates/{id}

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

Response 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