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:
Request access to the API by contacting the Urban Airship Sales team. Once approved, you’ll find additional configuration features in Account Settings.
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.
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: Getting Started: Certificate Setup: Apple Wallet to learn how to generate a certificate.
Create a project and template, then design the template’s appearance using the Reach interface. 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
Dynamic Links
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.
Generate Dynamic Link
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
valueandlabelfields.valueindicates the expiration date of the pass.labelcan be set to eithervalidorvoided, wherevalidindicates a non-expired pass, andvoidedindicates that the pass is no longer accepted. barcode_valueMay 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)
- Specify the field type (set to
value- Barcode value
label- Human-readable label for this barcode, displayed above the barcode
barcodeAltTextMay contains the same fields as
barcode_value.
fieldsAn 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
beaconsA 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
publicUrlRequired for Android. Optional on iOS to request a publicly accessible URL for the pass
typesingleormultipleuse, depending on how many times it can be downloaded. All Android pass URLs aresingle.multipleonly applicable on iOS.
path- Pass URL returned in response
used- Returns
trueorfalsefor iOS, N/A for Android
- Returns
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_timekey 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
audienceparameters,passvalues andtemplateID 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,commentandname.If fields
enabledanddefaultare not specified they won’t be changed.If fields
commentandnameare not specified, we assume the value needs to be removed. If you don’t want to change the value, specify"comment": nullor"name": null.Some of the fields will be extracted from the certificate and will be updated indirectly:
teamIdentifierandbaseName.The field
updatedAtwill change with each update.The field
createdAtcannot be changed.If the user specifies an invalid
idin 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
falseon 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.vendorstring - “Apple” is the only vendor currently supportedcertstring base64 encoded (optional) - p12 file base64 encoded in jsonbaseNamestring (read only) - this name is extracted from the certificate and cannot be changednamestring (optional, read only) - the user can provide an additional name; if it is not provided, the filename of the p12 file will be used.commentstring (optional) - text to describe the certificateenabledboolean (optional) -trueto have this certificate enabledfalseto have this certificate disableddefaultboolean (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.templateslist (optional) - a list of of templates that are associated with this certificate. Each entry has the members specified below.teamIdentifierstring (optional, read only) - required for the Apple certificate but not used for the Google certificatecreatedAtdate (optional, read only) - the date of creationupdatedAtdate (optional, read only) - the date of update; when the certificate is added/created theupdateAtis set to the same date as thecreatedAt
General Response Fields
nextPagestring (optional)certificateslist of Certificates (optional) - used for list certificates endpointcountnumber (optional) - used for the list certificates endpointpaginationpagination fields (optional) - all the fields used for pagination (see below)errorerror response fields (optional) - used in the case of an error
Pagination Fields
pagenumber (optional) - used for the list certificates endpoint; the page numberstartnumber (optional) - start index of the pagepageSizenumber (optional) - used for the list certificates endpointdirectionnumber (optional) - used for the list certificates endpoint; direction of the orderASCorDESCorderstring (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
idnumber - the template idnamestring - the name of the template
Error Response Fields
codenumber - error codemessagestring - some details about this error