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

Reach API

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

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

Overview

Here’s what you need to do to get started with the Urban Airship Reach API:

  1. Choose a Reach project from your Project list.

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

  3. Upload your certificate (optional). If you want to use your own Apple Pass Type certificate, upload it in the Platform Management section of Account Settings. See: Getting Started: Certificate Setup: Apple Wallet to learn how to generate a certificate.

  4. 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"}}}'
POST /v1/pass/12345 HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Api-Revision: 1.2

{
   "fields": {
      "Name": {
         "value": "John Doe"
      }
   }
}

All Reach API calls (except “Get System Status”) require authentication via HTTP basic authentication, using your project name and project secret as the username/password.

Your project key and secret are found in the Reach web interface. Open a project, then navigate to Settings » API.

The Authorization header is constructed as follows:

  • Project key and secret are combined into a string [PROJECT_KEY]:[PROJECT_SECRET].

  • The resulting string is then Base64 encoded. The example below illustrates how you might generate the encoded auth string in a terminal window.

  • The authorization method and a space are then added before the encoded string, e.g., Basic Y29vbF9wcm9qZWN0X2tleTpjb29sX3Byb2plY3Rfc2VjcmV0.

Generate Base64 authorization string:

echo -n [PROJECT_KEY]:[PROJECT_SECRET] | base64

Note: The previous authentication method using string [YOUR_EMAIL_ADDRESS]:[PROJECT_KEY] has been deprecated. While that method is currently functional, we recommend that all customers switch to using [PROJECT_KEY]:[PROJECT_SECRET].

Date/Time Format

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

Example:

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

HTTP Response Codes

The HTTP response body for error codes has the following JSON format:

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

JSON Parameters

code
matches the HTTP response code
fieldErrors
Optional.

Response Codes

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

Security

  • Our APIs only work under 2048 bit HTTPS encrypted connections to ensure your data is private from client to server connections.

  • Access is authenticated through a unique secret API key which we provide to you in your Reach dashboard. It is your responsibility to keep this key well-guarded as it represents your identity.

  • You will use your own Apple or Android Pay certificate to sign production passes.

Projects

Create Project

Example Request:

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

{
  "name": "Aztec Barcode",
  "projectType": "loyalty",
  "description": "Aztec Barcode",
  "settings": {
    "barcode_alt_text": "123json=456789",
    "barcode_label": "Member ID",
    "barcode_default_value": "123456789",
    "barcode_encoding": "iso-8859-1",
    "barcode_type": "pdf417"
  }
}
curl -X POST https://wallet-api.urbanairship.com/v1/project \
    -H "Authorization: Basic <Base64 key>" \
    -H "Content-Type: application/json" \
    -H "Api-Revision: 1.2" \
    -d '{
          "name": "Aztec Barcode",
          "projectType": "loyalty",
          "description": "Aztec Barcode",
          "settings": {
            "barcode_alt_text": "123json=456789",
            "barcode_label": "Member ID",
            "barcode_default_value": "123456789",
            "barcode_encoding": "iso-8859-1",
            "barcode_type": "pdf417"
          }
        }'

Example Response:

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

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

POST /v1/project/id/(projectExternalId)

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

Query Parameters

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

JSON Parameters

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

Get Project

Example Request:

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

Example Response:

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

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

GET /v1/project/id/(projectExternalId)

Get the project with the specified ID.

Query Parameters

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

List Projects

Example Request:

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

Example Response:

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

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

List projects belonging to you.

Query Parameters

pageSize
Number of projects per page, default is 10.
page
Page you want to retrieve, starting with 1.
order
The order you want the projects returned in. Can be any one of id, name, createdAt, or updatedAt; default is id.
direction
Choose ascending (ASC) or descending (DESC) order for the returned values; default is DESC

Update Project

Example Request:

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

{
  "name": "New And Improved Name",
  "description": "Significantly more detailed description"
}
curl -X PUT https://wallet-api.urbanairship.com/v1/project/10058 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Content-Type: application/json" \
    -H "Api-Revision: 1.2" \
    -d '{
          "name": "New And Improved Name",
          "description": "Significantly more detailed description"
        }'

Example Response:

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

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

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

Query Parameters

projectId
The ID of the project you wish to update.
projectExternalId
The external ID of the project you wish to update.

JSON Parameters

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

Templates

Create and Update Template request simplified JSON example:

Apple

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

Google (Loyalty)

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

Get Template response simplified JSON example:

Apple

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

Google (Loyalty)

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

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

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

Create Template

Example Request:

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

{
  "headers": {
    "logo_color": {
      "formatType":1,
      "fieldType":"topLevel",
      "value":"rgb(24,86,148)"
    },
    "icon_image":{
      "formatType":1,
      "fieldType":"image",
      "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png"
    },
    "logo_text":{
      "formatType":1,
      "fieldType":"topLevel",
      "value":"Logo Text"
    },
    "barcode_encoding":{
      "formatType":1,
      "fieldType":"barcode",
      "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":"barcode",
              "value":"iso-8859-1"
            },
            "suppress_strip_shine":{
              "formatType":1,
              "fieldType":"topLevel",
              "value":"true"
            },
            "logo_image":{
              "formatType":1,
              "fieldType":"image",
              "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-logo.png"
            },
            "foreground_color":{
              "formatType":1,
              "fieldType":"topLevel",
              "value":"rgb(255,255,255)"
            },
            "background_color":{
              "formatType":1,
              "fieldType":"topLevel",
              "value":"rgb(49,159,196)"
            }
          },
          "fields":{
            "Text":{
              "formatType":"String",
              "changeMessage":"Edited",
              "order":1,
              "fieldType":"primary",
              "textAlignment":"textAlignmentRight",
              "value":"",
              "label":"Text",
              "required":false,
              "hideEmpty":true
            },
            "spelledOut":{
              "formatType":"Number",
              "changeMessage":"888",
              "order":2,
              "numberStyle":"numberStyleSpellOut",
              "fieldType":"secondary",
              "value":888.0,
              "label":"Spelled Out Edited",
              "required":false,
              "hideEmpty":true
            },
            "Apple 2":{
              "formatType":"String",
              "changeMessage":"888",
              "order":1,
              "fieldType":"secondary",
              "value":"",
              "label":"Apple 2",
              "required":false,
              "hideEmpty":false
            }
          },
          "vendor":"Apple",
          "projectType":"memberCard",
          "projectId":1234,
          "type":"Store Card",
          "vendorId":1,
          "deleted":"False",
          "description":"Description",
          "name":"Loyalty Card",
          "disabled":"False"
        }'
POST /v1/template/(projectId)/id/(templateExternalId) HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
  "infoModuleData": {
     "hexFontColor": "#666666",
     "hexBackgroundColor": "#0096e1",
     "Program ID": {
        "label": "Program ID",
        "value": "12345678",
        "row": 0,
        "col": 0,
        "formatType": "String"
     },
     "Tier Name": {
        "label": "Tier Name",
        "value": "Silver",
        "row": 0,
        "col": 1,
        "formatType": "String"
     },
     "Last Updated": {
        "label": "Last Updated",
        "value": "Five days ago",
        "row": 1,
        "col": 0,
        "formatType": "String"
     }
  },
  "headers": {
     "barcode_type": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     },
     "barcode_value": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     },
     "barcode_label": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     },
     "barcode_encoding": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     },
     "barcodeAltText": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     }
  },
  "textModulesData": {
     "Program Details": {
        "header": "Program Details",
        "body": "Some Basic Text",
        "row": 0,
        "col": 0,
        "formatType": "String"
     }
  },
  "linksModuleData": {
     "Merchant Website": {
        "description": "Merchant Website",
        "uri": "http:\/\/www.test.com",
        "order": 1,
        "formatType": "URL"
     }
  },
  "messageModule": {
  },
  "imageModulesData": {
  },
  "pointsModule": {
     "Tier": {
        "label": "Tier",
        "value": 2,
        "row": 0,
        "col": 1,
        "formatType": "Number",
        "numberStyle": "PKNumberStyleDecimal"
     },
     "Points": {
        "label": "Points",
        "value": 1234,
        "row": 0,
        "col": 0,
        "formatType": "Number"
     }
  },
  "notAssigned": {
  },
  "titleModule": {
     "image":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
     "imageDescription": "Logo Image",
     "Program Name": {
        "label": "Program Name",
        "value": "UA",
        "row": 0,
        "col": 0,
        "formatType": "String"
    }
  },
  "vendor": "Google",
  "projectType":"memberCard",
  "type": "Loyalty1",
  "vendorId":2,
  "deleted":"False",
  "description": "description",
  "name": "Adding Google"
}
curl -X POST https://wallet-api.urbanairship.com/v1/template/(projectId)/id/(templateExternalId) \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
          "infoModuleData": {
             "hexFontColor": "#666666",
             "hexBackgroundColor": "#0096e1",
             "Program ID": {
                "label": "Program ID",
                "value": "12345678",
                "row": 0,
                "col": 0,
                "formatType": "String"
             },
             "Tier Name": {
                "label": "Tier Name",
                "value": "Silver",
                "row": 0,
                "col": 1,
                "formatType": "String"
             },
             "Last Updated": {
                "label": "Last Updated",
                "value": "Five days ago",
                "row": 1,
                "col": 0,
                "formatType": "String"
             }
          },
          "headers": {
             "barcode_type": {
                "fieldType": "barcode",
                "value": "",
                "notShared": true
             },
             "barcode_value": {
                "fieldType": "barcode",
                "value": "",
                "notShared": true
             },
             "barcode_label": {
                "fieldType": "barcode",
                "value": "",
                "notShared": true
             },
             "barcode_encoding": {
                "fieldType": "barcode",
                "value": "",
                "notShared": true
             },
             "barcodeAltText": {
                "fieldType": "barcode",
                "value": "",
                "notShared": true
             }
          },
          "textModulesData": {
             "Program Details": {
                "header": "Program Details",
                "body": "Some Basic Text",
                "row": 0,
                "col": 0,
                "formatType": "String"
             }
          },
          "linksModuleData": {
             "Merchant Website": {
                "description": "Merchant Website",
                "uri": "http:\/\/www.test.com",
                "order": 1,
                "formatType": "URL"
             }
          },
          "messageModule": {
          },
          "imageModulesData": {
          },
          "pointsModule": {
             "Tier": {
                "label": "Tier",
                "value": 2,
                "row": 0,
                "col": 1,
                "formatType": "Number",
                "numberStyle": "PKNumberStyleDecimal"
             },
             "Points": {
                "label": "Points",
                "value": 1234,
                "row": 0,
                "col": 0,
                "formatType": "Number"
             }
          },
          "notAssigned": {
          },
          "titleModule": {
             "image":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
             "imageDescription": "Logo Image",
             "Program Name": {
                "label": "Program Name",
                "value": "UA",
                "row": 0,
                "col": 0,
                "formatType": "String"
            }
          },
          "vendor": "Google",
          "projectType":"memberCard",
          "type": "Loyalty1",
          "vendorId":2,
          "deleted":"False",
          "description": "description",
          "name": "Adding Google"
        }'

Example Response:

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

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

Create a template and add the template to the specified project

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

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

Query Parameters

templateExternalId
A unique external ID that you will use to reference this template in the future.
projectId
The ID of the project you’d like to add the template to.

See the Reach Reference for image size specifications.

Get Template

Example Request:

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

Example Response:

{
   "fieldsModel":{
      "headers":{
         "logo_color":{
            "formatType":1,
            "fieldType":"topLevel",
            "value":"rgb(24,86,148)"
         },
         "icon_image":{
            "formatType":1,
            "fieldType":"image",
            "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png"
         },
         "logo_text":{
            "formatType":1,
            "fieldType":"topLevel",
            "value":"Logo Text"
         },
         "barcode_encoding":{
            "formatType":1,
            "fieldType":"barcode",
            "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":"barcode",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         },
         "barcode_value":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"barcode",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         },
         "barcode_encoding":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"barcode",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         },
         "barcode_label":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"barcode",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         },
         "barcode_type":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"barcode",
            "value":"",
            "label":"",
            "required":false,
            "hideEmpty":false
         }
      },
      "textModule":{
         "textModule":{
            "formatType":"String",
            "body":"",
            "Basic Text 3":{
               "col":0,
               "order":1,
               "value":"",
               "label":"Basic Text 3",
               "row":0
            },
            "fieldType":"textModule",
            "hideEmpty":false,
            "header":"Basic Text 3"
         }
      },
      "linkModule":{
         "Link":{
            "formatType":"URL",
            "order":1,
            "description":"http:\/\/www.meanPurnima.com",
            "fieldType":"linksModule",
            "uri":"Link",
            "hideEmpty":false
         }
      },
      "messageModule":{
      },
      "imageModule":{
         "imageModule":{
            "formatType":"String",
            "fieldType":"imageModule",
            "image":"",
            "hideEmpty":false,
            "imageDescription":"Logo Image"
         }
      },
      "vendor":"Google",
      "pointsModule":{
         " Number":{
            "formatType":"String",
            "balance":123.0,
            "col":0,
            "fieldType":"loyaltyPoints",
            "label":" Number",
            "hideEmpty":false,
            "row":0
         },
         "Two":{
            "formatType":"Number",
            "balance":2.0,
            "col":0,
            "fieldType":"loyaltyPoints",
            "label":"Two-edited",
            "hideEmpty":false,
            "row":0
         }
      },
      "notAssigned":{
         "Text":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"notAssigned",
            "value":"",
            "label":"Text",
            "required":false,
            "hideEmpty":false
         },
         "spelledOut":{
            "formatType":"Number",
            "changeMessage":null,
            "fieldType":"notAssigned",
            "value":"888",
            "label":"Spelled Out Edited",
            "required":false,
            "hideEmpty":false
         },
         "Apple 2":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"notAssigned",
            "value":"",
            "label":"Apple 2",
            "required":false,
            "hideEmpty":false
         }
      },
      "titleModule":{
         "Basic Text 4":{
            "formatType":"String",
            "description.string":"",
            "col":0,
            "title.string":"Basic Text 4",
            "fieldType":"titleModule",
            "hideEmpty":false,
            "row":0
         },
         "image":{
            "formatType":"String",
            "description.string":"Logo Image",
            "title.string":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-titlestring.png",
            "fieldType":"titleModule",
            "hideEmpty":false
         },
         "One":{
            "formatType":"String",
            "description.string":"1",
            "col":0,
            "title.string":"One",
            "fieldType":"titleModule",
            "hideEmpty":false,
            "row":0
         }
      }
   },
   "templateHeader":{
      "vendor":"Google",
      "projectType":"memberCard",
      "projectId":1234,
      "type":"Loyalty1",
      "vendorId":2,
      "deleted":"False",
      "id":"12345",
      "updatedAt":"2013-06-25T18:00:31.000Z",
      "description":"description",
      "createdAt":"2013-02-01T09:02:03.000Z",
      "name":"Loyalty Card",
      "disabled":"False"
   }
}
GET /v1/template/(templateId)
GET /v1/template/id/(templateExternalId)

Get the template specified by the ID.

Query Parameters

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

Update Template

Example Request:

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

{
   "headers":{
      "logo_color":{
         "formatType":"1",
         "fieldType":"topLevel",
         "value":"rgb(24,86,148)"
      },
      "icon_image":{
         "formatType":"1",
         "fieldType":"image",
         "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png"
      },
      "logo_text":{
         "formatType":"1",
         "fieldType":"topLevel",
         "value":"Logo Text"
      },
      "barcode_encoding":{
         "formatType":"1",
         "fieldType":"barcode",
         "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":"barcode",
                 "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":"barcode",
            "value":"some value",
            "label":"some label",
            "required":"false",
            "hideEmpty":"false"
         },
         "barcode_value":{
            "formatType":"String",
            "changeMessage":"some message",
            "fieldType":"barcode",
            "value":"some value",
            "label":"some message",
            "required":"false",
            "hideEmpty":"false"
         },
         "barcode_encoding":{
            "formatType":"String",
            "changeMessage":"some message",
            "fieldType":"barcode",
            "value":"",
            "label":"",
            "required":"false",
            "hideEmpty":"false"
         },
         "barcode_label":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"barcode",
            "value":"",
            "label":"",
            "required":"false",
            "hideEmpty":"false"
         },
         "barcode_type":{
            "formatType":"String",
            "changeMessage":"",
            "fieldType":"barcode",
            "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":"barcode",
                    "value":"some value",
                    "label":"some label",
                    "required":"false",
                    "hideEmpty":"false"
                 },
                 "barcode_value":{
                    "formatType":"String",
                    "changeMessage":"some message",
                    "fieldType":"barcode",
                    "value":"some value",
                    "label":"some message",
                    "required":"false",
                    "hideEmpty":"false"
                 },
                 "barcode_encoding":{
                    "formatType":"String",
                    "changeMessage":"some message",
                    "fieldType":"barcode",
                    "value":"",
                    "label":"",
                    "required":"false",
                    "hideEmpty":"false"
                 },
                 "barcode_label":{
                    "formatType":"String",
                    "changeMessage":"",
                    "fieldType":"barcode",
                    "value":"",
                    "label":"",
                    "required":"false",
                    "hideEmpty":"false"
                 },
                 "barcode_type":{
                    "formatType":"String",
                    "changeMessage":"",
                    "fieldType":"barcode",
                    "value":"",
                    "label":"",
                    "required":"false",
                    "hideEmpty":"false"
                 }
              },
              "textModule":{
                 "textModule":{
                    "formatType":"String",
                    "body":"",
                    "Basic Text 3":{
                       "col":"0",
                       "order":"1",
                       "value":"",
                       "label":"Basic Text 3",
                       "row":"0"
                    },
                    "fieldType":"textModule",
                    "hideEmpty":false,
                    "header":"Basic Text 3"
                 }
              },
              "linkModule":{
                 "Link":{
                    "formatType":"URL",
                    "order":"1",
                    "description":"http:\/\/www.meanPurnima.com",
                    "fieldType":"linksModule",
                    "uri":"Link",
                    "hideEmpty":false
                 }
              },
              "messageModule":{
              },
              "imageModule":{
                 "imageModule":{
                    "formatType":"String",
                    "fieldType":"imageModule",
                    "image":"",
                    "hideEmpty":"false",
                    "imageDescription":"Logo Image"
                 }
              },
              "vendor":"Google",
              "pointsModule":{
                 " Number":{
                    "formatType":"String",
                    "balance":"123.0",
                    "col":"0",
                    "fieldType":"loyaltyPoints",
                    "label":"Number",
                    "hideEmpty":"false",
                    "row":"0"
                 },
                 "Two":{
                    "formatType":"Number",
                    "balance":"2.0",
                    "col":"0",
                    "fieldType":"loyaltyPoints",
                    "label":"Two-edited",
                    "hideEmpty":"false",
                    "row":"0"
                 }
              },
              "notAssigned":{
                 "Text":{
                    "formatType":"String",
                    "changeMessage":null,
                    "fieldType":"notAssigned",
                    "value":"",
                    "label":"Text",
                    "required":"false",
                    "hideEmpty":"false"
                 },
                 "spelledOut":{
                    "formatType":"Number",
                    "changeMessage":null,
                    "fieldType":"notAssigned",
                    "value":"888",
                    "label":"Spelled Out Edited",
                    "required":"false",
                    "hideEmpty":"false"
                 },
                 "Apple 2":{
                    "formatType":"String",
                    "changeMessage":null,
                    "fieldType":"notAssigned",
                    "value":"",
                    "label":"Apple 2",
                    "required":"false",
                    "hideEmpty":"false"
                 }
              },
              "titleModule":{
                 "Basic Text 4":{
                    "formatType":"String",
                    "description.string":"",
                    "col":"0",
                    "title.string":"Basic Text 4",
                    "fieldType":"titleModule",
                    "hideEmpty":"false",
                    "row":"0"
                 },
                 "image":{
                    "formatType":"String",
                    "description.string":"Logo Image",
                    "title.string":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-titlestring.png",
                    "fieldType":"titleModule",
                    "hideEmpty":"false"
                 },
                 "One":{
                    "formatType":"String",
                    "description.string":"1",
                    "col":"0",
                    "title.string":"One",
                    "fieldType":"titleModule",
                    "hideEmpty":"false",
                    "row":"0"
                 }
              }
           },
           "templateHeader":{
              "vendor":"Google",
              "projectType":"memberCard",
              "type":"Loyalty1",
              "vendorId":2,
              "deleted":"False",
              "description":"description",
              "name":"Adding Google"
           }
        }'

Example Response:

{
   "templateId":"12345"
}
PUT /v1/template/(templateId)
PUT /v1/template/id/(templateExternalId)

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

Query Parameters

templateId
The ID of the existing template that you want to update
templateExternalId
The external ID of the existing template that you want to update

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

Duplicate Template

Example Request:

POST /v1/template/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X POST https://wallet-api.urbanairship.com/v1/template/duplicate/12345 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -H "Content-Length: 0"

Example Response:

HTTP/1.1 200 OK

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

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

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

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

Query Parameters

templateId
The ID of the existing template that you want to duplicate
templateExternalId
The external ID of the existing template that you want to duplicate

Add Locations to Template

Example Request:

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

{
   "locations":[
      {
         "longitude":-122.374,
         "latitude":37.618,
         "relevantText":"Hello loc0",
         "streetAddress1":"address line #1",
         "streetAddress2":"address line #2",
         "city":"San Francisco",
         "region":"CA",
         "regionCode":"94404",
         "country":"US"
      }
   ]
}
curl -X POST https://wallet-api.urbanairship.com/v1/template/12345/locations \
    -H "Authorization: Basic <Base64 key>" \
    -H "Content-Type: application/json" \
    -H "Api-Revision: 1.2" \
    -d '{
           "locations":[
              {
                 "longitude":-122.374,
                 "latitude":37.618,
                 "relevantText":"Hello loc0",
                 "streetAddress1":"address line #1",
                 "streetAddress2":"address line #2",
                 "city":"San Francisco",
                 "region":"CA",
                 "regionCode":"94404",
                 "country":"US"
              }
           ]
        }'

Example Response:

HTTP/1.1 200 OK

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

Add locations to the specified template.

Query Parameters

templateId
The ID of the template to which you are adding locations.
templateExternalId
The external ID of the template to which you are adding locations.

JSON Parameters

longitude
Required: Longitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
latitude
Required: Latitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
relevantText
Text to display to the user when close to this location
streetAddress1
Street address
streetAddress2
Street address (continued)
city
City that the address is in
region
Region (state) that the address is in
regionCode
Postal code for this location
country
Country that the location is in

Delete Location from Template

Example Request:

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

Example Response:

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

{

}

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

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

Delete location from template.

Query Parameters

templateId
The ID of the template you’d like to delete a location from.
templateExternalId
The external ID of the template you’d like to delete a location from.
locationId
The location ID of the location you’d like to delete from the template.

List Templates

Example Request:

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

Example Response:

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

List the headers for templates belonging to you.

Query Parameters

pageSize
Number of projects per page, default is 10.
page
Page you want to retrieve, default is 1.
order
The order you want the projects returned in. Can be any one of id, name, createdAt or updatedAt; default is id.
direction
Whether you want the values ordered ascending or descending. Can be either ASC or DESC, default is DESC.

Delete Template

Example Request:

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

Example Response:

HTTP/1.1 200 OK

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

Delete the specified template.

Query Parameters

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

Passes

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

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

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

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

Example Request:

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

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

Example Response:

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

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

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

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

JSON Parameters

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

Response Codes

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

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

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

Create Pass

Example Request:

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

{
    "headers":{
        "expirationDate":{
           "value":"2014-08-20T9:41-08:00"
         },
         "barcodeAltText":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"barcode",
            "value":"abc1234567890",
            "label":""
         },
         "barcode_value":{
            "formatType":"String",
            "changeMessage":null,
            "fieldType":"barcode",
            "value":"abc1234567890",
            "label":""
         }
    },
    "fields":{
        "Text":{
           "changeMessage":"edited text value",
           "value":"Text Value",
           "label":"Text Label"
        },
        "spelledOut":{
           "changeMessage":"spelled out changed",
           "value":"888",
           "label":"Spelled Out Edited"
        },
        "Apple 2":{
           "changeMessage":"Apple 2 Changed",
           "value":"Apple 2-value",
           "label":"Apple 2-label"
        },
        "thumbnail_image":{
           "value":"https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
        }
    },
    "beacons":[
        {
           "uuid":"55502220-A123-A88A-F321-555A444B333C",
           "relevantText":"You are near the Ship",
           "major":2,
           "minor":346
        }
    ],
    "publicUrl" : {
        "type" : "single"
    }
}
curl -X POST https://wallet-api.urbanairship.com/v1/pass/123 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Content-Type: application/json" \
    -H "Api-Revision: 1.2" \
    -d '{
           "headers": {
               "expirationDate": {
                  "value": "2014-08-20T9:41-08:00"
                },
                "barcodeAltText": {
                   "formatType": "String",
                   "changeMessage": null,
                   "fieldType": "barcode",
                   "value": "abc1234567890",
                   "label": ""
                },
                "barcode_value": {
                   "formatType": "String",
                   "changeMessage": null,
                   "fieldType": "barcode",
                   "value": "abc1234567890",
                   "label": ""
                }
           },
           "fields": {
               "Text": {
                  "changeMessage": "edited text value",
                  "value": "Text Value",
                  "label": "Text Label"
               },
               "spelledOut": {
                  "changeMessage": "spelled out changed",
                  "value": "888",
                  "label": "Spelled Out Edited"
               },
               "Apple 2": {
                  "changeMessage": "Apple 2 Changed",
                  "value": "Apple 2-value",
                  "label": "Apple 2-label"
               },
               "thumbnail_image": {
                  "value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
               }
           },
           "beacons": [
               {
                  "uuid": "55502220-A123-A88A-F321-555A444B333C",
                  "relevantText": "You are near the Ship",
                  "major": 2,
                  "minor": 346
               }
           ],
           "publicUrl": {
               "type": "single"
           }
        }'

Example Response:

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

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

JSON Parameters

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

May contain the following fields:

  • formatType

    Specify the formatting type
  • changeMessage

    Notify the user if the barcode value changes, see the Apple docs for more information.
  • fieldType

    Specify the field type (set to "barcode" by default)
  • value

    Barcode value
  • label

    Human-readable label for this barcode, displayed above the barcode
barcodeAltText

May contains the same fields as barcode_value.


fields

An unordered set of named JSON objects containing pass field information:

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

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

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

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

  • type

    single or multiple use, depending on how many times it can be downloaded. All Android pass URLs are single. multiple only applicable on iOS.
  • path

    Pass URL returned in response
  • used

    Returns true or false for iOS, N/A for Android
  • installs

    Returns number of pass installs for a multiple use iOS pass, N/A for Android

Query Parameters

templateId
The ID of the template you are using to create this pass
templateExternalId
The External ID of the template you are using to create this pass
passExternalId
The external ID you want associated with the newly created pass

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

Pass Deep Linking

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

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

Get the specified pass.

JSON Parameters

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

List Passes

Example Request:

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

Example Response:

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

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

Query Parameters

templateId
integer (optional) - Return passes associated with a specific template.
status
string (optional) - Filter the returned passes based on install status. Valid status values include: “installed”: all installed passes “uninstalled”: all uninstalled passes “been_installed”: all passes that have at one point been installed “not_been_installed”: all passes that have never been installed
pageSize
string (optional) - Number of passes per page, default 10.
page
string (optional) - Page you wish to retrieve, starting with 1.
order
string (optional) - The order you want the passes returned in. Can be any one of id, createdAt, or updatedAt. Default is id.
direction
string (optional) - Whether you want the values ordered ascending or descending. Can be either ASC or DESC, default is DESC.

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

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

Example Response:

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

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

JSON Parameters

passId
The ID of the pass you wish to update.
passExternalId
The external ID of the pass you wish to update.
fields
a JSON object containing the field information.
changeMessage
The change message associated with this field.
value
Value for this field.
label
Label for this field.

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

Bulk Update Passes

Example Request:

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

{
   "fields": {
      "Member Name": {
         "value": "Jack Handey"
      },
      "barcode_value": {
         "value": "55555"
      },
      "Points": {
         "value": 1000
      }
   }
}
curl -X PUT https://wallet-api.urbanairship.com/v1/template/(templateId)/passes \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
           "fields": {
              "Member Name": {
                 "value": "Jack Handey"
              },
              "barcode_value": {
                 "value": "55555"
              },
              "Points": {
                 "value": 1000
              }
           }
        }'

Example Response:

{
   "ticketId": 56789
}
PUT /v1/template/(templateId)/passes

PUT /v1/template/(passExternalId)/passes

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

The response will be a ticketId for the bulk update.

JSON Parameters

templateId
The ID of the template for which you are updating all passes.
passExternalId
Alternative to templateId if you are referencing an external template ID

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

  • Membership ID fields

  • Coupon Codes

  • Barcode values or alternative text

  • Any other field or image on the pass

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

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

To query the ticketId, see below.

Query Ticket ID

Example Response:

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

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

Expire Pass

Example Request (update expiration date):

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

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

Example (render pass void):

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

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

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

Get Apple JSON for a Pass

Example Request:

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

Example Response:

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

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

JSON Parameters

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

Download Apple Pass Contents

Example Request:

GET /v1/pass/123/download HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X GET https://wallet-api.urbanairship.com/v1/pass/123/download \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
GET /v1/pass/(passId)/download
GET /v1/pass/id/(passExternalId)/download

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

JSON Parameters

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

Google Save to Android Pay

Example Request:

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

{
  "fields": {
    "Points": {
      "value": "600"
    }
  },
  "tag": "abc",
  "externalId": "UserName",
  "onSuccess": "mySuccessFunc()",
  "onFail": "myFailureFunc()"
}
curl -X POST https://wallet-api.urbanairship.com/v1/pass/123/saveToWallet \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
          "fields": {
            "Points": {
              "value": "600"
            }
          },
          "tag": "abc",
          "externalId": "UserName",
          "onSuccess": "mySuccessFunc()",
          "onFail": "myFailureFunc()"
        }'

Example Response:

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

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

JSON Parameters

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

Add Locations to Pass

Example Request:

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

{
  "locations": [
    {
      "longitude": "-122.374",
      "latitude": "37.618",
      "relevantText": "Hello loc0",
      "streetAddress1": "address line #1",
      "streetAddress2": "address line #2",
      "city": "San Francisco",
      "region": "CA",
      "regionCode": "94404",
      "country": "US"
    },
    { "...": "..." }
  ]
}
curl -X POST https://wallet-api.urbanairship.com/v1/pass/123/locations \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2" \
    -d '{
          "locations": [
            {
              "longitude": "-122.374",
              "latitude": "37.618",
              "relevantText": "Hello loc0",
              "streetAddress1": "address line #1",
              "streetAddress2": "address line #2",
              "city": "San Francisco",
              "region": "CA",
              "regionCode": "94404",
              "country": "US"
            },
            { "...": "..." }
          ]
        }'

Example Response:

The API will return status code 200 if successful.

[
   {
      "passLocationId":65,
      "value":{
         "region":"CA",
         "regionCode":"94404",
         "relevantText":"Hello loc0!",
         "streetAddress1":"add11",
         "streetAddress2":"add22",
         "longitude":"-122.3742",
         "latitude":"37.618",
         "city":"FC"
      }
   },
   {
      "passLocationId":66,
      "value":{
         "region":"CA",
         "regionCode":"94404",
         "relevantText":"Hello loc1!",
         "streetAddress1":"add12",
         "streetAddress2":"add23",
         "longitude":"-123.374",
         "latitude":"38.618",
         "city":"FC"
      }
   }
]
POST /v1/pass/(passId)/locations
POST /v1/pass/id/(passExternalId)/locations

Add the locations to the specified pass

JSON Parameters

passId
The ID of the pass you want to add locations to.
passExternalId
The external ID of the pass you want to add locations to.
longitude
Required Longitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
latitude
Required Latitude of the location. Value must include a decimal point, e.g., 3.0 rather than 3.
relevantText
Text to display to the user when close to this location.
streetAddress1
Street Address
streetAddress2
Street Address (continued)
city
City that the address is in
region
Region (state) that the address is in
regionCode
Postal code for this location
country
Country that the location is in

Delete Location from Pass

Example Request:

DELETE /v1/pass/123/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X DELETE https://wallet-api.urbanairship.com/v1/pass/123/location/456 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
DELETE /v1/pass/(passId)/location/(locationId)
DELETE /v1/pass/id/(passExternalId)/location/(locationId)

Delete the specified location from the specified pass.

Query Parameters

passId
The ID of the pass you want to delete the location from.
passExternalId
The external ID of the pass you want to delete the location from.
locationId
The ID of the location you want to delete from the pass.

Response Codes

code 200
Success

Delete Pass

Example Request:

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

Example Response:

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

Delete the specified pass.

Query Parameters

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

Response Codes

code 200
Success

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

barcode
value will change the barcode
barcodeAltText
alternative text associated to the barcode. If we have no barcodeAtlTexparameter specified the actual barcode value will be used as barcodeAltText.
tags
tags that should be associated to the pass.
exid
the external id that is associated with pass that is created
lat
the longitude of the device, which is used to calculate the distance to locations that are provided when the Adaptive Link was created
long
the latitude of the device, which is used to calculate the distance to locations that are provided when the Adaptive Link was created

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.

For iOS, if your maxium number of locations is greater than 10, we will only use the 10 closest locations due to Apple's limit of 10 per pass.

API Endpoints

Endpoints are provided for Adaptive Link creation, listing, update, and deletion.

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
}
POST /v1/links/<adaptiveLinkId>

Adaptive Link creation accepts the following JSON fields:

JSON Parameters

iosTemplateId
String (conditionally optional) an iOS template id
androidTemplateId
String (conditionally optional) an Android template id
payload
String (conditionally optional) a payload used to create associated Dynamic Link objects for each device type
iosPassLinkId
String (conditionally optional) the serial number of an already created Dynamic Link for iOS devices
androidPassLinkId
String (conditionally optional) the serial number of a previously generated Dynamic Link for Android devices
isPersonalized
boolean (optional) if 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).
landingPageUrl
String (conditionally optional) a landing page URL to which requests are redirected if the device type from which the request originates cannot be detected (or is not supported)
availablePasses
Integer (conditionally optional) a number specifying how many passes can be created from this Adaptive Link. If this field is absent, the number of passes is not limited.

Location JSON

JSON Parameters

locations
list of locations (see below)
locationRadius
Integer (conditionally optional)
maxResultLocations
Integer (conditionally optional)
latitude
Double (required) the latitude of this location
longitude
Double (required) the longitude of this location
city
String (conditionally optional) a city name
country
String (conditionally optional) a country name
region
String (conditionally optional) a region or state name
regionCode
String (conditionally optional) a region or zip code
streetAddress1
String (conditionally optional) first address line
streetAddress2
String (conditionally optional) second address line
relevantText
String (conditionally optional) the relevant text which is shown as lock text with IOS

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

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
}
GET /v1/links/adaptive/<adaptiveLinkId>

Gets the specified link URL(s).

Response Codes

400 Not Found
could not find an entry with specified adaptiveLinkId
Authentication
Requires API key

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
}
PUT /v1/links/adaptive/<adaptiveLinkId>

Response Codes

404 NOT FOUND
Could not find templates or Adaptive Link object(s)
Authentication
Requires API key
DELETE /v1/links/adaptive/<adaptiveLinkId>

Deletes the specified link.

Response Codes

200 OK
link deleted successfully
400 Not Found
could not find an entry with specified adaptiveLinkId
Authentication
Requires API key
GET /v1/pass/<adaptiveLinkId>/[<deviceType>]

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

adaptiveLinkId
String. See Create Adaptive Link
deviceType
String (optional) The device type as ios, android or web

Response 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

GET /v1/pass/<adaptiveLinkId>/[<deviceType>]?fieldName1=aValue&fieldName2=aValue

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

Example Response:

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

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

Query Parameters

passId
The ID of the pass you want to add tags to.
passExternalId
The external ID of the pass you want to add tags to.

JSON Parameters

newTags
The tags that were added to this pass. Does not include tags that you requested be added but already existed on the pass.
mappings
The number of tags added to the pass.

List Tags for Pass

Example Request:

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

Example Response:

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

Get the tags that the specified pass has.

Query Parameters

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

List All Tags

Example Request:

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

Example Response:

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

List all tags.

Query Parameters

pageSize
Number of tags per page, default is 10.
page
Page you want to retrieve, starting with 1.
order
The order you want the tags returned in. Can be id or createdAt; default is id.
direction
Whether you want the values ordered ascending or descending. Can be either ASC or DESC, default is DESC.

List Passes for Tag

Example Request:

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

Example Response:

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

List the passes with this tag.

Query Parameters

tag
The tag that you want the passes for.
pageSize
Number of tags per page, default 10.
page
Page you want to retrieve, starting with 1.
order
The order you want the tags returned in. Can be any one of id, createdAt, or updatedAt; default is id.
direction
Whether you want the values ordered ascending or descending. Can be either ASC or DESC, default is DESC.

Update Passes by Tag

Example Request:

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

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

Example Response:

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

Update all of the passes that have a given tag.

Query Parameters

tag
The tag you wish to update the passes for

JSON Parameters

fields
A JSON Object containing the fields you want to update on the passes.

Remove Tag from Pass

Example Request:

DELETE /v1/tag/tag-name/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
curl -X DELETE https://wallet-api.urbanairship.com/v1/tag/tag-name/pass/123 \
    -H "Authorization: Basic <Base64 key>" \
    -H "Api-Revision: 1.2"
DELETE /v1/tag/(tag)/pass/(passId)

Example Response:

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

Remove the tag from the specified pass.

Query Parameters

tag
The tag you wish to remove from the pass.
passId
The ID of the pass you wish to remove the tag from.
passExternalId
The external ID of the pass you wish to remove the tag from.

Delete Tag

Example Request:

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

Example Response:

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

Delete the specified tag and remove it from all passes.

Query Parameters

tag
The tag you wish to delete

Segments

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

Create Segment

Example Request:

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

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

Example Response:

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

Create a segment for the project.

Query Parameters

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

List Segments

Example Request:

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

Example Response:

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

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

Query Parameters

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

Get Segment

Example Request:

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

Example Response:

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

Get segment data for a project’s segment.

Query Parameters

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

Update Segment

Example Request:

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

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

Example Response:

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

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

Query Parameters

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

Delete Segment

Example Request:

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

Example Response:

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

Delete project’s segment.

Query Parameters

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

Schedules

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

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

Schedule an Update

Example request:

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

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

Example response:

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

Schedule an update

JSON Parameters

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

List Schedules

Example request:

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

Example response:

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

Returns list of schedules for a project

Query Parameters

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

Get Schedule

Example request:

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

Example response:

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

Get schedule data for a project’s schedule

Query Parameters

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

Update Schedule

Example request:

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

Example response:

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

Update project’s schedule (identified by scheduleId)

Query Parameters

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

Delete Schedule

Example request:

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

Example response:

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

Delete project’s schedule

Query Parameters

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

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"
   }
}
POST /v1/project/<projectId>/settings/callback

Register a callback specification which includes remote the URL and any HTTP headers required by remote URL

Query Parameters

projectId
Project ID for which you want to register a callback.
baseUrl
The remote server URL that implemenents callback endpoints
headers
Contains all the HTTP headers required by remote API endpoints including "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 /v1/project/<projectId>/settings/callback

Get callback specification

Query Parameters

projectId
Project ID for which you want to retrieve the callback specification..

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"
   }
}
PUT /v1/project/<projectId>/settings/callback

Update callback specification

Query Parameters

projectId
Project ID for which you want to update the callback specification..

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 /v1/project/<projectId>/settings/callback

Delete registered callback specification

Query Parameters

projectId
Project ID for which you want to delete the callback specification, i.e., unsubscribe from event notifications on pass install/uninstall etc.

List Callback Events

iOS Only

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"
}
POST {baseUrl}/v1/pass/install

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"
}
POST {baseUrl}/v1/pass/uninstall

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"
   }
}
POST {baseUrl}/v1/pass/{passId}/personalize

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
}
GET /v1/template/(templateId)/stats

Return template statistics for a given template ID.

Query Parameters

templateId
The template ID.

JSON Parameters

id
The template ID.
vendor
The template vendor.
lastUpdated
The date the template was last updated.
total
The total number of passes generated from this template.
installed
The number of passes generated from this template that were installed.
uninstalled
The number of passes generated from this template that were uninstalled.
GET /v1/template/id/(templateExternalId)/stats

Return template statistics for a given template external ID.

Query Parameters

templateExternalId
The template external ID.

Template Activity

Example Request

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

Example Response

{
    "id": 1234,
    "vendor": "Apple",
    "startDate": "2015/08/19",
    "endDate": "2015/08/25",
    "summary": {
        "created": 113,
        "installed": 0,
        "uninstalled": 0
    },
    "details": [
        {
            "date": "2015/08/19",
            "activity": {
                "created": 111,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/20",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/21",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/22",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/23",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/24",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/25",
            "activity": {
                "created": 2,
                "installed": 0,
                "uninstalled": 0
            }
        }
    ]
}
GET /v1/template/(templateId)/activity
GET /v1/template/(templateId)/activity/(startDate)/(endDate)
GET /v1/template/id/(templateExternalId)/activity
GET /v1/template/id/(templateExternalId)/activity/(startDate)/(endDate)

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

JSON Parameters

id
The template ID.
vendor
The template vendor.
startDate
The start date of the returned data.
endDate
The end date of the returned data.
summary
An object containing the total number of passes created, installed, and uninstalled. created The number of passes, generated from this template, that were created in this time period. installed The number of passes, generated from this template, that were installed in this time period. uninstalled The number of passes, generated from this template, that were uninstalled within this time period.
details
An array of template activity detail objects. Each object contains a date, and then the activity (passes created, installed, and uninstalled) that occurred on that day.

Project Statistics

By Project ID

Example Request

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

Example Response

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

By Project External ID

Example Request

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

Example Response

{
    "id": 12345,
    "lastUpdated": "2015-10-01T20:15:29.000-07:00",
    "templates": [
        {
            "id": 1234,
            "vendor": "Apple",
            "lastUpdated": "2015-10-01T20:15:29.000-07:00",
            "total": 2194,
            "installed": 2,
            "uninstalled": 7
        }
    ],
    "total": 2194,
    "installed": 2,
    "uninstalled": 7
}
GET /v1/project/(projectId)/stats

Return project statistics for a given project ID.

Query Parameters

ID
The project ID.

JSON Parameters

id
The project ID.
lastUpdated
The date the project was last updated.
templates
An array of .
total
The total number of passes generated by this project.
installed
The number of passes generated by this project that were installed.
uninstalled
The number of passes generated by this project that were uninstalled.
GET /v1/project/id/(projectExternalId)/stats

Return project statistics for a given project external ID.

Query Parameters

projectExternalId
The project external ID.

Project Activity

Example Request

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

Example Response

{
    "id": 12345,
    "startDate": "2015/08/19",
    "endDate": "2015/08/25",
    "summary": {
        "created": 113,
        "installed": 0,
        "uninstalled": 0
    },
    "details": [
        {
            "date": "2015/08/19",
            "activity": {
                "created": 111,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/20",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/21",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/22",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/23",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/24",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/25",
            "activity": {
                "created": 2,
                "installed": 0,
                "uninstalled": 0
            }
        }
    ]
}
GET /v1/project/(projectId)/activity
GET /v1/project/(projectId)/activity/(startDate)/(endDate)
GET /v1/project/id/(projectExternalId)/activity
GET /v1/project/id/(projectExternalId)/activity/(startDate)/(endDate)

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

JSON Parameters

id
The project ID.
startDate
The start date of the returned data.
endDate
The end date of the returned data.
summary
An object containing the total number of passes created, installed, and uninstalled. created The number of passes, generated within this project, that were created in this time period. installed The number of passes, generated within this project, that were installed in this time period. uninstalled The number of passes, generated within this project, that were uninstalled within this time period.
details
An array of project activity detail objects. Each object contains a date, and then the activity (passes created, installed, and uninstalled) that occurred on that date.

Tickets

Get Ticket Status

Example Request:

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

Example Response:

{
   "Status": "COMPLETED",
   "createdAt": "2013-03-28 18:18:36.0",
   "ID": 123,
   "children": {
      "...": "..."
   }
}
GET /v1/ticket/(ticketId)

Get the status of a ticket

JSON Parameters

ticketId
The ID of the ticket you want the status for

Get System Status

Example Request:

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

Example Response:

{
    "Hello": "World"
}
GET /v1/system/status

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

JSON Parameters

Hello
{ “Hello”: “World” } response available solely for communication/status checks

Cert Management

The certificate management API manages certificates for Apple Wallet.

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

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

Add New Certificate

Example Request:

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

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

Example Responses:

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

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

{
    "error" : {
        "code": 123,
        "message":"descriptive error message"
    }
}
POST /v1/certificates/

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

Response Codes

200 OK
The certificate was added successfully (see JSON above).
400 BAD REQUEST
Internal code 1201 Specified vendor does not match the p12 file content.
400 BAD REQUEST
Internal code 1202 Invalid p12 file. The provided p12 is can not be opene because it does not contain the proper information.
400 BAD REQUEST
Internal code 1203 We could not open the p12 file with the specified password.

Update Certificate

Example Request:

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

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

Example Response:

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

{
    "error" : {
        "code": 123,
        "message":"Major fail"
    }
}
PUT /v1/certificates/{id}

Response Codes

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

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

  • The following fields can be updated directly: enabled, default, comment and name.

  • If fields enabled and default are not specified they won’t be changed.

  • If fields comment and name are not specified, we assume the value needs to be removed. If you don’t want to change the value, specify "comment": null or "name": null.

  • Some of the fields will be extracted from the certificate and will be updated indirectly: teamIdentifier and baseName.

  • The field updatedAt will change with each update.

  • The field createdAt cannot be changed.

  • If the user specifies an invalid id in the path or no certificate can be found we will return an error (see below).

  • Changing the default certificate is done by setting the new certificate "default" : true.

  • Setting default to false on the default certificate will throw an exception.

Get Certificate

Example Response:

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

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

{
    "error" : {
        "code": 123,
        "message":"Could not find the specified certificate"
    }
}
GET /v1/certificates/{id}

Response Codes

200 OK
We found the specified certificate (see JSON above)
400 BAD REQUEST
Internal code 1101 Invalid id, the id has to be a valid UUID.
404 NOT FOUND
Internal code 1204 The specified certificate could not be found.

List Certificates

Example Response:

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

{
    "nextPage": "https://wallet.urbanairship.com/v1/certificates/list/?page=11&pageSize=10",
    "count": 2,
    "pagination": {
        "order": "name",
        "page": "1",
        "start": "0",
        "direction": "DESC",
        "pageSize": 10
    },
    "certificates":[
        {
            "id": "40adce15-5c52-479d-8620-54c21cd851a6",
            "vendor": "Apple",
            "baseName": "xyz1",
            "name": "editable name1",
            "comment": "something about this cert",
            "teamIdentifier": "XYZ",
            "enabled": true,
            "default": true,
            "createdAt": "2016-05-26T22:23:21Z",
            "updatedAt": "2016-05-26T22:23:21Z",
            "templates" : [
                {"id": 123, "name": "templateName1"},
                {"id": 221, "name": "templateName2"}
            ]
        },
        {
            "id":"12adce15-5c52-479d-8620-54c21cd851aa",
            "vendor": "Apple",
            "baseName", "xyz2",
            "name": "editable name1",
            "comment": "something about this cert",
            "teamIdentifier" : "XYZ",
            "enabled": false,
            "default": false,
            "createdAt": "2016-05-26T23:23:21Z",
            "updatedAt": "2016-05-27T17:22:00Z",
            "templates" : [
                {"id": 123, "name": "templateName1"},
                {"id": 221, "name": "templateName2"}
            ]
        }
    ]
}
GET /v1/certificates?vendor=Apple&page=0&pageSize=10

Query Parameters

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

Response Codes

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

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

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

Delete Certificate

Example Response:

HTTP/1.1 201 Deleted

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

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

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

{
    "error" : {
        "code": 304,
        "message":"Could not find the specified certificate"
    }
}
DELETE /v1/certificates/{id}

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

Response Codes

201 Deleted
We found the specified certificate and deleted it
404 NOT FOUND
Internal code 1204 The specified certificate could not be found.
400 BAD REQUEST
Internal code 1101 Invalid id, the id has to be a valid UUID.

JSON Fields Description

This section explains the various JSON fields in detail.

Certificate Fields

  • id - string (optional, read only) - certificate id; it is optional because when we add a certificate we don’t have an id yet.

  • vendor string - “Apple” is the only vendor currently supported

  • cert string base64 encoded (optional) - p12 file base64 encoded in json

  • baseName string (read only) - this name is extracted from the certificate and cannot be changed

  • name string (optional, read only) - the user can provide an additional name; if it is not provided, the filename of the p12 file will be used.

  • comment string (optional) - text to describe the certificate

  • enabled boolean (optional) - true to have this certificate enabled false to have this certificate disabled

  • default boolean (optional) - indicates whether this certificate is used as the default certificate. If the user has multiple certificates and he/she sets a new default, the previously default certificate will be changed to default false.

  • templates list (optional) - a list of of templates that are associated with this certificate. Each entry has the members specified below.

  • teamIdentifier string (optional, read only) - required for the Apple certificate but not used for the Google certificate

  • createdAt date (optional, read only) - the date of creation

  • updatedAt date (optional, read only) - the date of update; when the certificate is added/created the updateAt is set to the same date as the createdAt

General Response Fields

  • nextPage string (optional)

  • certificates list of Certificates (optional) - used for list certificates endpoint

  • count number (optional) - used for the list certificates endpoint

  • pagination pagination fields (optional) - all the fields used for pagination (see below)

  • error error response fields (optional) - used in the case of an error

Pagination Fields

  • page number (optional) - used for the list certificates endpoint; the page number

  • start number (optional) - start index of the page

  • pageSize number (optional) - used for the list certificates endpoint

  • direction number (optional) - used for the list certificates endpoint; direction of the order ASC or DESC

  • order string (optional) - defines on which provided field you want to order the list of certificates The following fields may be used for ordering: name, baseName, createdAt, updatedAt

Template List Contents

  • id number - the template id

  • name string - the name of the template

Error Response Fields

  • code number - error code

  • message string - some details about this error

Never miss out on product updates

Click "Allow" in the browser prompt in the upper left hand corner of your browser.

Next, we'll allow you to choose what sort of notifications you'd like to receive.

Choose your notification topics

Product Subscription Options

    Platform Subscription Options