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:
Choose a Reach project from your Project list.
Get your API key: Your private API key is located in Settings » API. 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
Response Codes
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"
}
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
JSON Parameters
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 the project with the specified ID.
Query Parameters
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
}
}
List projects belonging to you.
Query Parameters
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"
}
Update the human-friendly name and/or description of a project.
Query Parameters
JSON Parameters
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
}
Create a template and add the template to the specified project
Create a template with an external ID and add the template to the specified project
Query Parameters
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 the template specified by the ID.
Query Parameters
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"
}
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
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
}
Duplicates the specified template and puts the newly created template it in the same project
Duplicates the template specified by the external id, and puts the newly created template in the same project
Query Parameters
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
}
]
Add locations to the specified template.
Query Parameters
JSON Parameters
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 location from template.
Query Parameters
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"
}
}
List the headers for templates belonging to you.
Query Parameters
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 the specified template.
Query Parameters
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.
Example Response:
{
"url":"https://reach-api.urbanairship.com/v1/pass/dynamic/44e128a5-ac7a-4c9a-be4c-224b6bf81b20","message":"Existing Dynamic Link"
}
You may not create multiple dynamic links using an external ID for which a link (or pass) was already created. If you try to create a dynamic link using an external ID that you have already used for a project, you will get the JSON return at right.
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.
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
Response Codes
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
}
]
}
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
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.
Example Response:
{
"code":400,"description":"Invalid Request Parameters.","details":"Duplicate external id: \u0027DeepLExID4\u0027"
}
You may not create multiple deep links using an external ID for which a link (or pass) was already created. If you try to create a deep link using an external ID that you have already used for a project, you will get the JSON return at right.
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 the specified pass.
JSON Parameters
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"
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
}
}
List your passes. When using the /v1/pass endpoint, the templateId
specification is optional. The /v1/template/ endpoint however, requires
a templateId.
Query Parameters
Totals returned for Installed and Uninstalled will not reflect any Android passes created using Deep Links.
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"
}
]
}'
Updating an expired pass with "label" : "valid" under the
expirationDate key will once again make the pass usable.
Example Response:
{
"ticketId": 1234
}
Update the specified pass. Optionally, update the pass with the specified
passExternalId.
JSON Parameters
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
}
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
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":{
}
}
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)"
}
View pass.json as per the Apple’s Passbook spec. This is a utility API to help debug your passes.
JSON Parameters
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"
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
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>
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
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"
}
}
]
Add the locations to the specified pass
JSON Parameters
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 the specified location from the specified pass.
Query Parameters
Response Codes
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 the specified pass.
Query Parameters
Response Codes
Adaptive Links
When distributing passes, you typically have no way of knowing what type of device an end user will use to access the pass. Whether via email, SMS, or social sharing, you need a URL that will lead to the fulfillment of the pass that is appropriate for the end user’s device, whether iOS, Android, or a web browser.
To that end, we have developed Adaptive Links, which allow you to distribute one URL that supports pass creation on iOS or Android devices, and to redirect users to a landing page URL for unsupported devices.
Overview
An Adaptive Link object represents the unified pass creation link and all of the necessary metadata needed to produce a pass from it.
To support both Android and iOS pass creation, an Adaptive Link must be associated with an appropriate template for each device type.
When a user follows an Adaptive Link URL, Reach must detect the type of device from which that request came and create a pass using the corresponding template associated with that Adaptive Link object.
In the case of a missing template or an unsupported device (including desktop browsers), Reach must either provide an error message or redirect to a landing page URL provided during creation of the Adaptive Link object.
A device flag can optionally be included in the request URL (android and ios)
to override the device detection and return a pass corresponding to that flag. A
primary application of this would be for use in landing pages that include
separate buttons explicitly linked to each device type.
Creating a Adaptive Link object requires an API key, but creating a pass by visiting an Adaptive Link URL does not and must not require an API key.
Request Parameter Mapping
Request parameters that map to fields in the pass creation payload may be used in the request to supply overriding custom values for those payload fields. If a provided request parameter does not match a payload field name, that parameter will be silently ignored.
The presence of any request parameter always necessitates the creation of a new personalized pass rather than another instance of an existing pass.
We have a few reserved parameters for pass tagging, barcode and location handling, and to associate an external ID to a pass:
Reserved Parameters:
JSON Parameters
barcodeAtlTexparameter specified the actual barcode value will be used as barcodeAltText.If the isPersonalized flag on your Adaptive Link object is set to false,
only one pass will be created with the first request and any subsequent requests will
create a new instance of the same pass.
If your Adaptive Link object has the isPersonalized flag set to true, every
request will create a new pass. However, if any request parameters are
present, the isPersonalized flag is considered to be true and Reach will
always create a new pass for every request (instead of a pass instance).
Location Handling
Provide a list of up to 2000 relevant locations with relevant text for the pass message when creating your Adaptive Link.
Optionally include a location radius and the maximum number of locations to be matched upon pass creation. Reach will sort the locations to be matched in order from closest to/furthest from the location provided by the device.
API Endpoints
Endpoints are provided for Adaptive Link creation, listing, update, and deletion.
Create Adaptive Link
Example Request:
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
{
"iosTemplateId": "12345",
"androidTemplateId": "154321",
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"landingPageUrl": "https://acustomer.com/landing.html",
"availablePasses": 100000
}
Example Request:
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
{
"iosTemplateId":"12345",
"androidTemplateId":"154321",
"isPersonalized":"true",
"payload": {"fields": {"tier": {"value": "gold"}}}
}
Example Request:
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
{
"iosTemplateId":"12345",
"androidTemplateId":"154321",
"isPersonalized":"true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"landingPageUrl":"https://acustomer.com/landing.html",
"availablePasses":100000,
"locationRadius": 10,
"maxResultLocations":5,
"locations":{
"latitude":[
{
"latitude": 45.5898,
"longitude": -122.5951,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97218",
"relevantText": "Welcome to Portland... Voodoo Donuts is only 11 miles away",
"streetAddress1": "7000 NE Airport Way"
},
{
"latitude": 45.525492,
"longitude": -122.686092,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97209",
"relevantText": "Welcome to the Ship!",
"streetAddress1": "1417 NW Everett St #300",
"streetAddress2": ""
},
{
"latitude": 45.5205,
"longitude": -122.6788,
"relevantText": "See you at dinner tonight… or did you already hit voodoo donuts?"
}
]
}
}
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"adaptiveLinkId":"abchd345",
"url": "https://reach-api.urbanairship.com/v1/pass/<adaptiveLinkId>",
"iosUrl": "https://reach-api.urbanairship.com/v1/pass/<adaptiveLinkId>ios",
"androidUrl": "https://reach-api.urbanairship.com/v1/pass/<adaptiveLinkId>/android",
"landingPageUrl":"https://acustomer.com/landing.html",
"isPersonalized":"true",
"availablePasses":100000
}
Adaptive Link creation accepts the following JSON fields:
JSON Parameters
true, the pass created from the Adaptive Link will use personalization; if false or absent, do not use personalization (create a new pass instance, not a new pass for each request).Location JSON
JSON Parameters
If a template for a device type is not provided, the Adaptive Link will not be
able to create passes for that device. Visiting the Adaptive Link URL associated
with an unsupported device will redirect to the landingPageUrl, if present.
Templates can be provided either implicitly as part of Dynamic Link objects
or explicitly with IDs. So either one or both of iosPassLinkId and
androidPassLinkId must be present, or payload must be present along
with one or both of iosTemplateId and androidTemplateId.
Response Details
The response JSON contains the Adaptive Link URLs (including device-specific URLs) that can be distributed to end-users.
- Response Parameters
adaptiveLinkId: String. the auto-generated ID used to uniquely identify the Adaptive Link for the API key- Status Codes
404 NOT FOUND: Could not find template(s), or could not find or create Dynamic Link object(s).- Authentication
- Requires API key
Get Adaptive Link
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId":"abchd345",
"url": "https://reach-api.urbanairship.com/v1/pass/<adaptiveLinkId>",
"iosUrl": "https://reach-api.urbanairship.com/v1/pass/<adaptiveLinkId>/ios",
"androidUrl": "https://reach-api.urbanairship.com/v1/pass/<adaptiveLinkId>/android",
"landingPageUrl":"https://acustomer.com/landing.html",
"availablePasses":100000
}
Gets the specified link URL(s).
Response Codes
adaptiveLinkId- Authentication
- Requires API key
Update Adaptive Link
Example Request:
PUT /v1/adaptive/<adaptiveLinkId> HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
{
"androidTemplateId":"154321",
"isPersonalized":"true",
"androidPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"landingPageUrl":"https://acustomer.com/landing.html"
}
Example Request:
PUT /v1/links/adaptive/<adaptiveLinkId> HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
{
"iosTemplateId":"12345",
"androidTemplateId":"154321",
"isPersonalized":"true",
"landingPageUrl":"https://acustomer.com/landing.html",
"payload": {"fields": {"tier": {"value": "gold"}}}
}
Example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId":"as3shd345",
"url":"https://reach-api.urbanairship.com/v1/pass/<adaptiveLinkId>",
"iosUrl":"https://reach-api.urbanairship.com/v1/pass/<adaptiveLinkId>/ios",
"androidUrl":"https://reach-api.urbanairship.com/v1/pass/<adaptiveLinkId>/android",
"landingPageUrl":"https://acustomer.com/landing.html",
"isPersonalized":"true",
"availablePasses":100000
}
Response Codes
- Authentication
- Requires API key
Delete Adaptive Link
Deletes the specified link.
Response Codes
adaptiveLinkId- Authentication
- Requires API key
Create Pass Via Adaptive Link
When distributing Adaptive Link URLs to your end users, if no device type is specified in the path, Reach detects the device type from the request headers.
If the device type cannot be detected Reach will redirect the request to a landing page URL that you must provide as part of the Adaptive Link metadata.
We recommend that this landing page provide buttons that
link to the explicit device-specific Dynamic Link URLs for iOS and Android pass
generation using the optional deviceType path flag.
You may also append to the request URL parameters mapping to existing pass fields. If a provided request parameter does not match a payload field name, that parameter will be silently ignored.
JSON Parameters
ios, android or webResponse by platform:
| Platform | Response |
|---|---|
| iOS | Download response header: Content-Type: application/vnd.apple.pkpass |
| Android | Redirect to the pass Deep Link |
| Web | Redirect to landing page URL associated for the Adaptive Link |
Create Pass With Request Parameters
If the isPersonalized flag on your Adaptive Link object is set to false,
only one pass will be created with the first request and any subsequent requests will
create a new instance of the same pass.
If your Adaptive Link object has the isPersonalized flag set to true, every
request will create a new pass. However, if any request parameters are
present, the isPersonalized flag is considered to be true and Reach will
always create a new pass for every request (instead of a pass instance).
Note: When adding tags use ~ to separate each tag, e.g., ?tags=tag1~tag2~tag3
See Request Parameter Mapping for a list of reserved parameters.
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"]
}'
Example Response:
{
"newTags": ["tag-name"],
"mappings":1
}
Add tags to the specified pass, limited to 15 tags per pass.
Query Parameters
JSON Parameters
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"
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 the tags that the specified pass has.
Query Parameters
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
}
List all tags.
Query Parameters
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
}
}
List the passes with this tag.
Query Parameters
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
}
Update all of the passes that have a given tag.
Query Parameters
JSON Parameters
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"
Example Response:
{
"passId":123,
"status":"success",
"tagId":70
}
Remove the tag from the specified pass.
Query Parameters
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 the specified tag and remove it from all passes.
Query Parameters
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"
}
Create a segment for the project.
Query Parameters
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"
}
]
}
List segments. Returns list of segments (segment metadata) for a project.
Query Parameters
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 segment data for a project’s segment.
Query Parameters
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"
}
Update segment. Update the segement data for a project’s segment.
Query Parameters
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 project’s segment.
Query Parameters
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"
}
}
}
}
}
]
}
Schedule an update
JSON Parameters
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
}
Returns list of schedules for a project
Query Parameters
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 schedule data for a project’s schedule
Query Parameters
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"
}
}
}
}
}
]
}
Update project’s schedule (identified by scheduleId)
Query Parameters
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 project’s schedule
Query Parameters
HTTP Callbacks
Reach callbacks provide a pass event notification, e.g., pass install or uninstall, using webhooks.
Create Callback Specification
Example request:
POST /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
{
"baseUrl": "https://www.remotehost.com/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
Example response:
HTTP/1.1 200 OK
{
"baseUrl": "https://www.remotehost.com/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
Register a callback specification which includes remote the URL and any HTTP headers required by remote URL
Query Parameters
"Authorization", "Content-Type", etc. By default, the payload sent is JSON and "Content-type:application/json" is added by the backend.Get Callback Specification
Example request:
GET /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Example response:
HTTP/1.1 200 OK
{
"baseUrl": "https://www.remotehost.com/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
Get callback specification
Query Parameters
Update Callback Specification
Example request:
PUT /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
{
"baseUrl": "https://www.remotehost.com/v1/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
Example response:
HTTP/1.1 200 OK
{
"baseUrl": "https://www.remotehost.com/v1/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
Update callback specification
Query Parameters
Delete Callback Specification
Example request:
DELETE /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Example response:
HTTP/1.1 204 No Content
Delete registered callback specification
Query Parameters
List Callback Events
iOS pass install, uninstall, and personalize events can be used to notify a remote client by performing callbacks to specified URLs via the callback specification API.
Pass Installation Callback
Example Request:
POST https://www.remotehost.com/v1/callbacks/v1/pass/install HTTP/1.1
Authorization: "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0"
{
"passId": "12345",
"templateId": 25035,
"serialNumber": "6779a823-7c8f-4145-a640-c688069a3465",
"createdAt": "2017-01-23T20:46:50Z",
"updatedAt": "2017-04-20T20:40:00Z",
"externalId": "user_phone:408400100",
"platform": "ios"
}
Send an HTTP POST callback to remote endpoint on iOS pass installation
Pass Uninstallation Callback
Example Request:
POST https://www.remotehost.com/v1/callbacks/v1/pass/uninstall HTTP/1.1
Authorization: "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0"
{
"passId": 12345,
"templateId": 25035,
"serialNumber": "6779a823-7c8f-4145-a640-c688069a3465",
"createdAt": "2017-01-23T20:46:50Z",
"updatedAt": "2017-04-20T20:40:00Z",
"externalId": "user_phone:408400100",
"platform": "ios"
}
Send an HTTP POST callback to remote endpoint on an iOS pass uninstallation
Pass Personalization Callback
Example Request:
POST https://www.remotehost.com/v1/callbacks/v1/12345/personalize HTTP/1.1
Authorization: "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0"
{
"passId": "12345",
"templateId": "25035",
"serialNumber": "6779a823-7c8f-4145-a640-c688069a3465",
"createdAt": "2017-01-23T20:46:50Z",
"platform": "ios",
"personalizationInfo": {
"fullName": "John Mise",
"givenName": "John",
"familyName": "Mise",
"emailAddress": "test@abc.com",
"postalCode": "95051",
"ISOCountryCode": "US",
"phoneNumber": "408-409-1234"
}
}
Send an HTTP POST callback to remote endpoint on installation of personalized iOS pass.
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.
Totals returned for Installed and Uninstalled will not reflect any Android passes created using Deep Links.
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
}
Return template statistics for a given template ID.
Query Parameters
JSON Parameters
Return template statistics for a given template external ID.
Query Parameters
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
}
}
]
}
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
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
}
Return project statistics for a given project ID.
Query Parameters
JSON Parameters
Return project statistics for a given project external ID.
Query Parameters
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
}
}
]
}
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
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 the status of a ticket
JSON Parameters
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"
}
Check if a connection can be made to the Wallet API.
JSON Parameters
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"
}
}
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
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"
}
}
Response Codes
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"
}
}
Response Codes
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"}
]
}
]
}
Query Parameters
Response Codes
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"
}
}
Deletes the specified certificate. The certificate to be deleted is specified by its id (UUID).
Response Codes
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