Wallet API

Airship’s REST API for Mobile Wallet projects. Use this API to create Apple Wallet and Google Wallet passes for your customers.

Libraries

Airship maintains open source server libraries to support your integrations with our APIs in multiple languages. Click below for library documentation.

Introduction

The Wallet API provides programmatic access to Airship Wallet service, where you can create passes for Apple Wallet and Google Wallet. Passes are:

  • Created from templates within a project. The project determines the types of templates and passes you create; your templates determine the style and default data for your passes.
  • Distributed as links—When creating a pass or an adaptive link, you are creating a link. Users tap this link (or scan a QR code representing the link, etc.) to install the pass on their device.
  • Customizable—Add relevant data to your users when they install your pass.
  • Updatable with relevant field and value changes. After users install your passes, you can update passes with relevant field and values so your users’ passes are always up to date.

For a better understanding of Airship Wallet projects and passes, see How mobile wallet works.

See the Getting Started Guide for help setting up an Airship Wallet project.

API Request Format

All API requests are HTTP requests. For all requests with a body, the body may be in JSON format or other formats like CSV as specified for the endpoint. The proper Content-Type for JSON is application/json and the proper content type for CSV is text/csv.

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: 2023-01-28T15:00-05:00

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 Wallet dashboard. It is your responsibility to keep this key well-guarded, as it represents your identity.
  • You will use your own Apple Pass Type Certificate or Google Pay certificate to sign production passes.

Specifying a Version

The current version of the Wallet API is 1.2. The versioning for the Wallet API is currently distinct from the versioning for the 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.

External IDs

Most endpoints support an externalId parameter in the path. While all assets within this API typically have an internal id, you can use the externalId parameter to grant custom identifiers to your assets — projects, templates, passes, etc. These identifiers can make your assets more recognizable and help you integrate with an external application or system.

If you want to use external IDs, you should use them for all assets — projects, templates, passes, etc.

In general you can support external IDs by appending /id/{externalId} to an endpoint path that would either take or generate a standard id.

Base URL

Select the domain associated with your Airship project.

  • The North American base URL for Wallet endpoints, including the API major version number. In addition to the major version, all requests must include an Api-Revision header, with a more specific version number, e.g., 1.2.
  • The European base URL for Wallet endpoints, including the API major version number. In addition to the major version, all requests must include an Api-Revision header, with a more specific version number, e.g., 1.2.
  • The deprecated base URL for Wallet (formerly known as Reach) endpoints. Use https://wallet-api.urbanairship.com/v1 instead.

Authentication

  • HTTP Authentication

    Basic Auth

    All Wallet operations use basic authorization. The authorization header contains the word Basic followed by a space and a Base64-encoded string generated from your Project Key and Project Secret in projectKey:projectSecret format. For example, Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0.

    You can copy you Project Key and Secret from your Wallet project. Go to Settings, then API.

    Only TLS 1.2 and TLS 1.3 are supported for Wallet API endpoint access. See also: Mobile Wallet Reference: Security.

Project

A project contains your templates and a collection of passes and determines the types of templates and passes you can create. You must specify a project for all operations in Wallet.

List Projects

Example Request

GET /v1/project HTTP/1.1
Authorization: Basic <Base64 key>
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",
      "contextId": "myvWKam4QN9Iu2K2fXK-Bd",
      "templates": [
      ],
      "settings": {
        "barcode_alt_text": "123456789",
        "barcode_default_value": "123456789",
        "barcode_encoding": "iso-8859-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",
      "contextId": "myvULam4QN3Iu2K4fXK-Bf",
      "templates": [
      ],
      "settings": {
        "barcode_alt_text": "123456789",
        "barcode_default_value": "123456789",
        "barcode_encoding": "iso-8859-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 /project

List the projects belonging to you.

Security:

query PARAMETERS
  • pageSize : Integer

    The number of results per page. Defaults to 10.

  • page : Integer

    The page of the search you want to return.

  • order : String

    Determines the order of results. Defaults to id.

    Possible values: id, name, createdAt, updatedAt

  • direction : String

    The direction of the result set, ascending or descending. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Responses

  • 200

    An array of projects belonging to you.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      OBJECT PROPERTIES
      • count : String

        The total number of results.

      • pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

      • projects : Array [Project Response]

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

Example Response

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

{
  "updatedAt": "2013-07-01T19:57:36.190Z",
  "id": "12345",
  "contextId":"nEkzVdIcTP2eNqP1--xQ_A",
  "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 /project

Create an empty project. Your project is based around the type of passes you want to create and the type of barcode you will include on your passes.

The response includes an id and contextId. Use these values to access your project via the API and dashboard, respectively.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Request Body

Create a project. Your project is based around a pass type and your certificates.

  • Content-Type: application/json; charset=utf-8

    Project Request

    A project request determines the type of passes you can create and the types of barcode your passes will use.

Responses

  • 200

    Create a project. Your project is based around a pass type and your certificates.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.

Duplicate Project

Example Request

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

Example Response

{
   "createdAt":"2018-06-04T23:26:43Z",
   "settings": {
    "barcode_alt_text": "123json=456789",
    "barcode_label": "Member ID",
    "barcode_default_value": "123456789",
    "barcode_encoding": "iso-8859-1",
    "barcode_type": "pdf417"
  },
   "templates":[
   ],
   "name":"Copy of LoyaltyCard",
   "projectType":"loyalty",
   "description":"Aztec Barcode",
   "contextId":"nEkzVdIcTP2eNqP1--xQ_A",
   "id":12346,
   "updatedAt":"2018-06-04T23:26:43Z"
}

POST /project/duplicate/{projectId}

Duplicate a project by ID. The duplicate project will be named “Copy of [ProjectName]” and have a new id but will otherwise use the same settings and templates as the original project. The response payload returns the same information as a Get Project call, with new identifiers for the new project.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project you want to copy.

Responses

  • 200

    A project and a list of templates within the project.

    RESPONSE BODY
    • Content-Type: application/json

      A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.

Get Project

Example Request

GET /v1/project/12345 HTTP/1.1
Authorization: Basic <Base64 key>
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",
  "contextId":"myvWLcm8QN3Iq2K4fXT-Bv",
  "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": {
    "barcode_alt_text": "123456789",
    "barcode_default_value": "123456789",
    "barcode_encoding": "iso-8859-1",
    "barcode_label": "Member ID",
    "barcode_type_text": "Aztec",
    "barcode_type": "aztec"
  },
  "name": "Aztec Barcode",
  "projectType": "loyalty"
}

GET /project/{projectId}

Get the project with the specified id. The response includes information about the project (set when Creating a Project) and an array of templates associated with the project. The templates array contains all the information found in the templateHeader object.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

Responses

  • 200

    A project and a list of templates within the project.

    RESPONSE BODY
    • Content-Type: application/json

      A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.

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

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 /project/{projectId}

Update a project.

 Note

Provide only the fields you want to update. While this payload takes any of the keys used when creating a project, any keys you do not provide are unchanged.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

Request Body

An update request can take the same payload as a Create Project request. However, you should provide only the keys you want to update; keys you do not provide will remain unchanged.

  • Content-Type: application/json

    Project Request

    A project request determines the type of passes you can create and the types of barcode your passes will use.

Responses

  • 200

    Returns project metadata and a list of templates for the project.

    RESPONSE BODY
    • Content-Type: application/json

      A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.

List NFC Merchants

Example Request

GET /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{
  "merchants": [
    {
      "merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
      "projectId": 13137,
      "vendor": "APPLE",
      "merchantName": "XYZ Merchant",
      "merchantEmail": "xyz@example.com",
      "terminalProvider": "Verifone",
      "publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
      "keyVersion": 1,
      "keySource": "GENERATED",
      "updatedAt": "2020-09-16T19:16:28.000Z"
    },
  
    {
      "merchantId": "70407b66-ffbc-41bf-bf13-7814caf1d2bc",
      "projectId": 13137,
      "vendor": "GOOGLE",
      "merchantName": "UA",
      "merchantEmail": "wallet@airship.com",
      "terminalProvider": "Test Tool",
      "publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo\n4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==\n",
      "keyVersion": 1,
      "keySource": "IMPORTED",
      "smartTapIssuerId": "3388000000005375425",
      "smartTapCollectorId": "23405818",
      "updatedAt": "2020-09-09T00:19:45.000Z"
    }
  ]
}

GET /project/{projectId}/nfcMerchants

Return all NFC merchant information for a project.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project you want to add or lookup NFC merchant information for.

Responses

  • 200

    Returns all NFC merchants associated with your Airship wallet project.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • merchants : Array [Object]

        ARRAY ITEM
        • A response contains information generated by Airship and/or gathered from Google Wallet services.

          All of
          • Object

            Describes NFC support for your project (and related templates/passes).

            OBJECT PROPERTIES
            • keyVersion : Integer

              The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

            • merchantEmail : String

              The google merchant email address, used when configuring smartTap.

            • merchantName : String

              The google merchant name, used when configuring smartTap.

            • publicKeyPem : String

              The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

            • smartTapCollectorId : String

              Defines your Google Wallet merchant.

            • terminalProvider : String

              The NFC terminal provider that can read NFC messages, like Verifone.

            • vendor : StringREQUIRED

              Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

              Possible values: GOOGLE, APPLE, ANY

          • Object

            OBJECT PROPERTIES
            • keySource : String

              Set by Airship, either GENERATED if Airship generates your public/private keys or IMPORTED if you provide your own publicKey.

              Possible values: GENERATED, IMPORTED

            • merchantId : String

              The Airship-generated UUID for your NFC merchant information.

            • privateKeyPem : String

              Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the publicKeyPem).

            • projectId : Integer

              The ID of the project. Use this ID to reference your project in the API.

            • smartTapIssuerId : String

              Google only, represents your platform and may contain more than one collectorId.

            • updatedAt : String

              The date and time when your NFC merchant information was last updated. Format: date-time

Add an NFC Merchant

Example Request — APPLE and GOOGLE vendors

POST /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

{
  "vendor": "ANY",
  "merchantName": "testMerchant5",
  "merchantEmail": "test@example.com",
  "terminalProvider": "Verifone",
  "publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
  "keyVersion": 1,
  "keySource": "IMPORTED"
}

Example Response

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

{
  "merchantId": "a535fc29-9e90-434a-b8e9-4a5851292ccc",
  "projectId": 13137,
  "vendor": "APPLE",
  "merchantName": "testMerchant5",
  "merchantEmail": "test@example.com",
  "terminalProvider": "Verifone",
  "publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
  "keyVersion": 1,
  "keySource": "IMPORTED",
  "updatedAt": "2020-09-16T18:17:49.349Z"
}

POST /project/{projectId}/nfcMerchants

Provide your merchant information and keys to support NFC interaction with passes and SmartTap for Android. When your project is NFC enabled, your audience can tap their device to a terminal to use their passes — consume point balances, use coupons, scan boarding passes, etc.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project you want to add or lookup NFC merchant information for.

Request Body

  • Content-Type: application/json

    Object

    Describes NFC support for your project (and related templates/passes).

    OBJECT PROPERTIES
    • keyVersion : Integer

      The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

    • merchantEmail : String

      The google merchant email address, used when configuring smartTap.

    • merchantName : String

      The google merchant name, used when configuring smartTap.

    • publicKeyPem : String

      The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

    • smartTapCollectorId : String

      Defines your Google Wallet merchant.

    • terminalProvider : String

      The NFC terminal provider that can read NFC messages, like Verifone.

    • vendor : StringREQUIRED

      Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

      Possible values: GOOGLE, APPLE, ANY

Responses

  • 200

    Returns the newly-added NFC merchant information for your project.

    RESPONSE BODY
    • Content-Type: application/json

      A response contains information generated by Airship and/or gathered from Google Wallet services.

      All of
      • Object

        Describes NFC support for your project (and related templates/passes).

        OBJECT PROPERTIES
        • keyVersion : Integer

          The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

        • merchantEmail : String

          The google merchant email address, used when configuring smartTap.

        • merchantName : String

          The google merchant name, used when configuring smartTap.

        • publicKeyPem : String

          The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

        • smartTapCollectorId : String

          Defines your Google Wallet merchant.

        • terminalProvider : String

          The NFC terminal provider that can read NFC messages, like Verifone.

        • vendor : StringREQUIRED

          Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

          Possible values: GOOGLE, APPLE, ANY

      • Object

        OBJECT PROPERTIES
        • keySource : String

          Set by Airship, either GENERATED if Airship generates your public/private keys or IMPORTED if you provide your own publicKey.

          Possible values: GENERATED, IMPORTED

        • merchantId : String

          The Airship-generated UUID for your NFC merchant information.

        • privateKeyPem : String

          Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the publicKeyPem).

        • projectId : Integer

          The ID of the project. Use this ID to reference your project in the API.

        • smartTapIssuerId : String

          Google only, represents your platform and may contain more than one collectorId.

        • updatedAt : String

          The date and time when your NFC merchant information was last updated. Format: date-time

Get an NFC Merchant

Example Request

GET /v1/project/<projectId>/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{
  "merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
  "projectId": 13137,
  "vendor": "GOOGLE",
  "merchantName": "testMerchant5",
  "merchantEmail": "test@example.com",
  "terminalProvider": "Verifone",
  "publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
  "keyVersion": 1,
  "keySource": "GENERATED",
  "updatedAt": "2020-09-16T18:20:45.000Z"
}

GET /project/{projectId}/nfcMerchants/{merchantId}

Get an individual NFC merchant.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project you want to add or lookup NFC merchant information for.

  • merchantId : StringREQUIRED

    The merchant ID you want to modify.

Responses

  • 200

    Returns the merchant information associated with the merchantId.

    RESPONSE BODY
    • Content-Type: application/json

      A response contains information generated by Airship and/or gathered from Google Wallet services.

      All of
      • Object

        Describes NFC support for your project (and related templates/passes).

        OBJECT PROPERTIES
        • keyVersion : Integer

          The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

        • merchantEmail : String

          The google merchant email address, used when configuring smartTap.

        • merchantName : String

          The google merchant name, used when configuring smartTap.

        • publicKeyPem : String

          The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

        • smartTapCollectorId : String

          Defines your Google Wallet merchant.

        • terminalProvider : String

          The NFC terminal provider that can read NFC messages, like Verifone.

        • vendor : StringREQUIRED

          Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

          Possible values: GOOGLE, APPLE, ANY

      • Object

        OBJECT PROPERTIES
        • keySource : String

          Set by Airship, either GENERATED if Airship generates your public/private keys or IMPORTED if you provide your own publicKey.

          Possible values: GENERATED, IMPORTED

        • merchantId : String

          The Airship-generated UUID for your NFC merchant information.

        • privateKeyPem : String

          Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the publicKeyPem).

        • projectId : Integer

          The ID of the project. Use this ID to reference your project in the API.

        • smartTapIssuerId : String

          Google only, represents your platform and may contain more than one collectorId.

        • updatedAt : String

          The date and time when your NFC merchant information was last updated. Format: date-time

Update NFC Merchant Information

Example Request

PUT /v1/project/<projectId>/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

{
  "merchantName": "Example Merchant",
  "merchantEmail": "my_merchant@example.com"
}

Example Response

{
  "merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
  "projectId": 13137,
  "vendor": "GOOGLE",
  "merchantName": "XYZ Merchant",
  "merchantEmail": "xyz@example.com",
  "terminalProvider": "Verifone",
  "publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
  "keyVersion": 1,
  "keySource": "GENERATED",
  "updatedAt": "2020-09-16T19:16:28.877Z"
}

PUT /project/{projectId}/nfcMerchants/{merchantId}

Update your NFC merchant information.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project you want to add or lookup NFC merchant information for.

  • merchantId : StringREQUIRED

    The merchant ID you want to modify.

Request Body

You cannot update your public/private key. If you need to update keys, you should add a new NFC merchant configuration using new keys and delete the existing configuration.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • merchantEmail : String

      The google merchant email address, used when configuring smartTap.

    • merchantName : String

      The google merchant name, used when configuring smartTap.

Responses

  • 200

    Returns your updated merchant information.

    RESPONSE BODY
    • Content-Type: application/json

      A response contains information generated by Airship and/or gathered from Google Wallet services.

      All of
      • Object

        Describes NFC support for your project (and related templates/passes).

        OBJECT PROPERTIES
        • keyVersion : Integer

          The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

        • merchantEmail : String

          The google merchant email address, used when configuring smartTap.

        • merchantName : String

          The google merchant name, used when configuring smartTap.

        • publicKeyPem : String

          The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

        • smartTapCollectorId : String

          Defines your Google Wallet merchant.

        • terminalProvider : String

          The NFC terminal provider that can read NFC messages, like Verifone.

        • vendor : StringREQUIRED

          Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

          Possible values: GOOGLE, APPLE, ANY

      • Object

        OBJECT PROPERTIES
        • keySource : String

          Set by Airship, either GENERATED if Airship generates your public/private keys or IMPORTED if you provide your own publicKey.

          Possible values: GENERATED, IMPORTED

        • merchantId : String

          The Airship-generated UUID for your NFC merchant information.

        • privateKeyPem : String

          Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the publicKeyPem).

        • projectId : Integer

          The ID of the project. Use this ID to reference your project in the API.

        • smartTapIssuerId : String

          Google only, represents your platform and may contain more than one collectorId.

        • updatedAt : String

          The date and time when your NFC merchant information was last updated. Format: date-time

Delete an NFC Merchant

Example Request

DELETE /v1/project/<projectId>/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Request

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

{
  "merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
  "updatedAt": "2020-09-16T18:20:45.000Z"
}

DELETE /project/{projectId}/nfcMerchants/{merchantId}

Delete an NFC merchant. Deleting your NFC information prevents users from redeeming passes using NFC for the associated terminal, unless you have already added new/different NFC information to your project.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project you want to add or lookup NFC merchant information for.

  • merchantId : StringREQUIRED

    The merchant ID you want to modify.

Responses

  • 200

    The merchant information was deleted.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • merchantId : String

        The merchant ID that you deleted. Format: uuid

      • updatedAt : String

        The date and time when the merchant information was deleted. Format: date-time

Project with external ID

Endpoints for projects using external IDs. A project contains your templates and a collection of passes and determines the types of templates and passes you can create. You must specify a project for all operations in Wallet.

Duplicate Project with external ID

Example Request

POST /v1/project/duplicate/id/mycustomid HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

{
    "createdAt": "2024-01-25T03:23:19Z",
    "settings": {},
    "appleCertificateId": "f5cbc01b-3c56-460c-8dca-ba1c327691e6",
    "templates": [
        {
            "projectType": "generic",
            "description": "a new template",
            "vendorId": 1,
            "type": "Generic",
            "createdAt": "2024-01-25T03:23:20Z",
            "deleted": "False",
            "vendor": "Apple",
            "name": "Copy of asykes-template-1234123",
            "disabled": "False",
            "id": "179192",
            "expiryDuration": 730,
            "projectName": "Copy of my test project",
            "projectId": 7425,
            "updatedAt": "2024-01-25T03:23:20Z"
        }
    ],
    "name": "Copy of my test project",
    "projectType": "generic",
    "description": "test project",
    "externalId": "Copy_of_mycustomid",
    "contextId": "4KN8Q9s-Qm68Ks9JF2A33g",
    "id": 7425,
    "updatedAt": "2024-01-25T03:23:19Z"
}

POST /project/duplicate/id/{externalId}

Duplicate a project by external ID. The duplicate project will be named “Copy of [ProjectName]” and have a new id but will otherwise use the same settings and templates as the original project.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : StringREQUIRED

    The external ID of the project you want to copy.

Responses

  • 200

    Returns a project and a list of templates within the project.

    RESPONSE BODY
    • Content-Type: application/json

      A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.

Get Project with external ID

Example Request

GET /v1/project/id/myProject HTTP/1.1
Authorization: Basic <Base64 key>
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",
  "externalId": "myProject",
  "id": "12345",
  "description": "Aztec Barcode",
  "createdAt": "2013-06-27T20:51:02.000Z",
  "contextId": "myvWKam4QN9Iu2K2fXK-Bd",
  "templates": [
  ],
  "settings": {
    "barcode_alt_text": "123456789",
    "barcode_default_value": "123456789",
    "barcode_encoding": "iso-8859-1",
    "barcode_label": "Member ID",
    "barcode_type_text": "Aztec",
    "barcode_type": "aztec"
  },
  "name": "Aztec Barcode",
  "projectType": "loyalty"
}

GET /project/id/{externalId}

Get the project with the specified id. The response includes information about the project (set when Creating a Project) and an array of templates associated with the project. The templates array contains all the information found in the templateHeader object. See Get Template for more information about the template header object and the fields it contains.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : StringREQUIRED

    The custom/external ID you want to use for your project.

Responses

  • 200

    A project and a list of templates within the project.

    RESPONSE BODY
    • Content-Type: application/json

      A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.

Update Project with external ID

Example Request

PUT /v1/project/id/myProject 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"
}

Example Response

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

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

PUT /project/id/{externalId}

Update a project with a given external ID.

 Note

Provide only the fields you want to update. While this payload takes any of the keys used when creating a project, any keys you do not provide are unchanged.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : StringREQUIRED

    The custom/external ID you want to use for your project.

Request Body

An update request can take the same payload as a Create Project request. However, you should provide only the keys you want to update; keys you do not provide will remain unchanged.

  • Content-Type: application/json

    Project Request

    A project request determines the type of passes you can create and the types of barcode your passes will use.

Responses

  • 200

    Returns project metadata and a list of templates for the project.

    RESPONSE BODY
    • Content-Type: application/json

      A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.

Create Project with external ID

Example Request

POST /v1/project/id/myProject 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"
  }
}

Example Response

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

{
  "updatedAt": "2013-07-01T19:57:36.190Z",
  "externalId": "myProject",
  "id": "12345",
  "contextId":"nEkzVdIcTP2eNqP1--xQ_A",
  "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 /project/id/{externalId}

Create a project with a custom identifier. Your project is based around the type of passes you want to create and the type of barcode you will include on your passes. It is a container for your templates and passes.

The response includes an id and contextId. Use these values to access your project via the API and dashboard, respectively.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : StringREQUIRED

    The custom/external ID you want to use for your project.

Request Body

Create a project. Your project is based around a pass type and your certificates.

  • Content-Type: application/json; charset=utf-8

    Project Request

    A project request determines the type of passes you can create and the types of barcode your passes will use.

Responses

  • 200

    Create a project. Your project is based around a pass type and your certificates.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.

List NFC Merchants

Example Request

GET /v1/project/id/<projectExternalId>/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{
  "merchants": [
    {
      "merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
      "projectId": 13137,
      "vendor": "APPLE",
      "merchantName": "XYZ Merchant",
      "merchantEmail": "xyz@example.com",
      "terminalProvider": "Verifone",
      "publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
      "keyVersion": 1,
      "keySource": "GENERATED",
      "updatedAt": "2020-09-16T19:16:28.000Z"
    },
  
    {
      "merchantId": "70407b66-ffbc-41bf-bf13-7814caf1d2bc",
      "projectId": 13137,
      "vendor": "GOOGLE",
      "merchantName": "UA",
      "merchantEmail": "wallet@airship.com",
      "terminalProvider": "Test Tool",
      "publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo\n4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==\n",
      "keyVersion": 1,
      "keySource": "IMPORTED",
      "smartTapIssuerId": "3388000000005375425",
      "smartTapCollectorId": "23405818",
      "updatedAt": "2020-09-09T00:19:45.000Z"
    }
  ]
}

GET /project/id/{projectExternalId}/nfcMerchants

Return all NFC merchant information for a project.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project you want to add NFC merchant information to, or look up NFC information for.

Responses

  • 200

    Returns all NFC merchants associated with your Airship wallet project.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • merchants : Array [Object]

        ARRAY ITEM
        • A response contains information generated by Airship and/or gathered from Google Wallet services.

          All of
          • Object

            Describes NFC support for your project (and related templates/passes).

            OBJECT PROPERTIES
            • keyVersion : Integer

              The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

            • merchantEmail : String

              The google merchant email address, used when configuring smartTap.

            • merchantName : String

              The google merchant name, used when configuring smartTap.

            • publicKeyPem : String

              The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

            • smartTapCollectorId : String

              Defines your Google Wallet merchant.

            • terminalProvider : String

              The NFC terminal provider that can read NFC messages, like Verifone.

            • vendor : StringREQUIRED

              Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

              Possible values: GOOGLE, APPLE, ANY

          • Object

            OBJECT PROPERTIES
            • keySource : String

              Set by Airship, either GENERATED if Airship generates your public/private keys or IMPORTED if you provide your own publicKey.

              Possible values: GENERATED, IMPORTED

            • merchantId : String

              The Airship-generated UUID for your NFC merchant information.

            • privateKeyPem : String

              Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the publicKeyPem).

            • projectId : Integer

              The ID of the project. Use this ID to reference your project in the API.

            • smartTapIssuerId : String

              Google only, represents your platform and may contain more than one collectorId.

            • updatedAt : String

              The date and time when your NFC merchant information was last updated. Format: date-time

Add an NFC Merchant

Example Request — APPLE and GOOGLE vendors

POST /v1/project/id/<projectExternalId>/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

{
  "vendor": "ANY",
  "merchantName": "testMerchant5",
  "merchantEmail": "test@example.com",
  "terminalProvider": "Verifone",
  "publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
  "keyVersion": 1,
  "keySource": "IMPORTED"
}

Example Response

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

{
  "merchantId": "a535fc29-9e90-434a-b8e9-4a5851292ccc",
  "projectId": 13137,
  "vendor": "APPLE",
  "merchantName": "testMerchant5",
  "merchantEmail": "test@example.com",
  "terminalProvider": "Verifone",
  "publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
  "keyVersion": 1,
  "keySource": "IMPORTED",
  "updatedAt": "2020-09-16T18:17:49.349Z"
}

POST /project/id/{projectExternalId}/nfcMerchants

Provide your merchant information and keys to support NFC interaction with passes and SmartTap for Android. When your project is NFC enabled, your audience can tap their device to a terminal to use their passes — consume point balances, use coupons, scan boarding passes, etc.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project you want to add NFC merchant information to, or look up NFC information for.

Request Body

  • Content-Type: application/json

    Object

    Describes NFC support for your project (and related templates/passes).

    OBJECT PROPERTIES
    • keyVersion : Integer

      The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

    • merchantEmail : String

      The google merchant email address, used when configuring smartTap.

    • merchantName : String

      The google merchant name, used when configuring smartTap.

    • publicKeyPem : String

      The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

    • smartTapCollectorId : String

      Defines your Google Wallet merchant.

    • terminalProvider : String

      The NFC terminal provider that can read NFC messages, like Verifone.

    • vendor : StringREQUIRED

      Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

      Possible values: GOOGLE, APPLE, ANY

Responses

  • 200

    Returns the newly-added NFC merchant information for your project.

    RESPONSE BODY
    • Content-Type: application/json

      A response contains information generated by Airship and/or gathered from Google Wallet services.

      All of
      • Object

        Describes NFC support for your project (and related templates/passes).

        OBJECT PROPERTIES
        • keyVersion : Integer

          The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

        • merchantEmail : String

          The google merchant email address, used when configuring smartTap.

        • merchantName : String

          The google merchant name, used when configuring smartTap.

        • publicKeyPem : String

          The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

        • smartTapCollectorId : String

          Defines your Google Wallet merchant.

        • terminalProvider : String

          The NFC terminal provider that can read NFC messages, like Verifone.

        • vendor : StringREQUIRED

          Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

          Possible values: GOOGLE, APPLE, ANY

      • Object

        OBJECT PROPERTIES
        • keySource : String

          Set by Airship, either GENERATED if Airship generates your public/private keys or IMPORTED if you provide your own publicKey.

          Possible values: GENERATED, IMPORTED

        • merchantId : String

          The Airship-generated UUID for your NFC merchant information.

        • privateKeyPem : String

          Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the publicKeyPem).

        • projectId : Integer

          The ID of the project. Use this ID to reference your project in the API.

        • smartTapIssuerId : String

          Google only, represents your platform and may contain more than one collectorId.

        • updatedAt : String

          The date and time when your NFC merchant information was last updated. Format: date-time

Get an NFC Merchant

Example Request

GET /v1/project/id/<projectExternalId>/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{
  "merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
  "projectId": 13137,
  "vendor": "GOOGLE",
  "merchantName": "testMerchant5",
  "merchantEmail": "test@example.com",
  "terminalProvider": "Verifone",
  "publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
  "keyVersion": 1,
  "keySource": "GENERATED",
  "updatedAt": "2020-09-16T18:20:45.000Z"
}

GET /project/id/{projectExternalId}/nfcMerchants/{merchantId}

Get an individual NFC merchant.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project you want to add NFC merchant information to or look up NFC information for.

  • merchantId : StringREQUIRED

    The merchant ID you want to modify.

Responses

  • 200

    Returns the merchant information associated with the merchantId.

    RESPONSE BODY
    • Content-Type: application/json

      A response contains information generated by Airship and/or gathered from Google Wallet services.

      All of
      • Object

        Describes NFC support for your project (and related templates/passes).

        OBJECT PROPERTIES
        • keyVersion : Integer

          The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

        • merchantEmail : String

          The google merchant email address, used when configuring smartTap.

        • merchantName : String

          The google merchant name, used when configuring smartTap.

        • publicKeyPem : String

          The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

        • smartTapCollectorId : String

          Defines your Google Wallet merchant.

        • terminalProvider : String

          The NFC terminal provider that can read NFC messages, like Verifone.

        • vendor : StringREQUIRED

          Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

          Possible values: GOOGLE, APPLE, ANY

      • Object

        OBJECT PROPERTIES
        • keySource : String

          Set by Airship, either GENERATED if Airship generates your public/private keys or IMPORTED if you provide your own publicKey.

          Possible values: GENERATED, IMPORTED

        • merchantId : String

          The Airship-generated UUID for your NFC merchant information.

        • privateKeyPem : String

          Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the publicKeyPem).

        • projectId : Integer

          The ID of the project. Use this ID to reference your project in the API.

        • smartTapIssuerId : String

          Google only, represents your platform and may contain more than one collectorId.

        • updatedAt : String

          The date and time when your NFC merchant information was last updated. Format: date-time

Update NFC Merchant Information

Example Request

PUT /v1/project/id/<projectExternalId>/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

{
  "merchantName": "Example Merchant",
  "merchantEmail": "my_merchant@example.com"
}

Example Response

{
  "merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
  "projectId": 13137,
  "vendor": "GOOGLE",
  "merchantName": "XYZ Merchant",
  "merchantEmail": "xyz@example.com",
  "terminalProvider": "Verifone",
  "publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
  "keyVersion": 1,
  "keySource": "GENERATED",
  "updatedAt": "2020-09-16T19:16:28.877Z"
}

PUT /project/id/{projectExternalId}/nfcMerchants/{merchantId}

Update your NFC merchant information.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project you want to add NFC merchant information to or look up NFC information for.

  • merchantId : StringREQUIRED

    The merchant ID you want to modify.

Request Body

You cannot update your public/private key. If you need to update keys, you should add a new NFC merchant configuration using new keys and delete the existing configuration.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • merchantEmail : String

      The google merchant email address, used when configuring smartTap.

    • merchantName : String

      The google merchant name, used when configuring smartTap.

Responses

  • 200

    Returns your updated merchant information.

    RESPONSE BODY
    • Content-Type: application/json

      A response contains information generated by Airship and/or gathered from Google Wallet services.

      All of
      • Object

        Describes NFC support for your project (and related templates/passes).

        OBJECT PROPERTIES
        • keyVersion : Integer

          The SSH protocol version for your key. Can be set to 1. Max: 4 Min: 1

        • merchantEmail : String

          The google merchant email address, used when configuring smartTap.

        • merchantName : String

          The google merchant name, used when configuring smartTap.

        • publicKeyPem : String

          The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.

        • smartTapCollectorId : String

          Defines your Google Wallet merchant.

        • terminalProvider : String

          The NFC terminal provider that can read NFC messages, like Verifone.

        • vendor : StringREQUIRED

          Set the vendor you want to provide information for, where ANY represents both Apple and Google vendors. If you omit this property, Airship assumes ANY.

          Possible values: GOOGLE, APPLE, ANY

      • Object

        OBJECT PROPERTIES
        • keySource : String

          Set by Airship, either GENERATED if Airship generates your public/private keys or IMPORTED if you provide your own publicKey.

          Possible values: GENERATED, IMPORTED

        • merchantId : String

          The Airship-generated UUID for your NFC merchant information.

        • privateKeyPem : String

          Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the publicKeyPem).

        • projectId : Integer

          The ID of the project. Use this ID to reference your project in the API.

        • smartTapIssuerId : String

          Google only, represents your platform and may contain more than one collectorId.

        • updatedAt : String

          The date and time when your NFC merchant information was last updated. Format: date-time

Delete an NFC Merchant

Example Request

DELETE /v1/project/id/<projectExternalId>/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Request

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

{
  "merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
  "updatedAt": "2020-09-16T18:20:45.000Z"
}

DELETE /project/id/{projectExternalId}/nfcMerchants/{merchantId}

Delete an NFC merchant. Deleting your NFC information prevents users from redeeming passes using NFC for the associated terminal, unless you have already added new/different NFC information to your project.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project you want to add NFC merchant information to or look up NFC information for.

  • merchantId : StringREQUIRED

    The merchant ID you want to modify.

Responses

  • 200

    The merchant information was deleted.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • merchantId : String

        The merchant ID that you deleted. Format: uuid

      • updatedAt : String

        The date and time when the merchant information was deleted. Format: date-time

Templates

A template determines the format, style, field placement, and default values for passes. You must specify a template when creating passes or adaptive links.

 Note

The Create Template and Update Template calls expect a different data structure than the response from a Get Template call.

Duplicate Template

Example Request

POST /v1/template/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

{
   "templateId": 12346
}

POST /template/duplicate/{templateId}

Duplicates the specified template and put it in the same project.

/v1/template/duplicate/id/(templateExternalId) duplicates the template specified by the external ID and puts the newly created template in the same project.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The templateId of the template you want to copy.

Responses

  • 200

    A successful request returns the ID of the newly created template.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      OBJECT PROPERTIES
      • templateId : Integer

        The identifier for the template. You can recall the template by ID in other operations.

List Templates

Example Request

GET /v1/template/headers HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
   "count": 2,
   "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",
         "expiryDuration": 730
      },
      {
         "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",
         "expiryDuration": 730
      }
   ],
   "pagination": {
      "order": "id",
      "page": 1,
      "start": 0,
      "direction": "DESC",
      "pageSize": 10
   }
}

GET /template/headers

List the headers for templates you created.

Security:

query PARAMETERS
  • pageSize : Number

    Number of templates per page. Defaults to 10.

  • page : Number

    The page you want to retrieve. Defaults to 1.

  • order : String

    The order you want the projects returned in. Defaults to id.

    Possible values: id, name, createdAt, updatedAt

  • direction : String

    The values ordered ascending or descending. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Responses

  • 200

    A successful response includes an array of template headers for templates you created. Look up an individual template to see field and header information for any individual template.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      OBJECT PROPERTIES
      • count : String

        The total number of results.

      • pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

      • templateHeaders : Array [Object]

        A list of template header objects.

        ARRAY ITEM
        • All of
          • Object

            OBJECT PROPERTIES
            • createdAt : String

              The date and time when the item was created. Format: date-time

            • id : Integer

              The identifier for the template. You can recall the template by ID in other operations.

            • updatedAt : String

              The date and time when the item was last updated. Format: date-time

          • General Template Headers : Object

            Meta information about templates; this object appears on all templates and identifies templates associated with a project.

            OBJECT PROPERTIES
            • deleted : Boolean

              If true, the template is deleted. You can no longer create passes from this template.

            • description : String

              A description for the template.

            • disabled : Boolean

              If true, the template is disabled; you cannot create new passes for this template until you update the template and enable it again.

            • expiryInfo : Any

              Determine when passes generated from the template should expire.

              One of
              • Expire on a date : Object

                Set the specific expiration date for passes generated from this template. Passes expire at 12:00 AM on the date you provide.

                OBJECT PROPERTIES
                • expiryDate : String

                  The date when passes expire. Format: date

                • expiryTimeZone : String

                  Passes expire at 12:00 AM in the time zone you set.

              • Expire after : Object

                Expire passes generated from this template after the specified number of minutes after creation.

                OBJECT PROPERTIES
                • expiryDuration : Integer

                  The number of days after creation that passes will expire.

              • Never expire : Object

                Passes generated from the template will never expire.

                OBJECT PROPERTIES
                • expireNever : String

                  Any string value (or null) will prevent passes generated from this template from expiring.

            • name : StringREQUIRED

              The name of the template.

            • projectId : Integer

              The ID of the project. Use this ID to reference your project in the API.

            • projectType : String

              The type of pass the template supports; matches the type setting for the parent project.

              Possible values: memberCard, coupon, boardingPass, eventTicket, generic, loyalty, giftCard

            • type : String

              The type of pass the template supports. This value corresponds to the projectType.

              Possible values: memberCard, coupon, boardingPass, eventTicket, generic, loyalty, giftCard

            • vendor : StringREQUIRED

              The device vendor the template is designed for, Apple or Google.

              Possible values: Apple, Google

            • vendorId : IntegerREQUIRED

              Corresponds to the vendor the template supports. 1 indicates an Apple template; 2 indicates a Google template.

              Possible values: 1, 2

Get Template

Example Request

GET /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response (Apple Template)

{
   "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": {
        "Coupon": {
          "formatType": "String",
          "changeMessage": "Enjoy %@ off your next order!",
          "order": 1,
          "fieldType": "primary",
          "textAlignment": "textAlignmentRight",
          "value": "20%",
          "label": "coupon",
          "required": false,
          "hideEmpty": true
        },
        "SiteAddress": {
          "formatType": "Number",
          "changeMessage": "New stuff, just for you at %@",
          "order": 2,
          "textAlignment": "textAlignmentCenter",
          "fieldType": "secondary",
          "value": "https://www.store.com/new?custnumb=123456",
          "label": "personalDeals",
          "required": false,
          "hideEmpty": true
        },
        "InStore": {
          "formatType": "String",
          "changeMessage": "Or visit your nearest store at %@",
          "order": 1,
          "fieldType": "secondary",
          "value": "1234 Fake St.",
          "label": "nearestStore",
          "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",
      "expiryDuration": 730
   }
}

GET /template/{Id}

Get the template specified by the templateId.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • Id : StringREQUIRED

    The templateId of the template you want to lookup.

Responses

  • 200

    A successful response returns returns the identifier of the template and dates when the template was created and last updated.

    RESPONSE BODY
    • Content-Type: application/json

      All of
      • Object

        OBJECT PROPERTIES
        • createdAt : String

          The date and time when the item was created. Format: date-time

        • id : Integer

          The identifier for the template. You can recall the template by ID in other operations.

        • updatedAt : String

          The date and time when the item was last updated. Format: date-time

      • One of
        • Apple Wallet Template Request

          A complete iOS template includes template meta information, headers, and fields.

        • Google Wallet Template Request

          A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.

Update Template

Example Request — Apple Template

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": {
      "Coupon": {
        "formatType": "String",
        "changeMessage": "Enjoy %@ off your next order!",
        "order": 1,
        "fieldType": "primary",
        "textAlignment": "textAlignmentRight",
        "value": "20%",
        "label": "coupon",
        "required": false,
        "hideEmpty": true
      },
      "SiteAddress": {
        "formatType": "Number",
        "changeMessage": "New stuff, just for you at %@",
        "order": 2,
        "textAlignment": "textAlignmentCenter",
        "fieldType": "secondary",
        "value": "https://www.store.com/new?custnumb=123456",
        "label": "personalDeals",
        "required": false,
        "hideEmpty": true
      },
      "InStore": {
        "formatType": "String",
        "changeMessage": "Or visit your nearest store at %@",
        "order": 1,
        "fieldType": "secondary",
        "value": "1234 Fake St.",
        "label": "nearestStore",
        "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"
}

Example Response

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

{
   "templateId": "12345"
}

PUT /template/{Id}

Update the specified template. This endpoint takes any of the parameters used for Creating a Template. You can also add or remove fields from the template with this call by adding or omitting those fields from the request.

 Note

Provide a complete template object when updating a template. This call replaces the existing template object in its entirety. You must include all keys and fields that should remain in the template, otherwise they are removed.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • Id : StringREQUIRED

    The templateId of the template you want to update.

Request Body

The shape of your template is determined by the device/wallet vendor you create passes for.

  • Content-Type: application/json

    One of
    • Apple Wallet Template Request

      A complete iOS template includes template meta information, headers, and fields.

    • Google Wallet Template Request

      A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.

Responses

  • 200

    A response returns the template’s unique identifier. Use this templateId to reference the template in subsequent operations.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      OBJECT PROPERTIES
      • templateId : Integer

        The identifier for the template. You can recall the template by ID in other operations.

Create Template

Example Apple Template

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": {
    "Coupon": {
      "formatType": "String",
      "changeMessage": "Enjoy %@ off your next order!",
      "order": 1,
      "fieldType": "primary",
      "textAlignment": "textAlignmentRight",
      "value": "20%",
      "label": "coupon",
      "required": false,
      "hideEmpty": true
    },
    "SiteAddress": {
      "formatType": "Number",
      "changeMessage": "New stuff, just for you at %@",
      "order": 2,
      "textAlignment": "textAlignmentCenter",
      "fieldType": "secondary",
      "value": "https://www.store.com/new?custnumb=123456",
      "label": "personalDeals",
      "required": false,
      "hideEmpty": true
    },
    "InStore": {
      "formatType": "String",
      "changeMessage": "Or visit your nearest store at %@",
      "order": 1,
      "fieldType": "secondary",
      "value": "1234 Fake St.",
      "label": "nearestStore",
      "required": false,
      "hideEmpty": false
    }
  },

  "vendor": "Apple",
  "projectType": "memberCard",
  "projectId": 1234,
  "type": "Store Card",
  "vendorId": 1,
  "deleted": "False",
  "description": "Description",
  "name": "Loyalty Card",
  "disabled": "False",
  "expiryInfo": {
    "expiryDuration": 365
  }
}

Example Google Template

POST /v1/template/12345 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",
  "expiryDuration": 365
}

Example Response

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

{
   "templateId": 12345
}

POST /template/{Id}

Create a template within the specified project. A template is specific to a vendor platform, Apple or Google.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • Id : StringREQUIRED

    The projectId of the project that will contain the new template.

Request Body

The request body is shaped by platform vendor your template and subsequent passes are intended for.

  • Content-Type: application/json

    One of
    • Apple Wallet Template Request

      A complete iOS template includes template meta information, headers, and fields.

    • Google Wallet Template Request

      A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.

Responses

  • 200

    A response returns the template’s unique identifier. Use this templateId to reference the template in subsequent operations.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      OBJECT PROPERTIES
      • templateId : Integer

        The identifier for the template. You can recall the template by ID in other operations.

Delete Template

Example Request

DELETE /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

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

DELETE /template/{Id}

Delete the specified template.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • Id : StringREQUIRED

    The templateId of the template you want to delete.

Responses

  • 200

    Returns the status of the deleted template.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • TemplateId : Integer

        The identifier of the deleted template.

      • status : String

        Indicates that the request succeeded.

        Possible values: success

Get Template passes

Example Request

GET /v1/template/12345/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

{
          "passes": [{
              "id": 3,
              "templateId": 12345,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/3/download",
              "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da051",
              "createdAt": "2023-04-19T06:17:01.000Z",
              "updatedAt": "2023-04-19T06:17:01.000Z",
              "status": "uninstalled",
              "installedAt": "2023-04-19T06:17:02.000Z",
              "platform": "android"
            },
            {
              "id": 1,
              "templateId": 12345,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/1/download",
              "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e253",
              "createdAt": "2023-04-05T17:55:23.000Z",
              "updatedAt": "2023-04-05T17:55:23.000Z",
              "status": "installed",
              "installedAt": "2023-04-05T17:55:23.000Z",
              "platform": "android"
            }
          ],
          "pagination": {
            "order": "id",
            "direction": "desc",
            "page": 1,
            "start": 0,
            "pageSize": 2
          }
}

GET /template/{templateId}/passes

List passes for a template.

Security:

query PARAMETERS
  • status : String

    Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • pageSize : Integer

    The number of passes per page. Defaults to 10.

  • page : Integer

    The page of results you want to retrieve, starting at 1.

  • order : String

    The order you want passes returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

  • direction : String

    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : IntegerREQUIRED

    The templateId of the template you want to get passes for.

Responses

  • 200

    A successful request returns a paged list of passes for a particular template.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

      • passes : Array [Object]

        The metadata for passes associated with the template. Each object in the array represents a pass.

        ARRAY ITEM
        • Pass Metadata

          Meta information about passes.

          OBJECT PROPERTIES
          • createdAt : String

            The date and time when the item was last updated. Format: date-time

          • id : Integer

            The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

          • installedAt : String

            The date and time when pass was first installed on the device. Format: date-time

          • platform : String

            Wallet platform (iOS or Android).

            Possible values: iOS, Android

          • serialNumber : String

            The serial number of the pass.

          • status : String

            Recent on-device pass status.

            Possible values: installed, uninstalled, not_been_installed

          • templateId : Integer

            The identifier for the template. You can recall the template by ID in other operations.

          • uninstalledAt : String

            The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

          • updatedAt : String

            The date and time when the item was created. Format: date-time

          • url : String

            Pass download URL.

  • 404

    Template not found.

Publish a Bulk Update to 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
      }
   }
}

Example Response

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

{
   "ticketId": 56789
}

PUT /template/{templateId}/passes

Updates all passes based on a particular template. The only information you can modify on passes for the specified template ID are images, barcode data, and the following fields:

  • Membership ID fields
  • Coupon codes
  • Barcode values or alternative text
  • Any other field or image on the pass

 Important

Updating the order value for linkModulesData can only be done in an Event or Boarding Pass template.

Security:

query PARAMETERS
  • status : String

    Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • pageSize : Integer

    The number of passes per page. Defaults to 10.

  • page : Integer

    The page of results you want to retrieve, starting at 1.

  • order : String

    The order you want passes returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

  • direction : String

    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : IntegerREQUIRED

    The templateId of the template you want to get passes for.

Request Body

Specify the fields you want to update. Any field you do not specify in this payload remains unchanged.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • fields : Object

      OBJECT PROPERTIES
      • Field Name (String) : Object

        OBJECT PROPERTIES
        • value : String

          The value key that you want to change for the field.

Responses

  • 200

    Returns a ticket ID as a reference for the update operation.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ticketId : Integer

        A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.

  • 404

    Template with ID templateId was not found.

Delete Location from Template

Example Request

DELETE /v1/template/12345/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

DELETE /template/{template_id}/location/{location_id}

Remove a location from template.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • template_id : StringREQUIRED

    The template you want to remove a location from.

  • location_id : StringREQUIRED

    The ID of the location you want to remove.

Responses

  • 200

    The location is deleted.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

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

Example Response

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

[
   {
      "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 /template/{template_id}/locations

Add locations to the specified template.

 Important

As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services. This affects a majority of Google passes. Google has not committed to a timetable to resolve the issue and make location triggers available to all Google passes again.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • template_id : StringREQUIRED

    The template you want to add locations to.

Request Body

A request includes an array of locations.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES

Responses

  • 200

    A successful request returns the locations on the pass.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      ARRAY ITEM
      • OBJECT PROPERTIES
        • LocationId : Integer

          The identifier for a location.

        • fieldId : Integer

        • value : Location Object

          Represents a location on a pass or an adaptive link.

          Place objects in the locations array to add location information to passes and templates. Updating locations on a pass or template will replace all locations on that pass; if you want to add to the locations on a pass, you must provide all locations already included on the pass and any additional locations you want to add.

          Apple Wallet supports up to 10 locations per pass. If you exceed this limit for an iOS pass, we will use the 10 locations nearest to a user (located by IP address) when they install the pass.

          As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services. This affects a majority of Google passes. Google has not committed to a timetable to resolve the issue and make location triggers available to all Google passes again.

Templates with external IDs

Endpoints for templates using external IDs. A template determines the format, style, field placement, and default values for passes. You must specify a template when creating passes or adaptive links.

 Note

The Create Template and Update Template calls expect a different data structure than the response from a Get Template call.

Delete Location from Template with external ID

Example Request

DELETE /v1/template/id/myTemplate/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

DELETE /template/id/{externalId}/location/{locationId}

Remove location from template with an external ID.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : StringREQUIRED

    The external ID of the template you want to remove a location from.

  • locationId : StringREQUIRED

    The ID of the location you want to remove.

Responses

  • 200

    The location is deleted.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

Add Locations to Template with external ID

Example Request

POST /v1/template/id/myTemplate/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"
      }
   ]
}

Example Response

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

[
   {
      "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 /template/id/{externalId}/locations

Add locations to a template with an external ID.

 Important

As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services. This affects a majority of Google passes. Google has not committed to a timetable to resolve the issue and make location triggers available to all Google passes again.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : StringREQUIRED

    The external ID of the template you want to add locations to.

Request Body

A request includes an array of locations.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES

Responses

  • 200

    A successful request returns the locations on the pass.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      ARRAY ITEM
      • OBJECT PROPERTIES
        • LocationId : Integer

          The identifier for a location.

        • fieldId : Integer

        • value : Location Object

          Represents a location on a pass or an adaptive link.

          Place objects in the locations array to add location information to passes and templates. Updating locations on a pass or template will replace all locations on that pass; if you want to add to the locations on a pass, you must provide all locations already included on the pass and any additional locations you want to add.

          Apple Wallet supports up to 10 locations per pass. If you exceed this limit for an iOS pass, we will use the 10 locations nearest to a user (located by IP address) when they install the pass.

          As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services. This affects a majority of Google passes. Google has not committed to a timetable to resolve the issue and make location triggers available to all Google passes again.

Get Template with external ID

Example Request

GET /v1/template/id/myTemplate HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response (Apple Template)

{
   "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": {
        "Coupon": {
          "formatType": "String",
          "changeMessage": "Enjoy %@ off your next order!",
          "order": 1,
          "fieldType": "primary",
          "textAlignment": "textAlignmentRight",
          "value": "20%",
          "label": "coupon",
          "required": false,
          "hideEmpty": true
        },
        "SiteAddress": {
          "formatType": "Number",
          "changeMessage": "New stuff, just for you at %@",
          "order": 2,
          "textAlignment": "textAlignmentCenter",
          "fieldType": "secondary",
          "value": "https://www.store.com/new?custnumb=123456",
          "label": "personalDeals",
          "required": false,
          "hideEmpty": true
        },
        "InStore": {
          "formatType": "String",
          "changeMessage": "Or visit your nearest store at %@",
          "order": 1,
          "fieldType": "secondary",
          "value": "1234 Fake St.",
          "label": "nearestStore",
          "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",
      "expiryDuration": 730
   }
}

GET /template/id/{templateExternalId}

Get the template specified by the external ID.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateExternalId : StringREQUIRED

    The external ID of the template you want to get, modify, or delete.

Responses

  • 200

    A successful response returns a template. The template object is shaped by the platform the template is designed for.

    RESPONSE BODY
    • Content-Type: application/json

      All of
      • Object

        OBJECT PROPERTIES
        • createdAt : String

          The date and time when the item was created. Format: date-time

        • id : Integer

          The identifier for the template. You can recall the template by ID in other operations.

        • updatedAt : String

          The date and time when the item was last updated. Format: date-time

      • One of
        • Apple Wallet Template Request

          A complete iOS template includes template meta information, headers, and fields.

        • Google Wallet Template Request

          A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.

Update Template with external ID

Example Google Template

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

Example Response

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

{
   "templateId": 12345
}

PUT /template/id/{templateExternalId}

Update the specified template. This endpoint takes any of the parameters used for Creating a Template. You can also add or remove fields from the template with this call by adding or omitting those fields from the request.

 Note

Provide a complete template object when updating a template. This call replaces the existing template object in its entirety. You must include all keys and fields that should remain in the template, otherwise they are removed.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateExternalId : StringREQUIRED

    The external ID of the template you want to get, modify, or delete.

Request Body

The shape of your template is determined by the device/wallet vendor you create passes for.

  • Content-Type: application/json

    One of
    • Apple Wallet Template Request

      A complete iOS template includes template meta information, headers, and fields.

    • Google Wallet Template Request

      A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.

Responses

  • 200

    A response returns the template’s unique identifier. Use this id to reference the template in subsequent operations.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      OBJECT PROPERTIES
      • templateId : Integer

        The identifier for the template. You can recall the template by ID in other operations.

Delete Template with external ID

Example Request

DELETE /v1/template/id/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

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

DELETE /template/id/{templateExternalId}

Delete the specified template.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateExternalId : StringREQUIRED

    The external ID of the template you want to get, modify, or delete.

Responses

  • 200

    Returns the status of the deleted template.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • TemplateId : Integer

        The identifier of the deleted template.

      • status : String

        Indicates that the request succeeded.

        Possible values: success

Create Template with external ID

Example Apple Template

POST /v1/template/(projectId)/id/myTemplate 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": {
    "Coupon": {
      "formatType": "String",
      "changeMessage": "Enjoy %@ off your next order!",
      "order": 1,
      "fieldType": "primary",
      "textAlignment": "textAlignmentRight",
      "value": "20%",
      "label": "coupon",
      "required": false,
      "hideEmpty": true
    },
    "SiteAddress": {
      "formatType": "Number",
      "changeMessage": "New stuff, just for you at %@",
      "order": 2,
      "textAlignment": "textAlignmentCenter",
      "fieldType": "secondary",
      "value": "https://www.store.com/new?custnumb=123456",
      "label": "personalDeals",
      "required": false,
      "hideEmpty": true
    },
    "InStore": {
      "formatType": "String",
      "changeMessage": "Or visit your nearest store at %@",
      "order": 1,
      "fieldType": "secondary",
      "value": "1234 Fake St.",
      "label": "nearestStore",
      "required": false,
      "hideEmpty": false
    }
  },

  "vendor": "Apple",
  "projectType": "memberCard",
  "projectId": 1234,
  "type": "Store Card",
  "vendorId": 1,
  "deleted": "False",
  "description": "Description",
  "name": "Loyalty Card",
  "disabled": "False",
  "expiryInfo": {
    "expiryDuration": 365
  }
}

Example Google Template

POST /v1/template/project/id/(projectExternalId)/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",
  "expiryInfo": {
   "expiryDuration": 365
  }
}

Example Response

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

{
   "templateId": 12345
}

POST /template/{projectId}/id/{templateExternalId}

Create a template with an external ID within the specified project. A template is specific to a vendor platform, Apple or Google.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project you want to associate your new template with.

  • templateExternalId : StringREQUIRED

    The custom identifier you want to give to your new template.

Request Body

The request body is shaped by platform vendor your template and subsequent passes are intended for.

  • Content-Type: application/json

    One of
    • Apple Wallet Template Request

      A complete iOS template includes template meta information, headers, and fields.

    • Google Wallet Template Request

      A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.

Responses

  • 200

    A response returns the template’s unique identifier. Use this templateId or the external ID to reference the template in subsequent operations.

    RESPONSE BODY
    • Content-Type: application/json; charset=utf-8

      OBJECT PROPERTIES
      • templateId : Integer

        The identifier for the template. You can recall the template by ID in other operations.

Apple Wallet Pass Personalization

Adding personalization to an Apple Wallet loyalty template creates a pass that prompts the user for relevant personal information when signing up for a rewards program. These endpoints help you manage the personalizable information that you require users to provide when signing up for your loyalty/rewards program.

Get personalization requirements

Example Request

GET /v1/template/{template_id}/personalization HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

{
  "requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
  ],
  "description": "Enter your information to sign up and earn points.",
  "termsAndConditions": "Terms and conditions go here"
}

GET /template/{template_id}/personalization

Returns personalization requirements for a template.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • template_id : StringREQUIRED

    The loyalty card template you want to add, modify, or retrieve personalization information for.

Responses

  • 200

    Your template has the following personalization requirements.

    RESPONSE BODY
    • Content-Type: application/json

Update personalization requirements

Example Request

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

{
  "requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
  ],
  "description": "Enter your information to sign up and earn points.",
  "termsAndConditions": "Terms and conditions go here"
}

Example Response

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

{
  "requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
  ],
  "description": "Enter your information to sign up and earn points.",
  "termsAndConditions": "Terms and conditions go here"
}

PUT /template/{template_id}/personalization

When updating personalization requirements for a template, you must provide a complete payload. This request overwrites all previous personalization requirements attached to the template; any information you leave out of this request will be removed from the personalization requirements for the template.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • template_id : StringREQUIRED

    The loyalty card template you want to add, modify, or retrieve personalization information for.

Request Body

Responses

  • 200

    Your personalization requirements have been updated for the template.

    RESPONSE BODY
    • Content-Type: application/json

Add personalization requirements

Example Request

POST /v1/template/{template_id}/personalization HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
  "requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
  ],
  "description": "Enter your information to sign up and earn points.",
  "termsAndConditions": "Terms and conditions go here"
}

Example Response

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

{
  "requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
  ],
  "description": "Enter your information to sign up and earn points.",
  "termsAndConditions": "Terms and conditions go here"
}

POST /template/{template_id}/personalization

Adds personalization requirements to a template. When a user attempts to install a pass with personalization requirements, they are first prompted for the requiredPersonalizationFields specified in this payload. When the user fills out the information and accepts the terms and conditions (if present), they receive a personalized pass.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • template_id : StringREQUIRED

    The loyalty card template you want to add, modify, or retrieve personalization information for.

Request Body

Responses

  • 200

    Your personalization requirements have been added to the template.

    RESPONSE BODY
    • Content-Type: application/json

Remove personalization requirements

Example Request

DELETE /v1/template/{template_id}/personalization HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

{
  "requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
  ],
  "description": "Enter your information to sign up and earn points.",
  "termsAndConditions": "Terms and conditions go here"
}

DELETE /template/{template_id}/personalization

Removes personalization requirements from a template.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • template_id : StringREQUIRED

    The loyalty card template you want to add, modify, or retrieve personalization information for.

Responses

  • 200

    Your personalization requirements removed from the template.

    RESPONSE BODY
    • Content-Type: application/json

Adaptive Links

A link that detects the platform of a recipient and installs the correct pass. You can send adaptive links to both Apple and Google platform users; When a user on either platform taps the link, Airship detects the user’s device platform and returns the correct pass.

To send an adaptive link to both Google and Apple platforms, you must have configured templates for both platforms. You can send an adaptive link to an individual platform, and define the behavior for the unsupported platform.

Example Request

GET /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

Example Response

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

{
   "links": [
      {
         "adaptiveLinkId": "0bDEgyJEko",
         "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/<adaptiveLinkId>",
         "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/<adaptiveLinkId>/ios",
         "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/<adaptiveLinkId>/android",
         "isPersonalized": true,
         "isExpired": false,
         "availablePasses": 999999,
         "ttlInDays": 30,
         "iosTemplateId": 4834,
         "androidTemplateId": 4840
      },
      {
         "adaptiveLinkId": "58HTBeYkqg",
         "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/<adaptiveLinkId>",
         "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/<adaptiveLinkId>/ios",
         "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/<adaptiveLinkId>/android",
         "landingPageUrl": "https://www.urbanairship.com/",
         "isPersonalized": false,
         "isExpired": true,
         "expirationDate": "2020-10-01",
         "availablePasses": 1000000,
         "ttlInDays": 30,
         "iosTemplateId": 4393,
         "androidTemplateId": 4387
      },
      {
         "adaptiveLinkId": "7Qxf5ar9P6",
         "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/<adaptiveLinkId>",
         "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/<adaptiveLinkId>/ios",
         "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/<adaptiveLinkId>/android",
         "isPersonalized": false,
         "isExpired": false,
         "availablePasses": 1000000,
         "ttlInDays": 30,
         "iosTemplateId": 4682,
         "androidTemplateId": 4680
      }
   ]
}

GET /links/adaptive

Returns a list of adaptive links.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

  • Returns a list of all adaptive links for the account.

    RESPONSE BODY

Create Adaptive Links

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": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
   "landingPageUrl": "https://acustomer.com/landing.html",
   "availablePasses": 100000,
   "payload": {}
}

Example Request with Expiration Date

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": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
   "landingPageUrl": "https://acustomer.com/landing.html",
   "expirationDate": "2022-10-01",
   "availablePasses": 100000,
   "ttlInDays": 730,
   "payload": {}
}

Example Request with Payload

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 with Locations

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": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "availablePasses": 100000,
  "ttlInDays": 30,
  "parameterEncoding": "base64",
  "locationRadius": 10,
  "maxResultLocations": 5,
  "payload": {},
  "locations": [
      {
         "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 200 OK
Content-Type: application/json

{
  "adaptiveLinkId": "abchd345",
  "url": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": "true",
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 30
}

POST /links/adaptive

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.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Request Body

  • Content-Type: application/json

    Adaptive Link Request

    An adaptive link request contains identifiers for the templates you used to generate passes from the link, and any fields you want to set when users create passes from the link.

Responses

  • 200

    A successful request results in an adaptive link.

    RESPONSE BODY
    • Content-Type: application/json

      An adaptive link response includes URLs that users can access to detect and install a pass.

  • 404

    Could not find template(s), or could not find or create Dynamic Link object(s).

Create Boarding Pass or Event Ticket Adaptive Links

Example Boarding Pass Request

POST /v1/links/adaptive/multiple/project/<projeclId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "iosTemplateExternalId": "<iosTemplateExternalId>",
  "androidTemplateExternalId": "<androidTemplateExternalId>",
  "payload": {
    "flights": [
      {
        "flightExternalId": "<flightExternalId1>",
        "fields": {
          "flightNumber": { "value": "815" },
          "airlineCode": { "value": "WN" },
          "airlineName": { "value": "Southwest Airlines" },
          "departureAirport": {
            "label": "San Francisco",
            "value": "SFO"
          },
          "departureGate": {
            "label": "Gate #",
            "value": "25"
          },
          "boardingTime": { "value": "2018-07-30T08:35:00" },
          "departureTime": { "value": "2018-07-30T09:00:00" },
          "arrivalAirport": {
            "label": "Portland",
            "value": "PDX"
          },
          "arrivalTime": { "value": "2018-07-30T11:00:00" },
          "flightStatus": { "value": "scheduled" }
        },
        "passengers": [
          {
            "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
            "fields": {
              "seatNumber": { "value": "13A" },
              "confirmationCode": { "value": "E4583B" },
              "passengerName": { "value": "SMITH/JOE" },
              "specialAssistance": { "label": "Special Assistance", "value": "Wheelchair" },
              "barcode_value": { "value": "12345" },
              "barcodeAltText": { "value": "12345" }
            }
          },
          {
            "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
            "fields": {
              "seatNumber": { "value": "13B" },
              "confirmationCode": { "value": "E4583B" },
              "passengerName": { "value": "SMITH/SALLY" },
              "barcode_value": { "value": "12346" },
              "barcodeAltText": { "value": "12346" }
            }
          },
          {
            "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
            "fields": {
              "seatNumber": { "value": "13C" },
              "confirmationCode": { "value": "E4583B" },
              "passengerName": { "value": "SMITH/SAM" },
              "barcode_value": { "value": "12347" },
              "barcodeAltText": { "value": "12347" }
            }
          }
        ],
        "passGroups": ["sfo-pdx-20180730"]
      }
    ]
  }
}

Example Response

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

{
  "links": [
    {
      "status": 200,
      "adaptiveLinkId": "<uaAdaptiveLinkId1>",
      "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
      "iosTemplateId": "<iosTemplateId>",
      "iosTemplateExternalId": "<iosTemplateExternalId>",
      "androidTemplateId": "<androidTemplateId>",
      "androidTemplateExternalId": "<androidTemplateExternalId>",
      "url": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber1>",
      "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumbe1r>/ios",
      "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber1>/android",
      "createdAt": "2018-07-05T09:12:32Z",
      "updatedAt": "2018-07-05T09:12:32Z",
      "isPersonalized": "false",
      "isExpired": false,
      "availablePasses": 1000000,
      "ttlInDays": 30,
      "flightId": 465,
      "flightExternalId": "<flightExternalId1>",
      "iosPassLinkId": "eb94e8e0-4353-4e0b-bfe9-cfd21c52a540",
      "androidPassLinkId": "41c1ea48-f469-4968-b610-a98629ea19bc"
    },
    {
      "status": 200,
      "adaptiveLinkId": "<uaAdaptiveLinkId2>",
      "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
      "iosTemplateId": "<iosTemplateId>",
      "iosTemplateExternalId": "<iosTemplateExternalId>",
      "androidTemplateId": "<androidTemplateId>",
      "androidTemplateExternalId": "<androidTemplateExternalId>",
      "url": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber2>",
      "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber2>/ios",
      "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber2>/android",
      "createdAt": "2018-07-05T09:12:32Z",
      "updatedAt": "2018-07-05T09:12:32Z",
      "isPersonalized": "false",
      "isExpired": false,
      "availablePasses": 1000000,
      "ttlInDays": 30,
      "flightId": 465,
      "flightExternalId": "<flightExternalId1>",
      "iosPassLinkId": "5d370e0d-0aa9-45c3-b7ab-eff0a3d4995b",
      "androidPassLinkId": "c60bd6c0-8f1e-4419-abb0-9f6fcb8a6fab"
    },
    {
      "status": 200,
      "adaptiveLinkId": "<uaAdaptiveLinkId2>",
      "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
      "iosTemplateId": "<iosTemplateId>",
      "iosTemplateExternalId": "<iosTemplateExternalId>",
      "androidTemplateId": "<androidTemplateId>",
      "androidTemplateExternalId": "<androidTemplateExternalId>",
      "url": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber2>",
      "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber2>/ios",
      "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber2>/android",
      "createdAt": "2018-07-05T09:12:32Z",
      "updatedAt": "2018-07-05T09:12:32Z",
      "isPersonalized": "false",
      "isExpired": false,
      "availablePasses": 1000000,
      "ttlInDays": 30,
      "flightId": 465,
      "flightExternalId": "<flightExternalId1>",
      "iosPassLinkId": "5d370e0d-0aa9-45c3-b7ab-eff0a3d4995b",
      "androidPassLinkId": "c60bd6c0-8f1e-4419-abb0-9f6fcb8a6fab"
    },
  ]
}

POST /links/adaptive/multiple/project/{projectId}

Create boarding pass or event ticket adaptive links. Creating boarding passes or event tickets is similar to other adaptive links, with a few additional items in the request and response payloads.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project you want to create the boarding pass in.

Request Body

An adaptive link request where the fields object can include an array of flights or events, each with an array of passengers or attendees, respectively.

  • Content-Type: application/json

    One of
    • Event Ticket Adaptive Link Request

      An event ticket requires similar information to other adaptive link types, but does not support some of the same fields, and requires event and attendee information.

      Like other adaptive links, you must provide the id or externalId of an iOS or Android template. You can create the event within this request or specify an event by eventId or eventExternalId. In either case, you must also provide an array of attendees for the event.

    • Boarding Pass Adaptive Link Request

      A boarding pass adaptive link requires similar information to other adaptive link types, but the payload includes flight information and an array of passengers for each flight.

      Like other adaptive links, you must provide the id or externalId of an iOS or Android template.

Responses

  • 200

    A successful request returns an array of adaptive links. Each object in the array represents an individual passenger or attendee in the request payload. Passes in the response appear in same order as objects in in the flights or events array.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • links : Array [Any]

        An array of adaptive links.

        ARRAY ITEM
        • One of
          • Boarding Pass Adaptive Link Response

            The boarding pass operations return responses like other adaptive links, with the addition of the identifier of the event and an HTTP status for each individual adaptive link.

            Like other adaptive links, you must provide the id or externalId of an iOS or Android template.

            All of
            • Adaptive Link Response

              An adaptive link response includes URLs that users can access to detect and install a pass.

            • Object

              OBJECT PROPERTIES
              • flightExternalId : String

                An external, custom identifier for a flight. You can reference flights by flightExternalId rather than the Airship-generated flightId.

                When creating boarding passes, if you specify an existing flight by flightExternalId, you do not need to provide flight information in the fields object. If creating a new flight in the fields object, you can assign a new flightExternalId to the new flight.

              • flightId : Integer

                A unique, auto-generated identifier for a flight.

                When creating boarding passes, if you specify a flight by ID, you do not need to define the flight in the fields object.

              • status : Integer

                The HTTP status code for the adaptive link operation.

          • Event Ticket Adaptive Link Response

            The response for event ticket operations is much like any other adaptive link, with the addition of the identifier of the event and an HTTP status for each individual adaptive link.

            All of
            • Adaptive Link Response

              An adaptive link response includes URLs that users can access to detect and install a pass.

            • Object

              OBJECT PROPERTIES
              • eventExternalId : String

                An external identifier for an event. You can only assign an external identifier when creating an event. If you do assign an external identifier, requests for events or passes referencing the event will return the external ID in addition to the eventId created within Airship.

              • eventId : Integer

                The Airship-created identifier for an event.

              • status : Integer

                The HTTP status code for the adaptive link operation.

Example Request

GET /v1/links/adaptive/projects/7331?pageSize=2 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

Example Response

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

{
  "links": [
    {
      "adaptiveLinkId": "7XRMaSpcEQk",
      "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/adaptive/7XRMaSpcEQk",
      "isPersonalized": false,
      "availablePasses": 998,
      "iosTemplateId": 106178,
      "projectId": 7331,
      "createdAt": "2023-05-23T20:21:10.446Z",
      "updatedAt": "2023-05-23T20:21:10.446Z",
      "status": 200,
      "isExpired": false,
      "doesAllowUrlParameters": true,
      "expiry": "2023-11-19",
      "isAvailablePassesUnlimited": false
    },
    {
      "adaptiveLinkId": "Y0E6EXuTx5i",
      "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/adaptive/Y0E6EXuTx5i",
      "isPersonalized": false,
      "availablePasses": 998,
      "iosTemplateId": 106178,
      "projectId": 7331,
      "createdAt": "2023-05-23T20:20:39.808Z",
      "updatedAt": "2023-05-23T20:20:39.808Z",
      "status": 200,
      "isExpired": false,
      "doesAllowUrlParameters": true,
      "expiry": "2023-11-19",
      "isAvailablePassesUnlimited": false
    }
  ],
  "nextPageToken": "XGMuDpx2RDs.1684443368127"
}

GET /links/adaptive/projects/{projectId}

Returns a list of adaptive links for a project.

query PARAMETERS
  • The maximum items to return per page. Defaults to 10.

  • The token for the next page of results.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The ID of the project.

  • Returns a list of all adaptive links for a project.

    RESPONSE BODY

Example Request

GET /v1/links/adaptive/projects/7331/templates/106178 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

Example Response

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

{
  "links": [
    {
      "adaptiveLinkId": "7XRMaSpcEQk",
      "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/adaptive/7XRMaSpcEQk",
      "isPersonalized": false,
      "availablePasses": 998,
      "iosTemplateId": 106178,
      "projectId": 7331,
      "createdAt": "2023-05-23T20:21:10.446Z",
      "updatedAt": "2023-05-23T20:21:10.446Z",
      "status": 200,
      "isExpired": false,
      "doesAllowUrlParameters": true,
      "expiry": "2023-11-19",
      "isAvailablePassesUnlimited": false
    }
  ],
  "nextPageToken": "Y0E6EXuTx5i.1684873239808"
}

GET /links/adaptive/projects/{projectId}/templates/{templateId}

Returns a list of adaptive links for a template.

query PARAMETERS
  • The maximum items to return per page. Defaults to 10.

  • The token for the next page of results.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The ID of the project.

  • The ID of the template.

  • Returns a list of all adaptive links for a template.

    RESPONSE BODY

Example Request

GET /v1/links/adaptive/<adaptiveLinkId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

Example Response

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

{
  "adaptiveLinkId": "abchd345",
  "url": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 30
}

GET /links/adaptive/{adaptiveLinkId}

Returns information about a single adaptive link.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The adaptive link you want to return or update.

  • Lists urls and available passes for an individual link.

    RESPONSE BODY
    • Content-Type: application/json

      An adaptive link response includes URLs that users can access to detect and install a pass.

  • Could not find an entry with specified adaptiveLinkId.

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://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>",
   "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>/ios",
   "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>/android",
   "landingPageUrl": "https://acustomer.com/landing.html",
   "isPersonalized": "true",
   "isExpired": false,
   "availablePasses": 100000,
   "ttlInDays": 30
}

PUT /links/adaptive/{adaptiveLinkId}

Updates an individual adaptive link. You can provide any part of an adaptive link body. Adaptive link fields that you do not provide in this request remain unchanged.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The adaptive link you want to return or update.

A request specifies templates and other information about, and limits for, passes created from the adaptive link. If you provide a single template, then the adaptive link functions for either iOS or Android devices and sends users of the other device type to a landing page.

  • Content-Type: application/json

    Adaptive Link Request

    An adaptive link request contains identifiers for the templates you used to generate passes from the link, and any fields you want to set when users create passes from the link.

  • A successful request results in an adaptive link.

    RESPONSE BODY
    • Content-Type: application/json

      An adaptive link response includes URLs that users can access to detect and install a pass.

  • Could not find templates or Dynamic Link object(s).

Example Request

DELETE /v1/links/adaptive/rthBWAWDaAA HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

Example Response

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

{}

DELETE /links/adaptive/{adaptiveLinkId}

Deletes an adaptive link.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The adaptive link you want to return or update.

  • The adaptive link was successfully deleted. A successful operation returns no content.

  • Could not find an entry with specified adaptiveLinkId.

Example Request

GET /v1/links/adaptive/<adaptiveLinkId>/passes HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

Example Response

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

{
    "passes": [{
        "id": 616,
        "templateId": 1000057,
        "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/616/download",
        "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da0b8",
        "createdAt": "2023-04-19T06:17:01.000Z",
        "updatedAt": "2023-04-19T06:17:01.000Z",
        "status": "installed",
        "installedAt": "2023-04-19T06:17:02.000Z",
        "platform": "android"
      },
      {
        "id": 610,
        "templateId": 1000083,
        "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/610/download",
        "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e216",
        "createdAt": "2023-04-05T17:55:23.000Z",
        "updatedAt": "2023-04-05T17:55:23.000Z",
        "status": "installed",
        "installedAt": "2023-04-05T17:55:23.000Z",
        "platform": "android"
      }
    ],
    "pagination": {
      "order": "id",
      "direction": "desc",
      "page": 1,
      "start": 0,
      "pageSize": 2
    }
}

GET /links/adaptive/{adaptiveLinkId}/passes

List passes for an adaptive link.

query PARAMETERS
  • Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • The number of passes per page. Defaults to 10.

  • The page of results you want to retrieve, starting at 1.

  • The order you want passes returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

  • Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The adaptive link ID used for pass creation.

  • A successful request returns a paged list of passes for a particular adaptive link.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • The total number of passes associated with an adaptive link.

      • Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • The key in the result set that you want to order results by. Defaults to id.

        • The page you are on. Multiply by the page size to determine the result set on the page.

        • The number of results per page.

        • The first result on the page; results begin with 0.

      • The metadata for passes associated with the adaptive link. Each object in the array represents a pass.

        ARRAY ITEM
        • Pass Metadata

          Meta information about passes.

          OBJECT PROPERTIES
          • The date and time when the item was last updated. Format: date-time

          • The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

          • The date and time when pass was first installed on the device. Format: date-time

          • Wallet platform (iOS or Android).

            Possible values: iOS, Android

          • The serial number of the pass.

          • Recent on-device pass status.

            Possible values: installed, uninstalled, not_been_installed

          • The identifier for the template. You can recall the template by ID in other operations.

          • The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

          • The date and time when the item was created. Format: date-time

          • Pass download URL.

  • The adaptive link ID does not exist.

Generate Pass from Adaptive Link

Example iOS Request

GET /v1/pass/adaptive/rthBWAWDaAA/ios HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

Example iOS Response

HTTP/1.1 200 OK
Content-Type: application/vnd.apple.pkpass

[.pkpass]

Example Android Request

GET /v1/pass/adaptive/rthBWAWDaAA/android HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

Example Android Response

HTTP/1.1 301 Redirect

GET /pass/adaptive/{adaptiveLinkId}/{device_type}

Generates a pass from an adaptive link.

When generating passes this way, you can append request parameters mapping to pass fields to the URL to add or update values to the pass at creation time. While this document lists reserved parameters, you can provide the fieldName=value for any field contained in the adaptive link.

If you configured your adaptive link object with the isPersonalized flag set to false (or the flag is absent), the first request will create a pass, and subsequent requests will create new instances of this same pass. If the isPersonalized flag is true, every request will create a new pass. If a request includes url-encoded parameters, the isPersonalized flag is considered true and Airship will always create a new pass for every request (instead of a pass instance).

query PARAMETERS
  • barcode : String

    Sets the barcode value for the new pass.

  • barcodeAltText : String

    The alternative text for the barcode on the pass. If unspecified, the barcode value is used as the barcodeAltText.

  • tags : String

    Tags you want to associate with the pass. Multiple tags may be separated by ~, e.g., &tags=tag1~tag2~tag3.

  • exid : String

    The external_id you want to set for this pass.

  • lat : String

    The latitude of the device installing the pass, used to calculate distance to locations specified in the adaptive link.

  • long : String

    The longitude of the device installing the pass, used to calculate distance to locations specified in the adaptive link.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • adaptiveLinkId : StringREQUIRED

    The identifier of the adaptive link you want to create a pass from.

  • device_type : StringREQUIRED

    The device type the user needs to install.

    If a device type is not specified in the path, Airship detects the device type from the request headers. If the device type cannot be detected Airship redirects the request to a landing page URL provided by the client as part of the adaptive link metadata. Airship recommends that this landing page provide buttons that link to the explicit device-specific Dynamic Link URLs for iOS and Android pass generation (e.g., this endpoint with the appropriate device type path parameter).

    Possible values: ios, android, web

Responses

  • 200

    This endpoint produces responses specific to the device type specified in the request. Requests for iOS passes return a .pkpass file. Requests for Android passes redirect to a Google Pay URL containing the Google pass JSON Web Token (JWT). Requests for web devices or without a device type specified return the landing page URL that a user can access to manually select a device type and install the pass.

    RESPONSE BODY
    • Content-Type: application/json

      A publicUrl for Android users or the landing page URL if the device type was set to web or was not specified.

    • Content-Type: application/vnd.apple.pkpass

      A .pkpass file for iOS users.

  • 404

    Could not find an entry with specified adaptiveLinkId.

Adaptive Links with external ID

Adaptive Link endpoints using external IDs — either for the link itself or for passes generated from adaptive links. An adaptive link is a link that detects the platform of a recipient and installs the correct pass. You can send adaptive links to both Apple and Google platform users; When a user on either platform taps the link, Airship detects the user’s device platform and returns the correct pass.

To send an adaptive link to both Google and Apple platforms, you must have configured templates for both platforms. You can send an adaptive link to an individual platform, and define the behavior for the unsupported platform.

Example Request

GET /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

Example Response

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

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": false,
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 730,
  "iosTemplateId": 54321,
  "iosTemplateExternalId": "<iosTemplateExternalId>",
  "androidTemplateId": 54322,
  "androidTemplateExternalId": "<androidTemplateExternalId>",
  "projectId": 12345,
  "projectExternalId": "myExternalProject",
  "createdAt": "2019-05-28T23:55:00.000Z",
  "updatedAt": "2019-05-31T00:59:42.000Z",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
  "status": 200
}

GET /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}

Get an adaptive link with an external ID from a project that also has an external ID.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The external ID of the project containing an adaptive link.

  • The custom identifier for an adaptive link.

  • Lists urls and available passes for an individual link.

    RESPONSE BODY
    • Content-Type: application/json

      An adaptive link response includes URLs that users can access to detect and install a pass.

  • The project or adaptive link does not exist.

Create Adaptive Link with external ID in Project with external ID

Example Request

POST /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
    "iosTemplateExternalId": "<iosTemplateExternalId>",
    "androidTemplateExternalId": "<androidTemplateExternalId>",
    "isPersonalized": "true",
    "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
    "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
    "landingPageUrl": "https://acustomer.com/landing.html",
    "availablePasses": 100000,
    "payload": {}
}

Example Response

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

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": false,
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 730,
  "iosTemplateId": 54321,
  "iosTemplateExternalId": "<iosTemplateExternalId>",
  "androidTemplateId": 54322,
  "androidTemplateExternalId": "<androidTemplateExternalId>",
  "projectId": 12345,
  "projectExternalId": "myExternalProject",
  "createdAt": "2019-05-28T23:55:00.000Z",
  "updatedAt": "2019-05-31T00:59:42.000Z",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
  "status": 200
}

POST /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}

Create an adaptive link in a project that also has an external ID. The adaptiveLinkExternalID you use in the path becomes the ID for your new adaptive link.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project containing an adaptive link.

  • adaptiveLinkExternalId : StringREQUIRED

    The custom identifier for an adaptive link.

Request Body

  • Content-Type: application/json

    Adaptive Link Request

    An adaptive link request contains identifiers for the templates you used to generate passes from the link, and any fields you want to set when users create passes from the link.

Responses

  • 200

    A successful request results in an adaptive link.

    RESPONSE BODY
    • Content-Type: application/json

      An adaptive link response includes URLs that users can access to detect and install a pass.

  • 404

    Could not find project, or could not find or create Dynamic Link object(s).

Example Request

GET /v1/links/adaptive/project/id/<projectExternalId>/id/<adaptiveLinkExternalId>/passes/id/<passExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

Example response

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

{
    "passes": [
        {
            "id": 39,
            "templateId": 6,
            "serialNumber": "6f019144-2285-4bb9-b28a-f863af887e53",
            "createdAt": "2019-03-06T17:48:28.000Z",
            "updatedAt": "2019-03-06T17:48:29.000Z",
            "externalId": "ext14"
        },
        {
            "id": 38,
            "templateId": 5,
            "serialNumber": "7f57d625-cf7c-455b-b3d9-c70adef7d889",
            "createdAt": "2019-03-06T17:39:00.000Z",
            "updatedAt": "2019-03-06T17:39:01.000Z",
            "externalId": "ext14"
        }
    ]
}

GET /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes/id/{passExternalId}

Get a pass with an external ID that was created from an adaptive link with an external ID.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The external ID of the pass you want to get.

  • The external ID of the project containing the adaptive link.

  • The adaptive link passes were created from.

  • Returns an array up to two passes created from the adaptive link — one for each template supported by the adaptive link.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • The metadata for passes associated with the adaptive link. Each object in the array represents a pass. Max items: 2 Min items: 1

        ARRAY ITEM
        • Pass Metadata

          Meta information about passes.

          OBJECT PROPERTIES
          • The date and time when the item was last updated. Format: date-time

          • The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

          • The date and time when pass was first installed on the device. Format: date-time

          • Wallet platform (iOS or Android).

            Possible values: iOS, Android

          • The serial number of the pass.

          • Recent on-device pass status.

            Possible values: installed, uninstalled, not_been_installed

          • The identifier for the template. You can recall the template by ID in other operations.

          • The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

          • The date and time when the item was created. Format: date-time

          • Pass download URL.

  • The project, adaptive link, or pass ID does not exist.

Example Request

PUT /v1/links/adaptive/project/id/<projectExternalId>/id/<adaptiveLinkExternalId>/passes/id/<passExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
    "fields": {
      "Details": {
          "changeMessage": "Enjoy %@ off your next order!",
          "value": "20%",
          "label": "Coupon"
      },
      "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
      }
    ],
    "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
Content-Type: application/json; charset=utf-8

{
    "tickets": [
        {
            "id": 15
        },
        {
            "id": 16
        }
    ]
}

PUT /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes/id/{passExternalId}

Update a pass with an external ID that was created from an adaptive link with an external ID. You need only provide the fields and headers you want to update for the pass; all other information will remain unchanged.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The external ID of the pass you want to update.

  • The external ID of the project containing the adaptive link.

  • The adaptive link passes were created from.

Provide only the fields or headers that you want to update for the specified pass.

Locations operate as a set operation. The array of pass locations is replaced by the locations you provide in an update; if you want to add to the locations on the pass, you must provide both the current locations and the locations you want to add in the payload.

  • Content-Type: application/json

    Update Apple Wallet Pass : Object

    OBJECT PROPERTIES
    • You can only include beacons for Apple Wallet passes.

    • The fields you want update on the pass.

    • The headers you want to update for this pass.

    • The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.

  • Returns a ticket IDs corresponding to the templates the adaptive link generated passes from. For example, if the pass was installed on both Android and iOS devices, the response will include two tickets — one to update passes supported by each template.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • Max items: 2 Min items: 1

        ARRAY ITEM
        • OBJECT PROPERTIES
          • A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.

  • The project, adaptive link, or pass ID does not exist.

Example Request

GET /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

Example Response

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

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": false,
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 730,
  "iosTemplateId": 54321,
  "androidTemplateId": 54322,
  "projectId": 12345,
  "createdAt": "2019-05-28T23:55:00.000Z",
  "updatedAt": "2019-05-31T00:59:42.000Z",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
  "status": 200
}

GET /links/adaptive/project/{projectId}/id/{adaptiveLinkExternalId}

Get an adaptive link with an external ID.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The ID of the project, generated by Airship, containing the adaptive link.

  • The custom identifier for the adaptive link.

  • Lists urls and available passes for an individual link.

    RESPONSE BODY
    • Content-Type: application/json

      An adaptive link response includes URLs that users can access to detect and install a pass.

  • The project or adaptive link does not exist.

Create Adaptive Link with external ID

Example Request

POST /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
    "iosTemplateId": "54321",
    "androidTemplateId": "54322",
    "isPersonalized": false,
    "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
    "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
    "landingPageUrl": "https://acustomer.com/landing.html",
    "availablePasses": 100000,
    "payload": {}
}

Example Response

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

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": false,
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 730,
  "iosTemplateId": 54321,
  "androidTemplateId": 54322,
  "projectId": 12345,
  "createdAt": "2019-05-28T23:55:00.000Z",
  "updatedAt": "2019-05-31T00:59:42.000Z",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
  "status": 200
}

POST /links/adaptive/project/{projectId}/id/{adaptiveLinkExternalId}

Create an adaptive link with an external ID. The adaptiveLinkExternalID you use in the path becomes the ID for your new adaptive link.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project, generated by Airship, containing the adaptive link.

  • adaptiveLinkExternalId : StringREQUIRED

    The custom identifier for the adaptive link.

Request Body

  • Content-Type: application/json

    Adaptive Link Request

    An adaptive link request contains identifiers for the templates you used to generate passes from the link, and any fields you want to set when users create passes from the link.

Responses

  • 200

    A successful request results in an adaptive link.

    RESPONSE BODY
    • Content-Type: application/json

      An adaptive link response includes URLs that users can access to detect and install a pass.

  • 404

    Could not find or create Dynamic Link object(s).

Example Request

GET /v1/links/adaptive/<adaptiveLinkId>/passes/id/<passExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

Example response

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

{
    "passes": [
        {
            "id": 39,
            "templateId": 6,
            "serialNumber": "6f019144-2285-4bb9-b28a-f863af887e53",
            "createdAt": "2019-03-06T17:48:28.000Z",
            "updatedAt": "2019-03-06T17:48:29.000Z",
            "externalId": "ext14"
        },
        {
            "id": 38,
            "templateId": 5,
            "serialNumber": "7f57d625-cf7c-455b-b3d9-c70adef7d889",
            "createdAt": "2019-03-06T17:39:00.000Z",
            "updatedAt": "2019-03-06T17:39:01.000Z",
            "externalId": "ext14"
        }
    ]
}

GET /links/adaptive/{adaptiveLinkId}/passes/id/{passExternalId}

Get passes with an external IDs that were created from an adaptive link.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The external ID of the pass you want to get.

  • The adaptive link passes were created from.

  • Returns an array up to two passes created from the adaptive link — one for each template supported by the adaptive link.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • The metadata for passes associated with the adaptive link. Each object in the array represents a pass. Max items: 2 Min items: 1

        ARRAY ITEM
        • Pass Metadata

          Meta information about passes.

          OBJECT PROPERTIES
          • The date and time when the item was last updated. Format: date-time

          • The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

          • The date and time when pass was first installed on the device. Format: date-time

          • Wallet platform (iOS or Android).

            Possible values: iOS, Android

          • The serial number of the pass.

          • Recent on-device pass status.

            Possible values: installed, uninstalled, not_been_installed

          • The identifier for the template. You can recall the template by ID in other operations.

          • The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

          • The date and time when the item was created. Format: date-time

          • Pass download URL.

  • The adaptive link or pass ID does not exist.

Example Request

PUT /v1/links/adaptive/<adaptiveLinkId>/passes/id/<passExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
    "fields": {
      "Details": {
          "changeMessage": "Enjoy %@ off your next order!",
          "value": "20%",
          "label": "Coupon"
      },
      "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
      }
    ],
    "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 201 Created
Content-Type: application/json; charset=utf-8

{
    "tickets": [
        {
            "id": 15
        },
        {
            "id": 16
        }
    ]
}

PUT /links/adaptive/{adaptiveLinkId}/passes/id/{passExternalId}

Update a pass with an external ID that was created from an adaptive link. You need only provide the fields and headers you want to update for the pass; all other information will remain unchanged.

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The external ID of the pass you want to update.

  • The adaptive link passes were created from.

Provide only the fields or headers that you want to update for the specified pass.

Locations operate as a set operation. The array of pass locations is replaced by the locations you provide in an update; if you want to add to the locations on the pass, you must provide both the current locations and the locations you want to add in the payload.

  • Content-Type: application/json

    Update Apple Wallet Pass : Object

    OBJECT PROPERTIES
    • You can only include beacons for Apple Wallet passes.

    • The fields you want update on the pass.

    • The headers you want to update for this pass.

    • The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.

  • Returns a ticket IDs corresponding to the templates the adaptive link generated passes from. For example, if the pass was installed on both Android and iOS devices, the response will include two tickets — one to update passes supported by each template.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • Max items: 2 Min items: 1

        ARRAY ITEM
        • OBJECT PROPERTIES
          • A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.

  • The adaptive link or pass ID does not exist.

Pass

A pass is essentially a populated, personalized template intended for a single platform — Apple Wallet or Google Wallet. Passes manifest as links; you distribute the pass link to users, and they tap or click the link to install the pass.

If you want to distribute passes to both Apple and Google users, you may want to use Adaptive links instead. While a pass is intended for a single platform, so you have to distribute separate pass links to independent Apple and Google audiences, an adaptive link is a single pass link that detects the user’s platform and installs the correct pass. Adaptive links can save you the trouble of maintaining separate passes and distribution lists for your customers.

Example Request

GET /v1/links/adaptive/<adaptiveLinkId>/passes HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

Example Response

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

{
    "passes": [{
        "id": 616,
        "templateId": 1000057,
        "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/616/download",
        "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da0b8",
        "createdAt": "2023-04-19T06:17:01.000Z",
        "updatedAt": "2023-04-19T06:17:01.000Z",
        "status": "installed",
        "installedAt": "2023-04-19T06:17:02.000Z",
        "platform": "android"
      },
      {
        "id": 610,
        "templateId": 1000083,
        "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/610/download",
        "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e216",
        "createdAt": "2023-04-05T17:55:23.000Z",
        "updatedAt": "2023-04-05T17:55:23.000Z",
        "status": "installed",
        "installedAt": "2023-04-05T17:55:23.000Z",
        "platform": "android"
      }
    ],
    "pagination": {
      "order": "id",
      "direction": "desc",
      "page": 1,
      "start": 0,
      "pageSize": 2
    }
}

GET /links/adaptive/{adaptiveLinkId}/passes

List passes for an adaptive link.

query PARAMETERS
  • Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • The number of passes per page. Defaults to 10.

  • The page of results you want to retrieve, starting at 1.

  • The order you want passes returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

  • Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • The adaptive link ID used for pass creation.

  • A successful request returns a paged list of passes for a particular adaptive link.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • The total number of passes associated with an adaptive link.

      • Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • The key in the result set that you want to order results by. Defaults to id.

        • The page you are on. Multiply by the page size to determine the result set on the page.

        • The number of results per page.

        • The first result on the page; results begin with 0.

      • The metadata for passes associated with the adaptive link. Each object in the array represents a pass.

        ARRAY ITEM
        • Pass Metadata

          Meta information about passes.

          OBJECT PROPERTIES
          • The date and time when the item was last updated. Format: date-time

          • The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

          • The date and time when pass was first installed on the device. Format: date-time

          • Wallet platform (iOS or Android).

            Possible values: iOS, Android

          • The serial number of the pass.

          • Recent on-device pass status.

            Possible values: installed, uninstalled, not_been_installed

          • The identifier for the template. You can recall the template by ID in other operations.

          • The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

          • The date and time when the item was created. Format: date-time

          • Pass download URL.

  • The adaptive link ID does not exist.

List your passes

Example Request

GET /v1/pass?templateId=12345&status=uninstalled HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

{
          "passes": [{
              "id": 61,
              "templateId": 12345,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
              "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
              "createdAt": "2023-04-19T06:17:01.000Z",
              "updatedAt": "2023-04-19T06:17:01.000Z",
              "status": "uninstalled",
              "installedAt": "2023-04-19T06:17:02.000Z",
              "platform": "android"
            },
            {
              "id": 60,
              "templateId": 12345,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/60/download",
              "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e201",
              "createdAt": "2023-04-05T17:55:23.000Z",
              "updatedAt": "2023-04-05T17:55:23.000Z",
              "status": "installed",
              "installedAt": "2023-04-05T17:55:23.000Z",
              "platform": "android"
            }
          ],
          "pagination": {
            "order": "id",
            "direction": "desc",
            "page": 1,
            "start": 0,
            "pageSize": 2
          }
}

GET /pass

List passes that your user account is responsible for. You can provide an optional template parameter, returning passes created from a particular template.

Security:

query PARAMETERS
  • templateId : String

    The id of the template you want to look up.

  • status : String

    Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • pageSize : Integer

    The number of passes per page. Defaults to 10.

  • page : Integer

    The page of results you want to retrieve, starting at 1.

  • order : String

    The order you want passes returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

  • direction : String

    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Responses

  • 200

    A successful request returns a paged list of passes created from a particular template.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • count : Integer

        The total number of passes associated with the template.

      • pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

      • passes : Array [Object]

        The metadata for passes associated with the template. Each object in the array represents a pass.

        ARRAY ITEM
        • Pass Metadata

          Meta information about passes.

          OBJECT PROPERTIES
          • createdAt : String

            The date and time when the item was last updated. Format: date-time

          • id : Integer

            The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

          • installedAt : String

            The date and time when pass was first installed on the device. Format: date-time

          • platform : String

            Wallet platform (iOS or Android).

            Possible values: iOS, Android

          • serialNumber : String

            The serial number of the pass.

          • status : String

            Recent on-device pass status.

            Possible values: installed, uninstalled, not_been_installed

          • templateId : Integer

            The identifier for the template. You can recall the template by ID in other operations.

          • uninstalledAt : String

            The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

          • updatedAt : String

            The date and time when the item was created. Format: date-time

          • url : String

            Pass download URL.

Create a Dynamic Link

Example Request

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

{
   "headers": {
      "expirationDate": {
         "value": "2014-08-20T09:41-08:00"
      },
         "barcodeAltText": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         },
         "barcode_value": {
            "changeMessage" : null,
            "value": "abc1234567890",
            "label": ""
         }
   },
   "fields": {
      "Coupon": {
         "changeMessage": "Enjoy %@ off your next order!",
         "value": "20%",
         "label": "Coupon"
      },
         "SiteAddress": {
            "changeMessage": "Check out things we think you would like at %@",
            "value": "https://www.store.com/new?custnumb=123456",
            "label": "personal deals"
         },
         "InStore": {
            "changeMessage": "Or visit your nearest store at %@",
            "value": "1234 Fake St.",
            "label": "nearestStore"
         },
         "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 Request with Payload

{
   "url": "https://wallet-api.urbanairship.com/v1/pass/dynamic/44e128a5-ac7a-4c9a-be4c-224b6bf81b20","message": "Existing Dynamic Link"
}

POST /pass/{Id}/dynamic

Generates a pass with an optional expiration date and serial number. You can also assign an external ID to passes generated from this endpoint.

Security:

query PARAMETERS
  • expiry : String

    The expiration date for the pass.

    Format: date

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • Id : StringREQUIRED

    The templateId of the template you want to create the pass from.

Request Body

Create a pass; pass composition varies by vendor.

  • Content-Type: application/json

    One of
    • Apple Wallet Pass Request

      A pass for Apple Wallet.

    • Google Wallet Pass Request

      A pass for Google Wallet. Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module that the field belongs to.

      Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

Responses

  • 200

    A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.

    RESPONSE BODY
    • Content-Type: application/json

      One of
      • Apple Wallet Pass Response

        A pass response includes both identifiers and the content of all fields on a pass.

      • Google Wallet Pass Response

        A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

        Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module (an object) that the field belongs to.

        Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

Get Pass

Example Request

GET /v1/pass/1234 HTTP/1.1
Authorization: Basic <Base64 key>
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": "%@",
         "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": "%@",
         "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": "The new date is %@",
         "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": "Get event details at %@",
         "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": "You are now seated at %@",
         "numberStyle": "PKNumberStyleDecimal",
         "label": "Seat",
         "hideEmpty": false,
         "formatType": "Number",
         "value": 1.0,
         "fieldType": "auxiliary",
         "required": false,
         "order": 3
      },
      "Row": {
         "textAlignment": "textAlignmentNatural",
         "changeMessage": "You are now seated in row %@",
         "numberStyle": "PKNumberStyleDecimal",
         "label": "Row",
         "hideEmpty": false,
         "formatType": "Number",
         "value": 1.0,
         "fieldType": "auxiliary",
         "required": false,
         "order": 2
      },
      "Section": {
         "textAlignment": "textAlignmentLeft",
         "changeMessage": "You are now seated in section %@",
         "label": "Section",
         "hideEmpty": false,
         "formatType": "String",
         "value": "1",
         "fieldType": "auxiliary",
         "required": true,
         "order": 1
      }
   }
}

GET /pass/{id}

Get the specified pass. This endpoint will return the external ID of a pass, but only if there is one associated with it.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • id : StringREQUIRED

    The id of the pass you want to look up.

Responses

  • 200

    Returns a complete pass, including headers and fields on the pass and metadata about the pass.

    RESPONSE BODY
    • Content-Type: application/json

      One of
      • Apple Wallet Pass Response

        A pass response includes both identifiers and the content of all fields on a pass.

      • Google Wallet Pass Response

        A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

        Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module (an object) that the field belongs to.

        Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

Update Pass

Update Expiration Date Example Request

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

{
   "headers": {
      "expirationDate": {
            "value": "2024-08-20T9:41-08:00"
      }
   },
   "fields": {
      "Seat": {
            "value": "26E"
      }
   }
}

Render Pass Void Example Request

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

{
   "headers": {
      "expirationDate": {
            "label": "voided"
      }
   }
}

Example Request

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

{
    "fields": {
       "Coupon": {
          "changeMessage": "Enjoy %@ off your next order!",
          "value": "20%",
          "label": "Coupon"
       },
       "SiteAddress": {
          "changeMessage": "Check out things we think you would like at %@",
          "value": "https://www.store.com/new?custnumb=123456",
          "label": "personal deals"
       },
       "InStore": {
          "changeMessage": "Or visit your nearest store at %@",
          "value": "1234 Fake St.",
          "label": "nearestStore"
       },
       "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"
       }
    ],
    "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

{
    "ticketId": 1234
}

PUT /pass/{id}

Update the specified pass. You need only include the fields that you want to update for the pass.

Optionally, you can also Schedule an update if you want to update a pass at a later date and time. See the /schedules endpoints for information about scheduling updates.

Do not use the response payload from the GET /v1/pass/(id) endpoint to update a pass, as it contains information from both the pass itself and the template used to create the pass, and you cannot update a template from the /v1/pass endpoint. You should only populate the JSON Parameters below. Within the headers and fields objects, these are the changeMessage, value, and label fields.

You can update locations on a pass, but doing so will replace all locations on the pass. See the Location Object for more about the fields you should provide in the locations array.

 Note

You can also update a pass to include an expiration date using the expirationDate key.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • id : StringREQUIRED

    The id of the pass you want to update.

Request Body

Provide only the fields from a pass object that you want to update.

Locations operate as a set operation. The array of pass locations is replaced by the locations you provide in an update; if you want to add to the locations on the pass, you must provide both the current locations and the locations you want to add in the payload.

  • Content-Type: application/json

    Update Apple Wallet Pass : Object

    OBJECT PROPERTIES
    • beacons : Array [Beacon Object (iOS Only)]

      You can only include beacons for Apple Wallet passes.

    • fields : Object

      The fields you want update on the pass.

    • headers : Object

      The headers you want to update for this pass.

    • locations : Array [Location Object]

      The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.

Responses

  • 200

    A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.

    RESPONSE BODY
    • Content-Type: application/json

      One of
      • Apple Wallet Pass Response

        A pass response includes both identifiers and the content of all fields on a pass.

      • Google Wallet Pass Response

        A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

        Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module (an object) that the field belongs to.

        Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

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-20T09:41-08:00"
         },
         "barcodeAltText": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         },
         "barcode_value": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         }
    },
    "fields": {
      "Coupon": {
         "changeMessage": "Enjoy %@ off your next order!",
         "value": "20%",
         "label": "Coupon"
      },
      "SiteAddress": {
         "changeMessage": "Check out things we think you would like at %@",
         "value": "https://www.store.com/new?custnumb=123456",
         "label": "personal deals"
      },
      "InStore": {
         "changeMessage": "Or visit your nearest store at %@",
         "value": "1234 Fake St.",
         "label": "nearestStore"
      },
      "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
        }
    ],
    "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"
        }
    ],
    "publicUrl": {
        "type": "single"
    }
}

Example Request with Payload

{
    "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": {
        "gate": {
            "changeMessage": "Your gate has changed to %@",
            "fieldType": "HEADER",
            "value": "A56",
            "label": "my value",
            "required": false
        },
        "logo_text": {
            "changeMessage": null,
            "fieldType": "TOP_LEVEL",
            "value": "Test Value",
            "label": "",
            "required": false
        },
        "boarding_time": {
            "changeMessage": "Be at your new gate by %@",
            "fieldType": "PRIMARY",
            "value": "08:45",
            "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
        }
    ],
    "locations":[
        {
            "relevantText":"Hello loc0",
            "latitude":37.618,
            "id":30473906,
            "longitude":-122.374
        }
    ]
}

POST /pass/{id}

Create a pass from the specified template.

You can optionally assign an external ID to the pass or generate the pass from templates with external IDs. See the appropriate endpoints to assign or use external IDs.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • id : StringREQUIRED

    The id of the template you want to create your pass from.

Request Body

Create a pass; pass composition varies by vendor.

  • Content-Type: application/json

    One of
    • Apple Wallet Pass Request

      A pass for Apple Wallet.

    • Google Wallet Pass Request

      A pass for Google Wallet. Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module that the field belongs to.

      Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

Responses

  • 200

    A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.

    RESPONSE BODY
    • Content-Type: application/json

      One of
      • Apple Wallet Pass Response

        A pass response includes both identifiers and the content of all fields on a pass.

      • Google Wallet Pass Response

        A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

        Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module (an object) that the field belongs to.

        Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

Delete Pass

Example Request

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

Example Response

{
    "status": "deleted",
    "passId": "123"
}

DELETE /pass/{id}

Delete the specified pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • id : StringREQUIRED

    The id of the pass you want to delete.

Responses

  • 200

    The pass was successfully deleted.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • passId : Integer

        The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

      • status : String

        Indicates that the pass was deleted.

        Possible values: deleted

Delete Location from Pass

Example Request

DELETE /v1/pass/123/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

DELETE /pass/{passId}/location/{passLocationId}

Delete the specified location from the specified pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passId : StringREQUIRED

    The id of the pass you want to remove locations from.

  • passLocationId : StringREQUIRED

    The location you want to remove from the pass.

Responses

  • 200

    Success.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES

Add Locations to Pass

Example Request

POST /v1/pass/123/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"
    },
    { "...": "..." }
  ]
}

Example Response

[
   {
      "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 /pass/{passId}/locations

Add the locations to the specified pass.

 Important

As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services. This affects a majority of Google passes. Google has not committed to a timetable to resolve the issue and make location triggers available to all Google passes again.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passId : StringREQUIRED

    The pass you want to add locations to.

Request Body

Set locations for the pass.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES

Responses

  • 200

    Returns passLocationId for each location on the pass. Use this value to identify locations in other location-based operations.

    RESPONSE BODY
    • Content-Type: application/json

      ARRAY ITEM
      • OBJECT PROPERTIES
        • passLocationId : Integer

          The identifier for a location.

        • value : Location Object

          Represents a location on a pass or an adaptive link.

          Place objects in the locations array to add location information to passes and templates. Updating locations on a pass or template will replace all locations on that pass; if you want to add to the locations on a pass, you must provide all locations already included on the pass and any additional locations you want to add.

          Apple Wallet supports up to 10 locations per pass. If you exceed this limit for an iOS pass, we will use the 10 locations nearest to a user (located by IP address) when they install the pass.

          As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services. This affects a majority of Google passes. Google has not committed to a timetable to resolve the issue and make location triggers available to all Google passes again.

List Passes Bearing a Tag

Example Request

GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

Example Response

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

{
          "passes": [{
              "id": 61,
              "templateId": 1000057,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
              "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
              "createdAt": "2023-04-19T06:15:01.000Z",
              "updatedAt": "2023-04-19T06:15:01.000Z",
              "status": "installed",
              "installedAt": "2023-04-19T06:17:02.000Z",
              "platform": "android"
            },
            {
              "id": 51,
              "templateId": 1000081,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/51/download",
              "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e223",
              "createdAt": "2023-04-05T17:55:23.000Z",
              "updatedAt": "2023-04-05T17:55:23.000Z",
              "status": "installed",
              "installedAt": "2023-04-05T17:55:23.000Z",
              "platform": "ios"
            }
          ],
          "pagination": {
            "order": "id",
            "direction": "desc",
            "page": 1,
            "start": 0,
            "pageSize": 2
          }
}

GET /tag/{tag}/passes

List the passes associated with the specified tag.

Security:

query PARAMETERS
  • status : String

    Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • pageSize : Integer

    The number of passes per page. Defaults to 10.

  • page : Integer

    The page of results you want to retrieve, starting at 1.

  • order : String

    The order you want tags returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

  • direction : String

    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • tag : StringREQUIRED

    A tag id or name. The request returns a paginated list of passes associated with the specified tag.

Responses

  • 200

    A successful response returns a paginated array of passes.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • count : Integer

        The total number of results.

      • pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

      • passes : Object

        Meta information about passes.

        OBJECT PROPERTIES
        • createdAt : String

          The date and time when the item was last updated. Format: date-time

        • id : Integer

          The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

        • installedAt : String

          The date and time when pass was first installed on the device. Format: date-time

        • platform : String

          Wallet platform (iOS or Android).

          Possible values: iOS, Android

        • serialNumber : String

          The serial number of the pass.

        • status : String

          Recent on-device pass status.

          Possible values: installed, uninstalled, not_been_installed

        • templateId : Integer

          The identifier for the template. You can recall the template by ID in other operations.

        • uninstalledAt : String

          The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

        • updatedAt : String

          The date and time when the item was created. Format: date-time

        • url : String

          Pass download URL.

Pass using external ID

These endpoints support passes incorporating external IDs for the template, the pass, or both. A pass is essentially a populated, personalized template intended for a single platform — Apple Wallet or Google Wallet. Passes manifest as links; you distribute the pass link to users, and they tap or click the link to install the pass.

If you want to distribute passes to both Apple and Google users, you may want to use adaptive links instead. While a pass is intended for a single platform, so you have to distribute separate pass links to independent Apple and Google audiences, an adaptive link is a single pass link that detects the user’s platform and installs the correct pass. Adaptive links can save you the trouble of maintaining separate passes and distribution lists for your customers.

Update Pass with external ID

Example Request

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

{
    "templates": ["5350", "5359"],
    "fields": {
       "Coupon": {
          "changeMessage": "Enjoy %@ off your next order!",
          "value": "20%",
          "label": "Coupon"
       },
       "SiteAddress": {
          "changeMessage": "Check out things we think you would like at %@",
          "value": "https://www.store.com/new?custnumb=123456",
          "label": "personal deals"
       },
       "InStore": {
          "changeMessage": "Or visit your nearest store at %@",
          "value": "1234 Fake St.",
          "label": "nearestStore"
       },
       "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"
       }
    ],
    "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

{
    "ticketId": 1234
}

PUT /pass/id/{externalId}

Update the specified pass. You need only include the fields that you want to update for the pass.

Do not use the response payload from a GET to update a pass, as it contains information from both the pass itself and the template used to create the pass, and you cannot update a template from the /v1/pass endpoint. You should only populate the JSON Parameters below. Within the headers and fields objects, these are the changeMessage, value, and label fields.

You can update locations on a pass, but doing so will replace all locations on the pass. See the Location Object for more about the fields you should provide in the locations array.

 Note

You can also update a pass to include an expiration date using the expirationDate key.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : StringREQUIRED

    The external ID of the pass you want to modify.

Request Body

Provide only the fields you want to update.

Locations operate as a set operation. The array of pass locations is replaced by the locations you provide in an update; if you want to add to the locations on the pass, you must provide both the current locations and the locations you want to add in the payload.

  • Content-Type: application/json

    All of
    • Object

      OBJECT PROPERTIES
      • templates : Array [Integer]

        Include an array of templates IDs, required to identify individual passes if there are multiple passes for the external ID in the path. If there are multiple passes for the external ID and you do not specify the templates corresponding to the passes you want to update, your request will return a 400.

    • Update Apple Wallet Pass : Object

      OBJECT PROPERTIES
      • beacons : Array [Beacon Object (iOS Only)]

        You can only include beacons for Apple Wallet passes.

      • fields : Object

        The fields you want update on the pass.

      • headers : Object

        The headers you want to update for this pass.

      • locations : Array [Location Object]

        The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.

Responses

  • 200

    A response returns one or more ticketId values, each referencing the pass update operation. If your request does not include the templates array, the response includes a single ticketId. If your request includes the templates array, the response is an array of of ticket objects, corresponding to the order of templates in the array.

    RESPONSE BODY
    • Content-Type: application/json

      One of
      • Object

        OBJECT PROPERTIES
        • ticketId : Integer

          A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.

      • Array [Object]

        ARRAY ITEM
        • OBJECT PROPERTIES
          • ticketId : Integer

            A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.

Create Pass from a Template with an external ID

Example Request

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

{
    "headers": {
        "expirationDate": {
           "value": "2014-08-20T09:41-08:00"
         },
         "barcodeAltText": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         },
         "barcode_value": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         }
    },
    "fields": {
      "Coupon": {
         "changeMessage": "Enjoy %@ off your next order!",
         "value": "20%",
         "label": "Coupon"
      },
      "SiteAddress": {
         "changeMessage": "Check out things we think you would like at %@",
         "value": "https://www.store.com/new?custnumb=123456",
         "label": "personal deals"
      },
      "InStore": {
         "changeMessage": "Or visit your nearest store at %@",
         "value": "1234 Fake St.",
         "label": "nearestStore"
      },
      "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
        }
    ],
    "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"
        }
    ],
    "publicUrl": {
        "type": "single"
    }
}

Example Request with Payload

{
    "externalId": "myNewPass",
    "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": {
        "gate": {
            "changeMessage": "Your gate has changed to %@",
            "fieldType": "HEADER",
            "value": "A56",
            "label": "my value",
            "required": false
        },
        "logo_text": {
            "changeMessage": null,
            "fieldType": "TOP_LEVEL",
            "value": "Test Value",
            "label": "",
            "required": false
        },
        "boarding_time": {
            "changeMessage": "Be at your new gate by %@",
            "fieldType": "PRIMARY",
            "value": "08:45",
            "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
        }
    ],
    "locations":[
        {
            "relevantText":"Hello loc0",
            "latitude":37.618,
            "id":30473906,
            "longitude":-122.374
        }
    ]
}

POST /pass/id/{templateExternalId}/id/{passExternalId}

Create a pass from the specified template and give it a custom identifier. You can use this custom ID to perform operations against the pass in addition to the standard, unique id given by Wallet.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateExternalId : StringREQUIRED

    The external ID of the template you want to create your pass from.

  • passExternalId : StringREQUIRED

    The external ID that you want to give your pass.

Request Body

Create a pass; pass composition varies by vendor.

  • Content-Type: application/json

    One of
    • Apple Wallet Pass Request

      A pass for Apple Wallet.

    • Google Wallet Pass Request

      A pass for Google Wallet. Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module that the field belongs to.

      Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

Responses

  • 200

    A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.

    RESPONSE BODY
    • Content-Type: application/json

      One of
      • Apple Wallet Pass Response

        A pass response includes both identifiers and the content of all fields on a pass.

      • Google Wallet Pass Response

        A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

        Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module (an object) that the field belongs to.

        Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

Get Pass with external ID

Example Request

GET /v1/pass/template/123/id/mypass HTTP/1.1
Authorization: Basic <Base64 key>
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": "%@",
         "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": "%@",
         "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": "The new date is %@",
         "label": "relevantDate",
         "hideEmpty": false,
         "formatType": "String",
         "value": "2015-12-31T23:00:00-08:00",
         "fieldType": "topLevel",
         "required": false
      }
   },
   "id": "1234",
   "templateId": "12345",
   "externalId": "mypass",
   "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": "Get event details at %@",
         "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": "You are now seated at %@",
         "numberStyle": "PKNumberStyleDecimal",
         "label": "Seat",
         "hideEmpty": false,
         "formatType": "Number",
         "value": 1.0,
         "fieldType": "auxiliary",
         "required": false,
         "order": 3
      },
      "Row": {
         "textAlignment": "textAlignmentNatural",
         "changeMessage": "You are now seated in row %@",
         "numberStyle": "PKNumberStyleDecimal",
         "label": "Row",
         "hideEmpty": false,
         "formatType": "Number",
         "value": 1.0,
         "fieldType": "auxiliary",
         "required": false,
         "order": 2
      },
      "Section": {
         "textAlignment": "textAlignmentLeft",
         "changeMessage": "You are now seated in section %@",
         "label": "Section",
         "hideEmpty": false,
         "formatType": "String",
         "value": "1",
         "fieldType": "auxiliary",
         "required": true,
         "order": 1
      }
   }
}

GET /pass/template/{templateId}/id/{passExternalId}

Get a pass with an external ID

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passExternalId : StringREQUIRED

    The custom ID assigned to the pass.

  • templateId : StringREQUIRED

    The template the pass is created from.

Responses

  • 200

    A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.

    RESPONSE BODY
    • Content-Type: application/json

      One of
      • Apple Wallet Pass Response

        A pass response includes both identifiers and the content of all fields on a pass.

      • Google Wallet Pass Response

        A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

        Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module (an object) that the field belongs to.

        Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

  • 404

    The pass or template ID does not exist.

Update Pass with external ID for a Single Template

Example Request

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

{
    "fields": {
       "Coupon": {
          "changeMessage": "Enjoy %@ off your next order!",
          "value": "20%",
          "label": "Coupon"
       },
       "SiteAddress": {
          "changeMessage": "Check out things we think you would like at %@",
          "value": "https://www.store.com/new?custnumb=123456",
          "label": "personal deals"
       },
       "InStore": {
          "changeMessage": "Or visit your nearest store at %@",
          "value": "1234 Fake St.",
          "label": "nearestStore"
       },
       "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"
       }
    ],
    "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 201 Created
Content-Type: application/json; charset=utf-8

{
      "ticketId": 1234
}

PUT /pass/template/{templateId}/id/{passExternalId}

Update a pass with an external ID

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passExternalId : StringREQUIRED

    The external ID of the pass you want to modify.

  • templateId : StringREQUIRED

    The template the pass is created from.

Request Body

Update a pass. You can provide any of the fields or headers used when creating a pass to update the pass.

  • Content-Type: application/json

    One of
    • Apple Wallet Pass Request

      A pass for Apple Wallet.

    • Google Wallet Pass Request

      A pass for Google Wallet. Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module that the field belongs to.

      Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

Responses

  • 200

    The response contains a ticketId that you can use to lookup the operation.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ticketId : Integer

        An identifier for this operation.

  • 400

    The request was malformed.

  • 404

    The pass or template ID does not exist.

Create Pass with an external ID

Example Request

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

{
    "headers": {
        "expirationDate": {
           "value": "2014-08-20T09:41-08:00"
         },
         "barcodeAltText": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         },
         "barcode_value": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         }
    },
    "fields": {
      "Coupon": {
         "changeMessage": "Enjoy %@ off your next order!",
         "value": "20%",
         "label": "Coupon"
      },
      "SiteAddress": {
         "changeMessage": "Check out things we think you would like at %@",
         "value": "https://www.store.com/new?custnumb=123456",
         "label": "personal deals"
      },
      "InStore": {
         "changeMessage": "Or visit your nearest store at %@",
         "value": "1234 Fake St.",
         "label": "nearestStore"
      },
      "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
        }
    ],
    "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"
        }
    ],
    "publicUrl": {
        "type": "single"
    }
}

Example Request with Payload

{
    "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": {
        "gate": {
            "changeMessage": "Your gate has changed to %@",
            "fieldType": "HEADER",
            "value": "A56",
            "label": "my value",
            "required": false
        },
        "logo_text": {
            "changeMessage": null,
            "fieldType": "TOP_LEVEL",
            "value": "Test Value",
            "label": "",
            "required": false
        },
        "boarding_time": {
            "changeMessage": "Be at your new gate by %@",
            "fieldType": "PRIMARY",
            "value": "08:45",
            "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
        }
    ],
    "locations":[
        {
            "relevantText":"Hello loc0",
            "latitude":37.618,
            "id":30473906,
            "longitude":-122.374
        }
    ]
}

POST /pass/template/{templateId}/id/{passExternalId}

Create a pass from the specified template and give it a custom identifier. You can use this custom ID to perform operations against the pass like you would use the standard, unique id given by Wallet.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passExternalId : StringREQUIRED

    The external ID you want to assign to the new pass.

  • templateId : StringREQUIRED

    The template the pass is created from.

Request Body

Create a pass; pass composition varies by vendor.

  • Content-Type: application/json

    One of
    • Apple Wallet Pass Request

      A pass for Apple Wallet.

    • Google Wallet Pass Request

      A pass for Google Wallet. Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module that the field belongs to.

      Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

Responses

  • 200

    A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.

    RESPONSE BODY
    • Content-Type: application/json

      One of
      • Apple Wallet Pass Response

        A pass response includes both identifiers and the content of all fields on a pass.

      • Google Wallet Pass Response

        A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

        Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module (an object) that the field belongs to.

        Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

  • 404

    The pass or template ID does not exist.

Delete Pass with external ID

Example Request

DELETE /v1/pass/template/<templateId>/id/<passExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

Example Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
   "status": "deleted",
   "passId": "33"
}

DELETE /pass/template/{templateId}/id/{passExternalId}

Delete a pass with an external ID

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passExternalId : StringREQUIRED

    The external ID of the pass you want to delete.

  • templateId : StringREQUIRED

    The template the pass is created from.

Responses

  • 200

    The pass was successfully deleted.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • passId : Integer

        The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

      • status : String

        Indicates that the pass was deleted.

        Possible values: deleted

  • 404

    The pass or template ID does not exist.

Delete Location from Pass with external ID

Example Request

DELETE /v1/pass/template/123/id/mypass/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

DELETE /pass/template/{templateId}/id/{passExternalId}/location/{locationId}

Delete the specified location from a pass using an external ID.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The template of the pass that you want to delete locations from.

  • passExternalId : StringREQUIRED

    The external ID of the pass you want to delete locations from.

  • locationId : StringREQUIRED

    The location you want to remove from the pass.

Responses

  • 200

    Success.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
  • 404

    The pass, template ID, or location does not exist.

Add Locations to Pass with external ID

Example Request

POST /v1/pass/template/123/id/mypass/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"
    },
    { "...": "..." }
  ]
}

Example Response

[
   {
      "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 /pass/template/{templateId}/id/{passExternalId}/locations

Add the locations to the specified pass.

 Important

As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services. This affects a majority of Google passes. Google has not committed to a timetable to resolve the issue and make location triggers available to all Google passes again.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The template of the pass that you want to add locations to.

  • passExternalId : StringREQUIRED

    The external ID of the pass you want to add locations to.

Request Body

Set locations for the pass.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES

Responses

  • 200

    Returns passLocationId for each location on the pass. Use this value to identify locations in other location-based operations.

    RESPONSE BODY
    • Content-Type: application/json

      ARRAY ITEM
      • OBJECT PROPERTIES
        • passLocationId : Integer

          The identifier for a location.

        • value : Location Object

          Represents a location on a pass or an adaptive link.

          Place objects in the locations array to add location information to passes and templates. Updating locations on a pass or template will replace all locations on that pass; if you want to add to the locations on a pass, you must provide all locations already included on the pass and any additional locations you want to add.

          Apple Wallet supports up to 10 locations per pass. If you exceed this limit for an iOS pass, we will use the 10 locations nearest to a user (located by IP address) when they install the pass.

          As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services. This affects a majority of Google passes. Google has not committed to a timetable to resolve the issue and make location triggers available to all Google passes again.

  • 404

    The pass or template ID does not exist.

Tags

Tags are plain-text identifiers for passes. Use tags to identify passes for segmentation purposes, or to target an audience of passes for updates.

Tags are limited to 15 per pass.

List Tags for Pass

Example Request

GET /v1/pass/123/tags HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

Example Response

{
  "tags": [
    {
      "id": 72,
      "createdAt": "2013-07-10T11:38:06Z",
      "name": "tag-2971-4280-479"
    },
    {
      "id": 73,
      "createdAt": "2013-07-10 11:52:20Z",
      "name": "tag-1049-2951-9529"
    },
    {
      "id": 74,
      "createdAt": "2013-07-10 11:59:32Z",
      "name": "tag-385-9612-723"
    },
    {
      "id": 75,
      "createdAt": "2013-07-10 12:00:18Z",
      "name": "tag-5784-6282-8767"
    },
    {
      "id": 76,
      "createdAt": "2013-07-10 12:00:55Z",
      "name": "tag-1050-1982-8211"
    },
    {
      "id": 77,
      "createdAt": "2013-07-10 12:02:09Z",
      "name": "tag-5040-8715-7744"
    }
  ]
}

GET /pass/{passId}/tags

List tags assigned to the specified pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passId : StringREQUIRED

    The ID of the pass you want to list tags for.

Responses

  • 200

    An array of tags belonging to the pass.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • tags : Array [Object]

        An array of tags associated with the pass.

        ARRAY ITEM
        • Tag Object

          OBJECT PROPERTIES
          • createdAt : String

            The date and time when the item was created. Format: date-time

          • id : Integer

            The ID of the tag, used to reference the tag.

          • name : String

            The name of the tag.

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

Example Response

{
  "newTags": ["tag-name"],
  "mappings": 1
}

PUT /pass/{passId}/tags

Add tags to a pass, limited to 15 tags per pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passId : StringREQUIRED

    The ID of the pass you want to add tags to.

Request Body

An array of tags that you want to associate with the pass.

  • Content-Type: application/json

    Add Tags to PassRequest : Object

    An array of tags that you want to add to a pass.

    OBJECT PROPERTIES
    • tags : Array [String]REQUIRED

      An array of strings, each string representing a tag. Max items: 15

Responses

  • 200

    Lists the tags added to the pass.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • mappings : Integer

        The number of tags added.

      • newTags : Array [String]

        A list of tags successfully added to the pass.

List All Tags

Example Request

GET /v1/tag HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

Example Request with Payload

{
  "tags": [
    {
      "id": 2,
      "tag": "Gold",
      "createdAt": "2018-03-02T23:49:53Z"
    },
    {
      "id": 3,
      "tag": "Silver",
      "createdAt": "2018-03-02T23:49:53Z"
    },
    {
      "id": 4,
      "tag": "Platinum",
      "createdAt": "2018-03-02T23:49:53Z"
    },
    {
      "id": 5,
      "tag": "Enterprise",
      "createdAt": "2018-03-02T23:49:53Z"
    }
  ],
  "Pagination": {
    "order": "ID",
    "page": 1,
    "start": 0,
    "direction": "DESC",
    "pageSize": 10
  },
  "count": 4
}

GET /tag

List all tags.

Security:

query PARAMETERS
  • pageSize : Integer

    The number of tags per page. Defaults to 10.

  • page : Integer

    The page of results you want to retrieve, starting at 1.

  • order : String

    The order you want tags returned in, defaulting to id.

    Possible values: id, createdAt

  • direction : String

    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Responses

  • 200

    A paginated array of tags.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • Pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

      • count : Integer

        The number of items returned.

      • tags : Array [Object]

        ARRAY ITEM
        • Tag Object

          OBJECT PROPERTIES
          • createdAt : String

            The date and time when the item was created. Format: date-time

          • id : Integer

            The ID of the tag, used to reference the tag.

          • name : String

            The name of the tag.

Delete Tag

Example Request

DELETE /v1/tag/tag-name HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

DELETE /tag/{tag}

Delete the specified tag and remove it from all passes.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • tag : StringREQUIRED

    The tag you want to delete.

Responses

  • 200

    A successful operation returns a count of affected passes.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • count : Integer

        The number of passes the tag was removed from.

      • status : String

        The operation was successful.

        Possible values: success

      • tagId : Integer

        The ID of the deleted tag.

Remove Tag from a Pass

Example Request

DELETE /v1/tag/tag-name/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

DELETE /tag/{tag}/pass/{pass}

Remove a tag from the specified pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • tag : StringREQUIRED

    The tag you want to remove from the pass.

  • pass : StringREQUIRED

    The pass you want to remove the tag from.

Responses

  • 200

    A successful response includes the ID of the tag and the ID of the pass it was removed from.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • passId : Integer

        The ID of the pass that the tag was removed from.

      • status : String

        The operation was successful.

        Possible values: success

      • tagId : Integer

        The ID of the tag.

List Passes Bearing a Tag

Example Request

GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

Example Response

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

{
          "passes": [{
              "id": 61,
              "templateId": 1000057,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
              "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
              "createdAt": "2023-04-19T06:15:01.000Z",
              "updatedAt": "2023-04-19T06:15:01.000Z",
              "status": "installed",
              "installedAt": "2023-04-19T06:17:02.000Z",
              "platform": "android"
            },
            {
              "id": 51,
              "templateId": 1000081,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/51/download",
              "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e223",
              "createdAt": "2023-04-05T17:55:23.000Z",
              "updatedAt": "2023-04-05T17:55:23.000Z",
              "status": "installed",
              "installedAt": "2023-04-05T17:55:23.000Z",
              "platform": "ios"
            }
          ],
          "pagination": {
            "order": "id",
            "direction": "desc",
            "page": 1,
            "start": 0,
            "pageSize": 2
          }
}

GET /tag/{tag}/passes

List the passes associated with the specified tag.

Security:

query PARAMETERS
  • status : String

    Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • pageSize : Integer

    The number of passes per page. Defaults to 10.

  • page : Integer

    The page of results you want to retrieve, starting at 1.

  • order : String

    The order you want tags returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

  • direction : String

    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • tag : StringREQUIRED

    A tag id or name. The request returns a paginated list of passes associated with the specified tag.

Responses

  • 200

    A successful response returns a paginated array of passes.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • count : Integer

        The total number of results.

      • pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

      • passes : Object

        Meta information about passes.

        OBJECT PROPERTIES
        • createdAt : String

          The date and time when the item was last updated. Format: date-time

        • id : Integer

          The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

        • installedAt : String

          The date and time when pass was first installed on the device. Format: date-time

        • platform : String

          Wallet platform (iOS or Android).

          Possible values: iOS, Android

        • serialNumber : String

          The serial number of the pass.

        • status : String

          Recent on-device pass status.

          Possible values: installed, uninstalled, not_been_installed

        • templateId : Integer

          The identifier for the template. You can recall the template by ID in other operations.

        • uninstalledAt : String

          The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

        • updatedAt : String

          The date and time when the item was created. Format: date-time

        • url : String

          Pass download URL.

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

Example Response

{
   "ticketId": 123
}

PUT /tag/{tag}/passes

Update all of the passes that have a given tag.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • tag : StringREQUIRED

    The tag associated with the passes you want to update.

Request Body

Provide only the fields you want to update.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • fields : Object

      OBJECT PROPERTIES
      • * : Object

        OBJECT PROPERTIES
        • value : String

          The value you want to change for field.

Responses

  • 200

    A successful request returns a ticketId.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ticketId : Integer

Remove Tag from All Passes

Example Request

DELETE /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
   "count": 38,
   "status": "success",
   "tagId": 2
}

DELETE /tag/{tag}/passes

Remove this tag from all of its passes.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • tag : StringREQUIRED

    The tag you want to remove.

Responses

  • 200

    A successful response returns a count of the affected passes.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • count : Integer

        The number of passes the tag was removed from.

      • status : String

        The operation was successful.

        Possible values: success

      • tagId : Integer

        The ID of the deleted tag.

Tags using external ID

These endpoints support passes using external IDs. Tags are plain-text identifiers for passes. Use tags to identify passes for segmentation purposes, or to target an audience of passes for updates. Tags are limited to 15 per pass.

Get Tags for Pass with external ID

Example Request

GET /v1/pass/id/mypass/tags HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

GET /pass/id/{passExternalId}/tags

Get the tags for a pass with an external ID.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passExternalId : StringREQUIRED

    The external ID of the pass you want to get tags from.

Responses

  • 200

    An array of tags belonging to the pass.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • tags : Array [Object]

        An array of tags associated with the pass.

        ARRAY ITEM
        • Tag Object

          OBJECT PROPERTIES
          • createdAt : String

            The date and time when the item was created. Format: date-time

          • id : Integer

            The ID of the tag, used to reference the tag.

          • name : String

            The name of the tag.

Add Tags to Pass with external ID

Example Request

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

{
    "tags": ["tag-name"]
}

Example Response

{
  "newTags": ["tag-name"],
  "mappings": 1
}

PUT /pass/id/{passExternalId}/tags

Add tags to a pass with an external ID, limited to 15 tags per pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passExternalId : StringREQUIRED

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

Request Body

An array of tags that you want to associate with the pass.

  • Content-Type: application/json

    Add Tags to PassRequest : Object

    An array of tags that you want to add to a pass.

    OBJECT PROPERTIES
    • tags : Array [String]REQUIRED

      An array of strings, each string representing a tag. Max items: 15

Responses

  • 200

    Lists the tags added to the pass.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • mappings : Integer

        The number of tags added.

      • newTags : Array [String]

        A list of tags successfully added to the pass.

List Tags for Pass with external ID

Example Request

GET /v1/pass/template/123/id/mypass/tags HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

Example Response

{
  "tags": [
    {
      "id": 72,
      "createdAt": "2013-07-10T11:38:06Z",
      "name": "tag-2971-4280-479"
    },
    {
      "id": 73,
      "createdAt": "2013-07-10 11:52:20Z",
      "name": "tag-1049-2951-9529"
    },
    {
      "id": 74,
      "createdAt": "2013-07-10 11:59:32Z",
      "name": "tag-385-9612-723"
    },
    {
      "id": 75,
      "createdAt": "2013-07-10 12:00:18Z",
      "name": "tag-5784-6282-8767"
    },
    {
      "id": 76,
      "createdAt": "2013-07-10 12:00:55Z",
      "name": "tag-1050-1982-8211"
    },
    {
      "id": 77,
      "createdAt": "2013-07-10 12:02:09Z",
      "name": "tag-5040-8715-7744"
    }
  ]
}

GET /pass/template/{templateId}/id/{passExternalId}/tags

List tags assigned to the specified pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The template of the pass that you want to get tags for.

  • passExternalId : StringREQUIRED

    The external ID of the pass you want to get tags for.

Responses

  • 200

    An array of tags belonging to the pass.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • tags : Array [Object]

        An array of tags associated with the pass.

        ARRAY ITEM
        • Tag Object

          OBJECT PROPERTIES
          • createdAt : String

            The date and time when the item was created. Format: date-time

          • id : Integer

            The ID of the tag, used to reference the tag.

          • name : String

            The name of the tag.

Update Tags for Pass with external ID

Example Request

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

{
    "tags": ["tag-name"]
}

Example Response

{
  "newTags": ["tag-name"],
  "mappings": 1
}

PUT /pass/template/{templateId}/id/{passExternalId}/tags

Assign or update tags on a pass with an external ID.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The template of the pass that you want to apply tags to.

  • passExternalId : StringREQUIRED

    The external ID of the pass you want to apply tags to.

Request Body

An array of tags that you want to associate with the pass.

  • Content-Type: application/json

    Add Tags to PassRequest : Object

    An array of tags that you want to add to a pass.

    OBJECT PROPERTIES
    • tags : Array [String]REQUIRED

      An array of strings, each string representing a tag. Max items: 15

Responses

  • 200

    Lists the tags added to the pass.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • mappings : Integer

        The number of tags added.

      • newTags : Array [String]

        A list of tags successfully added to the pass.

  • 404

    The pass or template ID does not exist.

Remove Tag from Pass with external ID

Example Request

DELETE /v1/tag/tag-name/pass/id/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

DELETE /tag/{tag}/pass/id/{passExternalId}

Remove a tag from the specified pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • tag : StringREQUIRED

    The tag you want to remove from the pass.

  • passExternalId : StringREQUIRED

    The external ID of the pass you want to remove the tag from.

Responses

  • 200

    A successful response includes the ID of the tag and the ID of the pass it was removed from.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • passId : Integer

        The ID of the pass that the tag was removed from.

      • status : String

        The operation was successful.

        Possible values: success

      • tagId : Integer

        The ID of the tag.

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. Use segments to group and target passes for subsequent updates.

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

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

{
   "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 /segments/{projectId}

List meta information for all segments for a project.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

Responses

  • 200

    A response returns a list of segments for a project.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • segments : Array [Object]

        ARRAY ITEM
        • OBJECT PROPERTIES
          • creation_date : String

            The date and time when the item was created. Format: date-time

          • display_name : String

            The name of the segment.

          • id : String

            The identifier for the segment, used to identify the segment in other operations. Format: uuid

          • modification_date : String

            The date and time when the item was last updated. Format: date-time

Create a 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

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

{
   "ok": true,
   "segmentId": "b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
   "operationId": "dd2f1d32-aca9-4463-91c2-a3420bbcd489"
}

POST /segments/{projectId}

Create a segment for a project.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

Request Body

Contains and, or, or not operators for tags that identify your segment.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • criteria : Segment Selector

      Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.

    • display_name : String

      The name of the segment.

Responses

  • 200

    A response returns a segment ID that you can use to reference the segment in future operations.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ok : Boolean

        If true, the operation completed successfully.

      • operationId : String

        An identifier for the operation. Use this value to reference the operation for troubleshooting purposes.

        Format: uuid

      • segmentId : String

        An identifier for the segment. Use this value to reference the segment in other operations. Format: uuid

Look up a 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

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

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

GET /segments/{projectId}/{segmentId}

Returns the selector criteria for a segment.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

  • segmentId : StringREQUIRED

    The ID of the segment.

Responses

  • 200

    A successful request returns the selection criteria for the segment.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • criteria : Segment Selector

        Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.

      • display_name : String

        The name of the segment.

Update a 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

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

{
 "ok": true,
 "segmentId": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
 "operationId": "f573b3c5-b0ee-4461-a179-2e78aab20400"
}

PUT /segments/{projectId}/{segmentId}

Update selection criteria or the display name for a segment.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

  • segmentId : StringREQUIRED

    The ID of the segment.

Request Body

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • criteria : Segment Selector

      Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.

    • display_name : String

      The name of the segment.

Responses

  • 200

    A response returns a segment ID that you can use to reference the segment in future operations.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ok : Boolean

        If true, the operation completed successfully.

      • operationId : String

        An identifier for the operation. Use this ID to reference the operation for troubleshooting purposes. Format: uuid

      • segmentId : String

        An identifier for the segment that you can use to reference the segment in other operations. Format: uuid

Delete a 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 /segments/{projectId}/{segmentId}

Delete a segment by ID. This operation just deletes the segment criteria; the passes previously selected by this criteria are unchanged.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

  • segmentId : StringREQUIRED

    The ID of the segment.

Responses

  • 204

    A successful delete request returns no content.

Update Passes by Segment

Example Request

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

{
    "fields":{
        "secondary1":{
            "value":"Mega Offer"
        },
        "primary1":{
            "value":"$20 Off"
        }
    }
}

Example Response

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

{
   "ticketId": 123
}

PUT /segments/{projectId}/{segmentId}/passes

Update passes by segment ID and template ID.

query PARAMETERS
  • templateId : String

    The ID for the template. Required since pass updates for segments are done at the template level.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

  • segmentId : StringREQUIRED

    The ID of the segment.

Request Body

Provide only the fields you want to update.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • fields : Object

      OBJECT PROPERTIES
      • * : Object

        OBJECT PROPERTIES
        • value : String

          The value you want to change for field.

Responses

  • 200

    A response returns one or more ticketId values, each referencing the pass update operation.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ticketId : Integer

        A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.

Flights

Create and store flight information for use with boarding passes. When creating boarding passes, you can reference a flight, automatically populating flight information on the pass. By storing and referencing flight information independently of your passes, you can update a single flight, automatically pushing an update to all passes referencing that flight.

Create a flight

Example Request

POST /v1/flights/project/<projectId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "flightNumber": { "value": "815" },
    "airlineCode": { "value": "WN" },
    "airlineName": { "value": "Southwest Airlines" },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "25"
    },
    "boardingTime": { "value": "2018-07-30T08:35:00" },
    "departureTime": { "value": "2018-07-30T09:00:00" },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalTime": { "value": "2018-07-30T11:00:00" },
    "flightStatus": { "value": "scheduled" },
  }
}

Example Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "flightId": "<uaFlightId>",
  "projectId": "<uaProjectId>",
  "createdAt": "2018-07-05T09:12:32Z",
  "updatedAt": "2018-07-05T09:12:32Z",
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "flightNumber": {
      "label": "Flight Number",
      "value": "815"
    },
    "airlineCode": {
      "label": "Airline Code",
      "value": "WN"
    },
    "airlineName": {
      "label": "Airline Name",
      "value": "Southwest Airlines"
    },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "25"
    },
    "boardingTime": {
      "label": "Boarding Time",
      "value": "2018-07-30T08:35:00"
    },
    "departureTime": {
      "label": "Departure Time",
      "value": "2018-07-30T09:00:00"
    },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalGate": {
      "label": "Arrival Gate",
      "value": ""
    },
    "arrivalTime": {
      "label": "Arrival Time",
      "value": "2018-07-30T11:00:00"
    },
    "flightStatus": {
      "label": "Flight Status",
      "value": "scheduled"
    }
  }
}

POST /flights/project/{projectId}

Create flights

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project you want to create the flight in.

Request Body

  • Content-Type: application/json

    Flight Object

    A complete flight request object.

    The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.

Responses

  • 200

    A successful request returns the flightId and flightExternalId (if applicable) values, so you can reference the flight in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Update Flights in a Pass Group

Example Request

PUT /v1/flights/project/12345/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json

{
  "fields": {
    "departureTime": {
      "value": "2018-08-30T10:00:00"
    }
  }
}

Example Response

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

{
  "groupName" : "sfo-pdx-20180730", 
  "flights" : [
    {
      "flightId" : 123
    },
    {
      "flightId" : 456
    }
  ]
}

PUT /flights/project/{projectId}/passGroups/{passGroup}

Update all of the flights in a pass group.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project that the flight belongs to. Use either the Airship-generated project ID or the external ID.

  • passGroup : IntegerREQUIRED

    The pass group that you want to modify.

Request Body

Update fields common to a group of flights.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • fields : Object

      Provide only the keys that you want to update from fields object of an flight Request; any fields that you omit from the payload remain unchanged.

Responses

  • 200

    The update was successful.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • flights : Array [Object]

        Lists the flights updated as a part of this pass group.

        ARRAY ITEM
        • OBJECT PROPERTIES
          • flightId : Integer

            The Airship flight ID for flights updated as a part of this pass group.

      • groupName : String

        The pass group that you updated in this request.

  • 400

    The request was malformed.

  • 404

    The project ID or pass group was not found.

Get a flight

Example Request

GET /v1/flights/project/<projectId>/<flightId> HTTP/1.1
Authorization: Basic <authorization string>

Example Response

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

{
  "flightId": "<uaFlightId>",
  "projectId": "<uaProjectId>",
  "createdAt": "2018-07-05T09:12:32Z",
  "updatedAt": "2018-07-05T09:12:32Z",
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "flightNumber": {
      "label": "Flight Number",
      "value": "815"
    },
    "airlineCode": {
      "label": "Airline Code",
      "value": "WN"
    },
    "airlineName": {
      "label": "Airline Name",
      "value": "Southwest Airlines"
    },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "21"
    },
    "boardingTime": {
      "label": "Boarding Time",
      "value": "2018-07-30T09:20:00"
    },
    "departureTime": {
      "label": "Departure Time",
      "value": "2018-07-30T09:45:00"
    },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalGate": {
      "label": "Arrival Gate",
      "value": ""
    },
    "arrivalTime": {
      "label": "Arrival Time",
      "value": "2018-07-30T11:45:00"
    },
    "flightStatus": {
      "label": "Flight Status",
      "value": "scheduled"
    }
  }
}

GET /flights/project/{projectId}/{flightId}

Returns information for a single flight.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project that the flight belongs to.

  • flightId : IntegerREQUIRED

    The flight you want to get, update, or delete.

Responses

  • 200

    A successful request returns the flightId and flightExternalId (if applicable) values, so you can reference the flight in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Update a flight

Example Request

PUT /v1/flights/project/<projectId>/<flightId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "departureGate": { "value": "21" },
    "boardingTime": { "value": "2018-07-30T09:20:00" },
    "departureTime": { "value": "2018-07-30T09:45:00" },
    "arrivalTime": { "value": "2018-07-30T11:45:00" }
  }
}

Example Response

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

{
  "flightId": "<uaFlightId>",
  "projectId": "<uaProjectId>",
  "createdAt": "2018-07-05T09:12:32Z",
  "updatedAt": "2018-07-05T09:15:32Z",
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "flightNumber": {
      "label": "Flight Number",
      "value": "815"
    },
    "airlineCode": {
      "label": "Airline Code",
      "value": "WN"
    },
    "airlineName": {
      "label": "Airline Name",
      "value": "Southwest Airlines"
    },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "21"
    },
    "boardingTime": {
      "label": "Boarding Time",
      "value": "2018-07-30T09:20:00"
    },
    "departureTime": {
      "label": "Departure Time",
      "value": "2018-07-30T09:45:00"
    },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalGate": {
      "label": "Arrival Gate",
      "value": ""
    },
    "arrivalTime": {
      "label": "Arrival Time",
      "value": "2018-07-30T11:45:00"
    },
    "flightStatus": {
      "label": "Flight Status",
      "value": "scheduled"
    }
  }
}

PUT /flights/project/{projectId}/{flightId}

Update any of the keys provided in the fields object of a Flight Request. Provide only the fields you want to update; any fields that you omit from the payload remain unchanged.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project that the flight belongs to.

  • flightId : IntegerREQUIRED

    The flight you want to get, update, or delete.

Request Body

  • Content-Type: application/json

    Flight Object

    A complete flight request object.

    The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.

Responses

  • 200

    A successful request returns the complete, updated flight object and the flightId and flightExternalId (if applicable) values, so you can reference the updated flight in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Delete a flight

Example Request

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

Example Response

HTTP/1.1 200 OK

DELETE /flights/project/{projectId}/{flightId}

Deletes the specified flight.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project that the flight belongs to.

  • flightId : IntegerREQUIRED

    The flight you want to get, update, or delete.

Responses

  • 200

    The flight was deleted.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ok : Boolean

        If true, the operation completed successfully.

List Pass Groups for a Flight

Example Request

GET /v1/flights/project/<projectId>/<flightId>/passGroups HTTP/1.1
Authorization: Basic <authorization string>

Example Response

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

{
  "flightTicketId" : 1234,
  "passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}

GET /flights/project/{projectId}/{flightId}/passGroups

Returns a list of pass groups associated with a flight.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : IntegerREQUIRED

    The project that the flight belongs to.

  • flightId : IntegerREQUIRED

    The flight you want modify groups for.

Responses

  • 200

    Returns a list of pass groups that a flight is associated with.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • flightId : Integer

        The Airship-generated ID of the flight in the request.

      • passGroups : Array [String]

        An array of the pass groups that the flight belongs to.

  • 400

    Missing fields or malformed input.

  • 404

    The flight or project cannot be found.

Add flight to a pass group

Example Request

POST /v1/flights/project/<projectId>/<flightId>/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json

{
  "passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}

Example Response

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

{
  "flightId" : 1234,
  "passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}

POST /flights/project/{projectId}/{flightId}/passGroups

Add a flight to a pass group. You can target the group to make changes to multiple flights.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : IntegerREQUIRED

    The project that the flight belongs to.

  • flightId : IntegerREQUIRED

    The flight you want modify groups for.

Request Body

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • passGroups : Array [String]

      An array of pass groups that you want to create and add a flight to. If a pass group (string) in the array already exists, it is ignored.

Responses

  • 200

    At least one pass group in the passGroups array was created.

    RESPONSE BODY
    • Content-Type: application/json

      An array of eventId or eventExternalId values representing a group. You can reference the group to make changes to all associated events.

      You can set pass groups when creating an event or when creating an event ticket adaptive link.

      ARRAY ITEM
  • 400

    Missing or malformed input.

  • 404

    The flight or project cannot be found.

Remove Flight from Pass Group

Example Request

DELETE /v1/flights/project/<projectId>/<flightId>/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json

DELETE /flights/project/{projectId}/{flightId}/passGroups/{passGroup}

Removes a flight from a pass group. The group specified in the path will no longer appear in the flight’s passGroups array, nor will you be able to make changes to the flight by targeting the pass group.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : IntegerREQUIRED

    The project that the flight belongs to. Use either the Airship-generated project ID or the external ID.

  • flightId : IntegerREQUIRED

    The flight you want modify groups for. Use either the Airship-generated flight ID or the external ID for the flight.

  • passGroup : StringREQUIRED

    The pass group you want to remove the flight from.

Responses

  • 200

    The flight was successfully removed from the pass group.

  • 400

    The project, flight, or pass group was not found.

Flights with external IDs

These endpoints support flight objects created using external IDs. Create and store flight information for use with boarding passes. When creating boarding passes, you can reference a flight, automatically populating flight information on the pass. By storing and referencing flight information independently of your passes, you can update a single flight, automatically pushing an update to all passes referencing that flight.

Update Flights in a Pass Group

Example Request

PUT /v1/flights/project/id/<projectExternalId>/id/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json

{
  "fields": {
    "departureTime": {
      "value": "2018-08-30T10:00:00"
    }
  }
}

Example Response

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

{
  "groupName" : "sfo-pdx-20180730", 
  "flights" : [
    {
      "flightId" : 123
    },
    {
      "flightId" : 456
    }
  ]
}

PUT /flights/project/id/{projectExternalId}/id/passGroups/{passGroup}

Update fields common to a group of flights. Provide only the keys that you want to update from fields object of an flight Request; any fields that you omit from the payload remain unchanged.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project that the flight belongs to.

  • passGroup : StringREQUIRED

    The pass group that you want to modify.

Request Body

Provide only the field(s) you want to update for all of the flights in the group.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • fields : Object

      Provide only the keys that you want to update from fields object of an flight Request; any fields that you omit from the payload remain unchanged.

Responses

  • 200

    The update was successful.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • flights : Array [Object]

        Lists the flights updated as a part of this pass group.

        ARRAY ITEM
        • OBJECT PROPERTIES
          • flightId : Integer

            The Airship flight ID for flights updated as a part of this pass group.

      • groupName : String

        The pass group that you updated in this request.

  • 400

    The request was malformed.

  • 404

    The project ID or pass group was not found.

Get a flight with external ID

Example Request

GET /v1/flights/project/id/<projectExternalId>/id/<flightExternalId> HTTP/1.1
Authorization: Basic <authorization string>

Example Response

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

{
  "flightId": "<uaFlightId>",
  "flightExternalId": "<flightExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-07-05T09:12:32Z",
  "updatedAt": "2018-07-05T09:12:32Z",
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "flightNumber": {
      "label": "Flight Number",
      "value": "815"
    },
    "airlineCode": {
      "label": "Airline Code",
      "value": "WN"
    },
    "airlineName": {
      "label": "Airline Name",
      "value": "Southwest Airlines"
    },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "21"
    },
    "boardingTime": {
      "label": "Boarding Time",
      "value": "2018-07-30T09:20:00"
    },
    "departureTime": {
      "label": "Departure Time",
      "value": "2018-07-30T09:45:00"
    },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalGate": {
      "label": "Arrival Gate",
      "value": ""
    },
    "arrivalTime": {
      "label": "Arrival Time",
      "value": "2018-07-30T11:45:00"
    },
    "flightStatus": {
      "label": "Flight Status",
      "value": "scheduled"
    }
  }
}

GET /flights/project/id/{projectExternalId}/id/{flightExternalId}

Returns information for a single flight.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project you want to create the flight in.

  • flightExternalId : StringREQUIRED

    The external identifier you want to give to the flight.

Responses

  • 200

    A successful request returns the flightId and flightExternalId (if applicable) values, so you can reference the flight in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Update a flight with external ID

Example Request

PUT /v1/flights/project/id/<projectExternalId>/id/<flightExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "departureGate": { "value": "21" },
    "boardingTime": { "value": "2018-07-30T09:20:00" },
    "departureTime": { "value": "2018-07-30T09:45:00" },
    "arrivalTime": { "value": "2018-07-30T11:45:00" }
  }
}

Example Response

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

{
  "flightId": "<uaFlightId>",
  "flightExternalId": "<flightExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-07-05T09:12:32Z",
  "updatedAt": "2018-07-05T09:15:32Z",
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "flightNumber": {
      "label": "Flight Number",
      "value": "815"
    },
    "airlineCode": {
      "label": "Airline Code",
      "value": "WN"
    },
    "airlineName": {
      "label": "Airline Name",
      "value": "Southwest Airlines"
    },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "21"
    },
    "boardingTime": {
      "label": "Boarding Time",
      "value": "2018-07-30T09:20:00"
    },
    "departureTime": {
      "label": "Departure Time",
      "value": "2018-07-30T09:45:00"
    },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalGate": {
      "label": "Arrival Gate",
      "value": ""
    },
    "arrivalTime": {
      "label": "Arrival Time",
      "value": "2018-07-30T11:45:00"
    },
    "flightStatus": {
      "label": "Flight Status",
      "value": "scheduled"
    }
  }
}

PUT /flights/project/id/{projectExternalId}/id/{flightExternalId}

Update any of the keys provided in the fields object when creating a flight. Provide only the fields you want to update; any fields that you omit from the payload remain unchanged.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project you want to create the flight in.

  • flightExternalId : StringREQUIRED

    The external identifier you want to give to the flight.

Request Body

  • Content-Type: application/json

    Flight Object

    A complete flight request object.

    The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.

Responses

  • 200

    A successful request returns the complete, updated flight object and the flightId and flightExternalId (if applicable) values, so you can reference the updated flight in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Create a flight with external ID

Example Request

POST /v1/flights/project/id/<projectExternalId>/id/<flightExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "flightNumber": { "value": "815" },
    "airlineCode": { "value": "WN" },
    "airlineName": { "value": "Southwest Airlines" },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "25"
    },
    "boardingTime": { "value": "2018-07-30T08:35:00" },
    "departureTime": { "value": "2018-07-30T09:00:00" },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalTime": { "value": "2018-07-30T11:00:00" },
    "flightStatus": { "value": "scheduled" }
  }
}

Example Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "flightId": "<uaFlightId>",
  "flightExternalId": "<flightExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-07-05T09:12:32Z",
  "updatedAt": "2018-07-05T09:12:32Z",
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "flightNumber": {
      "label": "Flight Number",
      "value": "815"
    },
    "airlineCode": {
      "label": "Airline Code",
      "value": "WN"
    },
    "airlineName": {
      "label": "Airline Name",
      "value": "Southwest Airlines"
    },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "25"
    },
    "boardingTime": {
      "label": "Boarding Time",
      "value": "2018-07-30T08:35:00"
    },
    "departureTime": {
      "label": "Departure Time",
      "value": "2018-07-30T09:00:00"
    },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalGate": {
      "label": "Arrival Gate",
      "value": ""
    },
    "arrivalTime": {
      "label": "Arrival Time",
      "value": "2018-07-30T11:00:00"
    },
    "flightStatus": {
      "label": "Flight Status",
      "value": "scheduled"
    }
  }
}

POST /flights/project/id/{projectExternalId}/id/{flightExternalId}

Create flights

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project you want to create the flight in.

  • flightExternalId : StringREQUIRED

    The external identifier you want to give to the flight.

Request Body

  • Content-Type: application/json

    Flight Object

    A complete flight request object.

    The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.

Responses

  • 200

    A successful request returns the flightId and flightExternalId (if applicable) values, so you can reference the flight in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Delete a flight with external ID

Example Request

DELETE /v1/flights/project/id/<projectExternalId>/id/<flightExternalId> HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

Example Response

HTTP/1.1 200 OK

DELETE /flights/project/id/{projectExternalId}/id/{flightExternalId}

Deletes the specified flight.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project you want to create the flight in.

  • flightExternalId : StringREQUIRED

    The external identifier you want to give to the flight.

Responses

  • 200

    The flight was deleted.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ok : Boolean

        If true, the operation completed successfully.

List Pass Groups for a Flight

Example Request

GET /v1/flights/project/id/<projectExternalId>/id/<flightExternalId>/passGroups HTTP/1.1
Authorization: Basic <authorization string>

Example Response

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

{
  "flightTicketId" : 1234,
  "passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}

GET /flights/project/id/{projectExternalId}/id/{flightExternalId}/passGroups

Returns a list of pass groups associated with a flight.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project that the flight belongs to.

  • flightExternalId : StringREQUIRED

    The flight you want modify groups for.

Responses

  • 200

    Returns a list of pass groups that a flight is associated with.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • flightId : Integer

        The Airship-generated ID of the flight in the request.

      • passGroups : Array [String]

        An array of the pass groups that the flight belongs to.

  • 400

    Missing fields or malformed input.

  • 404

    The flight or project cannot be found.

Add flight to a pass group

Example Request

POST /v1/flights/project/id/<projectExternalId>/id/<flightExternalId>/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json

{
  "passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}

Example Response

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

{
  "flightId" : 1234,
  "passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}

POST /flights/project/id/{projectExternalId}/id/{flightExternalId}/passGroups

Add a flight to a pass group. You can target the group to make changes to multiple flights.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project that the flight belongs to.

  • flightExternalId : StringREQUIRED

    The flight you want modify groups for.

Request Body

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • passGroups : Array [String]

      An array of pass groups that you want to add a flight to. If a flight already belongs to a pass group (string) in the array, it is ignored.

Responses

  • 200

    The flight was added to one or more passGroups.

    RESPONSE BODY
    • Content-Type: application/json

      An array of eventId or eventExternalId values representing a group. You can reference the group to make changes to all associated events.

      You can set pass groups when creating an event or when creating an event ticket adaptive link.

      ARRAY ITEM
  • 400

    Missing or malformed input.

  • 404

    The flight or project cannot be found.

Remove Flight from Pass Group

Example Request

DELETE /v1/flights/project/id/<projectExternalId>/id/<flightExternalId>/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json

DELETE /flights/project/id/{projectExternalId}/id/{flightExternalId}/passGroups/{passGroup}

Removes a flight from a pass group. The group specified in the path will no longer appear in the flight’s passGroups array, nor will you be able to make changes to the flight by targeting the pass group.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project that the flight belongs to. Use either the Airship-generated project ID or the external ID.

  • flightExternalId : StringREQUIRED

    The flight you want modify groups for. Use either the Airship-generated flight ID or the external ID for the flight.

  • passGroup : StringREQUIRED

    The pass group you want to remove the flight from.

Responses

  • 200

    The flight was successfully removed from the pass group.

  • 400

    The project, flight, or pass group was not found.

Events

Create and store event information for use with event tickets. When creating event tickets, you can reference an event, automatically populating event information on the pass. By storing and referencing event information independently of your passes, you can update a single event, automatically pushing an update to all passes referencing it.

Create an event

Example Request

POST /v1/events/project/<projectId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

{
  "passGroups": ["giants_2019-09-25"],
  "fields": {
    "eventName": { "value": "LA Dodgers at SF Giants" },
    "venueTitle": { "value": "AT&T Park" },
    "venueAddress": { "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107" },
     "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T08:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T09:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T11:00:00"
    }
  }
}

Example Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "passGroups": ["giants_2019-09-25"],
  "eventId": "<uaEventId>",
  "projectId": "<uaProjectId>",
  "createdAt": "2018-09-24T09:12:32Z",
  "updatedAt": "2018-09-24T09:12:32Z",
  "fields": {
    "eventName": {
      "label": "Event",
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "label": "Venue",
      "value": "AT&T Park"
    },
    "venueAddress": {
      "label": "Address",
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T08:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T09:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T11:00:00"
    }
  }
}

POST /events/project/{projectId}

Create an event.

If your request uses an eventExternalId already associated with an existing event, the call is treated as a PUT, and updates the existing event. As with the PUT method, any fields not contained in the request are unchanged.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project you want to create the event in.

Request Body

  • Content-Type: application/json

    Event Request

    Represents an event scheduled at a specific time and venue.

Responses

  • 201

    The event was successfully created. A successful request returns the eventId and eventExternalId (if applicable) values, so you can reference the event in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Update Events in a Pass Group

Example Request

PUT /v1/events/project/myFavProject/passGroups/giants_2019-09-25 HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

{
  "fields": {
    "venueTitle": {
      "value": "Oracle Park"
    }
  }
}

Example Response

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

{
  "groupName" : "giants_2019-09-25", 
  "events" : [
    {
      "eventTicketId" : 123
    },
    {
      "eventTicketId" : 456
    }
  ]
}

PUT /events/project/{projectId}/passGroups/{passGroup}

Update all of the events in a pass group.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : IntegerREQUIRED

    The project that the event belongs to.

  • passGroup : IntegerREQUIRED

    The pass group that you want to modify.

Request Body

Update fields common to multiple events.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • fields : Object

      Provide only the keys that you want to update from fields object of an Event Request; any fields that you omit from the payload remain unchanged.

Responses

  • 200

    The update was successful.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • events : Array [Object]

        Lists the events updated as a part of this pass group.

        ARRAY ITEM
        • OBJECT PROPERTIES
          • eventTicketId : Integer

            The Airship event ID for events updated as a part of this pass group.

      • groupName : String

        The pass group that you updated in this request.

  • 400

    The request was malformed.

  • 404

    The project ID or pass group was not found.

Get an event

Example Request

GET /v1/events/project/<projectId>/<eventId> HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{
  "eventId": "<uaEventId>",
  "projectId": "<uaProjectId>",
  "createdAt": "2018-09-24T09:12:32Z",
  "updatedAt": "2018-09-24T09:12:32Z",
  "passGroups": ["giants_2019-09-25"],
  "fields": {
    "eventName": {
      "label": "Event",
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "label": "Venue",
      "value": "AT&T Park"
    },
    "venueAddress": {
      "label": "Address",
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T09:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T10:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T12:00:00"
    }
  }
}

GET /events/project/{projectId}/{eventId}

Returns information about a single event.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project that the event belongs to.

  • eventId : IntegerREQUIRED

    The event you want to get, update, or delete.

Responses

  • 200

    A successful request returns the eventId and eventExternalId (if applicable) values, so you can reference the event in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Update an event

Example Request

PUT /v1/events/project/<projectId>/<eventId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

{
  "fields": {
    "doorsOpen": { "value": "2019-09-25T09:35:00" },
    "startTime": { "value": "2019-09-25T10:00:00" },
    "endTime": { "value": "2019-09-25T12:00:00" }
  }
}

Example Response

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

{
  "eventId": "<uaEventId>",
  "projectId": "<uaProjectId>",
  "createdAt": "2018-09-24T09:12:32Z",
  "updatedAt": "2018-09-24T09:12:32Z",
  "passGroups": ["giants_2019-09-25"],
  "fields": {
    "eventName": {
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "value": "AT&T Park"
    },
    "venueAddress": {
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T09:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T10:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T12:00:00"
    }
  }
}

PUT /events/project/{projectId}/{eventId}

Update any of the keys provided in the fields object of an Event Request. Provide only the fields you want to update; any fields that you omit from the payload remain unchanged.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project that the event belongs to.

  • eventId : IntegerREQUIRED

    The event you want to get, update, or delete.

Request Body

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • fields : Object

Responses

  • 200

    A successful request returns the complete, updated event object and the eventId and eventExternalId (if applicable) values, so you can reference the updated event in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Delete an event

Example Request

DELETE /v1/events/project/12345/1 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{}

DELETE /events/project/{projectId}/{eventId}

Deletes the specified event.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project that the event belongs to.

  • eventId : IntegerREQUIRED

    The event you want to get, update, or delete.

Responses

  • 200

    The event was deleted.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ok : Boolean

        If true, the operation completed successfully.

List Pass Groups for an Event

Example Request

GET /v1/events/project/<projectId>/<eventId>/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{
    "eventTicketId": 1234,
    "passGroups": [
        "EVENT_100_LUNCH",
        "FLIGHT_100_DINNER"
    ]
}

GET /events/project/{projectId}/{eventId}/passGroups

Returns a list of pass groups associated with an event.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : IntegerREQUIRED

    The project that the event belongs to. Use the Airship-generated project ID or project’s external ID.

  • eventId : IntegerREQUIRED

    The event you want modify groups for.

Responses

  • 200

    Returns a list of pass groups that an event is associated with.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • eventId : Integer

        The Airship-generated ID of the event in the request.

      • passGroups : Array [String]

        An array of the pass groups that the event belongs to.

  • 400

    Missing fields or malformed input.

  • 404

    The event or project cannot be found.

Add Event to Pass Group

Example Request

POST /v1/events/project/<projectId>/<eventId>/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

{
    "passGroups": [
        "EVENT_100_LUNCH",
        "EVENT_100_DINNER"
    ]
}

Example Response

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

{
    "eventId": 1234,
    "passGroups": [
        "EVENT_100_LUNCH",
        "EVENT_100_DINNER"
    ]
}

POST /events/project/{projectId}/{eventId}/passGroups

Add an event to a pass group. You can target the group to make changes to multiple events.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : IntegerREQUIRED

    The project that the event belongs to. Use the Airship-generated project ID or project’s external ID.

  • eventId : IntegerREQUIRED

    The event you want modify groups for.

Request Body

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • passGroups : Array [String]

      An array of pass groups that you want to create and add an event to. If an event already belongs to a pass group (string) in the array, it is ignored.

Responses

  • 200

    The event was successfully added to one or more passGroups.

    RESPONSE BODY
    • Content-Type: application/json

      An array of pass groups that an event belongs to.

      ARRAY ITEM
  • 400

    Missing or malformed input.

  • 404

    The event or project cannot be found.

Remove Event from Pass Group

Example Request

DELETE /v1/events/project/<projectId>/<eventId>/passGroups/EVENT_100_LUNCH HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

Example Response

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

{}

DELETE /events/project/{projectId}/{eventId}/passGroups/{passGroup}

Removes an event from a pass group. The group specified in the path will no longer appear in the event’s passGroups array, nor will you be able to make changes to the event by targeting the pass group.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : IntegerREQUIRED

    The project that the event belongs to. Use either the Airship-generated project ID or the external ID.

  • eventId : IntegerREQUIRED

    The event you want modify groups for. Use either the Airship-generated event ID or the external ID for the event.

  • passGroup : StringREQUIRED

    The pass group you want to remove the event from.

Responses

  • 200

    The event was removed from the pass group.

  • 400

    The project, event, or pass group was not found.

Events with external IDs

These endpoints support flight objects created using external IDs. Create and store event information for use with event tickets. When creating event tickets, you can reference an event, automatically populating event information on the pass. By storing and referencing event information independently of your passes, you can update a single event, automatically pushing an update to all passes referencing it.

Get an event with external ID

Example Request

GET /v1/events/project/id/<projectExternalId>/id/<eventExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{
  "eventId": "<uaEventId>",
  "eventExternalId": "<eventExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-09-24T09:12:32Z",
  "updatedAt": "2018-09-24T09:12:32Z",
  "passGroups": ["giants_2019-09-25"],
  "fields": {
    "eventName": {
      "label": "Event",
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "label": "Venue",
      "value": "AT&T Park"
    },
    "venueAddress": {
      "label": "Address",
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T09:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T10:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T12:00:00"
    }
  }
}

GET /events/project/id/{projectExternalId}/id/{eventExternalId}

Returns information about a single event.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project you want to create the event in.

  • eventExternalId : StringREQUIRED

    A custom identifier for an event. This is the event you want to create, get, modify, or delete.

Responses

  • 200

    A successful request returns the eventId and eventExternalId (if applicable) values, so you can reference the event in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Update an event with external ID

Example Request

PUT /v1/events/project/id/<projectExternalId>/id/<eventExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

{
  "fields": {
    "doorsOpen": { "value": "2019-09-25T09:35:00" },
    "startTime": { "value": "2019-09-25T10:00:00" },
    "endTime": { "value": "2019-09-25T12:00:00" }
  }
}

Example Response

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

{
  "eventId": "<uaEventId>",
  "eventExternalId": "<eventExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-09-24T09:12:32Z",
  "updatedAt": "2018-09-24T09:12:32Z",
  "passGroups": ["giants_2019-09-25"],
  "fields": {
    "eventName": {
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "value": "AT&T Park"
    },
    "venueAddress": {
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T09:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T10:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T12:00:00"
    }
  }
}

PUT /events/project/id/{projectExternalId}/id/{eventExternalId}

Update any of the keys provided in the fields object of an Event Request. Provide only the fields you want to update; any fields that you omit from the payload remain unchanged.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project you want to create the event in.

  • eventExternalId : StringREQUIRED

    A custom identifier for an event. This is the event you want to create, get, modify, or delete.

Request Body

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • fields : Object

Responses

  • 200

    A successful request returns the complete, updated event object and the eventId and eventExternalId (if applicable) values, so you can reference the updated event in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Create an event with external ID

Example Request

POST /v1/events/project/id/<projectExternalId>/id/<eventExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

{
  "passGroups": ["giants_2019-09-25"],
  "fields": {
    "eventName": {
      "label": "Event",
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "label": "Venue",
      "value": "AT&T Park"
    },
    "venueAddress": {
      "label": "Address",
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T08:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T09:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T11:00:00"
    }
  }
}

POST /events/project/id/{projectExternalId}/id/{eventExternalId}

Create an event using external IDs.

If your request uses an eventExternalId already associated with an existing event, the call is treated as a PUT, and updates the existing event. As with the PUT method, any fields not contained in the request are unchanged.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project you want to create the event in.

  • eventExternalId : StringREQUIRED

    A custom identifier for an event. This is the event you want to create, get, modify, or delete.

Request Body

  • Content-Type: application/json

    Event Request

    Represents an event scheduled at a specific time and venue.

Responses

  • 201

    The event was successfully created. A successful request returns the eventId and eventExternalId (if applicable) values, so you can reference the event in later operations.

    RESPONSE BODY
    • Content-Type: application/json

      An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Delete an event with external ID

Example Request

DELETE /v1/events/project/id/CUSTOM_PROJECT_ID/id/custom_event_id HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{}

DELETE /events/project/id/{projectExternalId}/id/{eventExternalId}

Deletes the specified event.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The external ID of the project you want to create the event in.

  • eventExternalId : StringREQUIRED

    A custom identifier for an event. This is the event you want to create, get, modify, or delete.

Responses

  • 200

    The event was deleted.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ok : Boolean

        If true, the operation completed successfully.

List Pass Groups for an Event

Example Request

GET /v1/events/project/id/<projectExternalId>/id/<eventExternalId>/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{
  "eventTicketId" : 1234,
  "passGroups": [
    "EVENT_100_LUNCH",
    "FLIGHT_100_DINNER"
    ]
}

GET /events/project/id/{projectExternalId}/id/{eventExternalId}/passGroups

Returns a list of pass groups associated with an event.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project that the event belongs to.

  • eventExternalId : StringREQUIRED

    The event you want modify groups for.

Responses

  • 200

    Returns a list of pass groups that an event is associated with.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • eventId : Integer

        The Airship-generated ID of the event in the request.

      • passGroups : Array [String]

        An array of the pass groups that the event belongs to.

  • 400

    Missing fields or malformed input.

  • 404

    The event or project cannot be found.

Add Event to Pass Group

Example Request

POST /v1/events/project/id/<projectExternalId>/id/<eventExternalId>/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

{
    "passGroups": [
        "EVENT_100_LUNCH",
        "EVENT_100_DINNER"
    ]
}

Example Response

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

{
  "eventId" : 1234,
  "passGroups" :["EVENT_100_LUNCH","EVENT_100_DINNER"]
}

POST /events/project/id/{projectExternalId}/id/{eventExternalId}/passGroups

Add an event to a pass group. You can target the group to make changes to multiple events.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project that the event belongs to.

  • eventExternalId : StringREQUIRED

    The event you want modify groups for.

Request Body

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • passGroups : Array [String]

      An array of pass groups that you want to add an event to. If an event already belongs to a pass group (string) in the array, it is ignored.

Responses

  • 200

    The event was successfully added to one or more passGroups.

    RESPONSE BODY
    • Content-Type: application/json

      An array of pass groups that an event belongs to.

      ARRAY ITEM
  • 400

    Missing or malformed input.

  • 404

    The event or project cannot be found.

Delete Pass Groups

Example Request

DELETE /v1/events/project/id/<projectExternalId>/id/<eventExternalId>/passGroups/EVENT_100_LUNCH HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

Example Response

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

{}

DELETE /events/project/id/{projectExternalId}/id/{eventExternalId}/passGroups/{passGroup}

Removes an event from a pass group. The group specified in the path will no longer appear in the event’s passGroups array, nor will you be able to make changes to the event by targeting the pass group.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project that the event belongs to.

  • eventExternalId : StringREQUIRED

    The event you want modify groups for.

  • passGroup : StringREQUIRED

    The pass group you want to remove the event from.

Responses

  • 200

    The event was removed from the pass group.

  • 400

    The project, event, or pass group was not found.

Update Events in a Pass Group

Example Request

PUT /v1/events/project/id/myFavProject/passGroups/giants_2019-09-25 HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json
Api-Revision: 1.2

{
  "fields": {
    "venueTitle": {
      "value": "Oracle Park"
    }
  }
}

Example Response

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

{
  "groupName" : "giants_2019-09-25", 
  "events" : [
    {
      "eventTicketId" : 123
    },
    {
      "eventTicketId" : 456
    }
  ]
}

PUT /events/project/id/{projectExternalId}/passGroups/{passGroup}

Update fields common to multiple events. Provide only the keys that you want to update from fields object of an Event Request; any fields that you omit from the payload remain unchanged.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : StringREQUIRED

    The project that the event belongs to.

  • passGroup : StringREQUIRED

    The pass group that you want to modify.

Request Body

Provide only the field(s) you want to update for all of the events in the group.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • fields : Object

      Provide only the keys that you want to update from fields object of an Event Request; any fields that you omit from the payload remain unchanged.

Responses

  • 200

    The update was successful.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • events : Array [Object]

        Lists the events updated as a part of this pass group.

        ARRAY ITEM
        • OBJECT PROPERTIES
          • eventTicketId : Integer

            The Airship event ID for events updated as a part of this pass group.

      • groupName : String

        The pass group that you updated in this request.

  • 400

    The request was malformed.

  • 404

    The project ID or pass group was not found.

Callbacks

Wallet callbacks provide a pass event notification, e.g., pass install or uninstall, using webhooks.

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
Content-Type: application/json

{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}

GET /project/{projectId}/settings/callback

Return the callback specification for a project.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

Responses

  • 200

    A successful call returns the callback specification.

    RESPONSE BODY
    • Content-Type: application/json

      Used for both requests and responses to /callback endpoints.

      OBJECT PROPERTIES
      • baseUrl : String

        The URL of your webhook/callback server.

      • headers : Object

        Contains headers required by your webhook/callback server, including authorization, content-type, etc.

        By default, Airship appends content-type: application/json and sends a JSON payload.

        OBJECT PROPERTIES
        • * : String

Update callback specification

Example Request

PUT /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json

{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}

Example Response

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

{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}

PUT /project/{projectId}/settings/callback

Update a callback specification. The payload to update a callback is identical to the payload to create a callback.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

Request Body

  • Content-Type: application/json

    Callback Specification : Object

    Used for both requests and responses to /callback endpoints.

    OBJECT PROPERTIES
    • baseUrl : String

      The URL of your webhook/callback server.

    • headers : Object

      Contains headers required by your webhook/callback server, including authorization, content-type, etc.

      By default, Airship appends content-type: application/json and sends a JSON payload.

      OBJECT PROPERTIES
      • * : String

Responses

  • 200

    A successful call returns the callback specification.

    RESPONSE BODY
    • Content-Type: application/json

      Used for both requests and responses to /callback endpoints.

      OBJECT PROPERTIES
      • baseUrl : String

        The URL of your webhook/callback server.

      • headers : Object

        Contains headers required by your webhook/callback server, including authorization, content-type, etc.

        By default, Airship appends content-type: application/json and sends a JSON payload.

        OBJECT PROPERTIES
        • * : String

Create callback specification

Example Request

POST /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json

{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}

Example Response

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

{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}

POST /project/{projectId}/settings/callback

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

Your callback server should expect to receive callbacks at up to three endpoints:

  • {baseUrl}/v1/pass/install — Receives a callback when your audience installs passes.
  • {baseUrl}/v1/pass/uninstall — Receives a callback when your audience uninstalls passes.
  • {baseUrl}/v1/pass/{pass_id}/personalize — Receives a callback with a personalization object when your audience personalizes a Loyalty pass. You must add personalization requirements to Apple templates before users can personalize passes created from them.

See Wallet callbacks for more information.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

Request Body

  • Content-Type: application/json

    Callback Specification : Object

    Used for both requests and responses to /callback endpoints.

    OBJECT PROPERTIES
    • baseUrl : String

      The URL of your webhook/callback server.

    • headers : Object

      Contains headers required by your webhook/callback server, including authorization, content-type, etc.

      By default, Airship appends content-type: application/json and sends a JSON payload.

      OBJECT PROPERTIES
      • * : String

Responses

  • 200

    A successful call returns the callback specification.

    RESPONSE BODY
    • Content-Type: application/json

      Used for both requests and responses to /callback endpoints.

      OBJECT PROPERTIES
      • baseUrl : String

        The URL of your webhook/callback server.

      • headers : Object

        Contains headers required by your webhook/callback server, including authorization, content-type, etc.

        By default, Airship appends content-type: application/json and sends a JSON payload.

        OBJECT PROPERTIES
        • * : String

Delete a 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 /project/{projectId}/settings/callback

Delete a registered callback specification. Because a project only uses a single callback specification, you specify the projectId only.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The ID of the project.

Responses

  • 204

    A successful request returns no content.

Tickets

Return status information about tickets or the server itself. For operations that cannot complete immediately, the system returns a ticketId. You can look up this ticketId to determine the true status of the operation.

Check System Status

Example Request

GET /v1/system/status HTTP/1.1

Example Response

{
    "Hello": "World"
}

GET /system/status

Ensure that you can make a connection to the Wallet API.

Responses

  • 200

    You have successfully established a connection with the server.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • Hello : String

        A “Hello World” response tells you that everything is Ok.

        Possible values: World

Get Ticket Status

Example Request

GET /v1/ticket/123 HTTP/1.1
Authorization: Basic <Base64 key>

Example Response

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

GET /ticket/{ticketId}

Get the status of a ticket. Some operations can’t complete immediately and return a ticketId; use this item to determine the true status of the operation.

Security:

path PARAMETERS
  • ticketId : StringREQUIRED

    The ticket you want to know the status of.

Responses

  • 200

    Returns the status of a ticket.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ID : Integer

        The identifier of the ticket.

      • children : Object

      • createdAt : String

        The date and time when the item was created. Format: date-time

      • status : String

        The status of the ticket.

Statistics

Get pass creation, installation, and uninstallation counts for projects and templates.

Endpoints for /activity report net total activities, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, a response will show two passes installed and one pass removed. Endpoints for /stats will not count repeated actions from the same user.

Project Activity

Example Request

GET /v1/project/12345/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
    "id": 12345,
    "startDate": "2015/08/19",
    "endDate": "2015/08/20",
    "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
            }
        }
    ]
}

GET /project/{projectId}/activity

Returns daily pass activity for a given project ID. You can also add start and end date parameters in the path to return activity between two dates, in the format /template/{templateId}/activity/2018-08-10/2018-10-01. If your request did not specify a date range, the response includes all activity, organized by day, since the template’s createdAt date.

This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : IntegerREQUIRED

    The ID of the project you want to return statistics for.

Responses

  • 200

    Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the projects’s createdAt date.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • details : Array [Object]

        Each object in this array represents pass activity for a single day. Each object represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the object shows two passes installed and one pass removed.

        ARRAY ITEM
        • OBJECT PROPERTIES
          • activity : Object

            Represents activity for a template or project.

            OBJECT PROPERTIES
            • created : Integer

              The number of passes created.

            • installed : Integer

              The number of passes that were installed.

            • uninstalled : Integer

              The number of passes that were uninstalled.

          • date : String

            The date for a specific activity instance in wallet statistics. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • endDate : String

        The end date for a statistics report. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • id : Integer

        The ID of the project specified in the path.

      • startDate : String

        The start date for a statistics report. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • summary : Object

        Represents activity for a template or project.

        OBJECT PROPERTIES
        • created : Integer

          The number of passes created.

        • installed : Integer

          The number of passes that were installed.

        • uninstalled : Integer

          The number of passes that were uninstalled.

Project Statistics

Example Request

GET /v1/project/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
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 /project/{projectId}/stats

Returns statistics for a given project ID. This endpoint does not count repeated actions by the same user.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : IntegerREQUIRED

    The ID of the project you want to return statistics for.

Responses

  • 200

    Returns a summary of pass statistics for every template in the project.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • id : Integer

        The identifier for the project.

      • installed : Integer

        The total number of passes from this project that are installed.

      • lastUpdated : String

        The date and time when the item was last updated. Format: date-time

      • templates : Array [Object]

        Contains statistics for each template belonging to the project.

        ARRAY ITEM
        • Each object in the array represents a template.

          OBJECT PROPERTIES
          • id : Integer

            The identifier for a specific template.

          • installed : Integer

            The total number of passes from this template that are installed.

          • lastUpdated : String

            The date and time when the item was last updated. Format: date-time

          • total : Integer

            The total number of passes created from the template.

          • uninstalled : Integer

            The total number of passes created from this template that are uninstalled.

          • vendor : String

            The device vendor the template is designed for, Apple or Google.

            Possible values: Apple, Google

      • total : Integer

        The total number of passes created in the project.

      • uninstalled : Integer

        The total number of passes created from this project that are uninstalled.

Tag Statistics

Example Request

GET /v1/tag/my_tag/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
  "total": 21,
  "installed": 11,
  "uninstalled": 0,
  "not_been_installed": 0,
  "lastUpdated": "2023-06-14T12:45:37.000Z"
}              

GET /tag/{tag}/stats

Returns statistics for a given tag. Tags are typically used for segmentation but can also be useful for reporting. This endpoint does not count repeated actions by the same user.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • tag : StringREQUIRED

    The tag you want to return statistics for.

Responses

  • 200

    Returns an object containing usage information about a tag.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • installed : Integer

        The number of installed passes with the tag.

      • lastUpdated : String

        The date and time when the statistics were generated. Format: date-time

      • not_been_installed : Integer

        The number of passes created but not installed.

      • total : Integer

        A count of the total number of passes created with the tag.

      • uninstalled : Integer

        The number of uninstalled passes with the tag.

Template Activity

Example Request

GET /v1/template/1234/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
    "id": 1234,
    "vendor": "Apple",
    "startDate": "2015/08/19",
    "endDate": "2015/08/20",
    "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
            }
        }
    ]
}

GET /template/{templateId}/activity

Returns daily activity of passes created, installed, and uninstalled for a template, specified by template ID. You can also add start and end date parameters in the path to return activity between two dates, in the format /template/id/{externalId}/activity/2018-08-10/2018-10-01. If your request did not specify a date range, the response includes all activity, organized by day, since the template’s createdAt date.

This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : IntegerREQUIRED

    The ID of the template you want to return statistics for.

Responses

  • 200

    Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the template’s createdAt date.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • details : Array [Object]

        Each object in this array represents pass activity for a single day.

        ARRAY ITEM
        • OBJECT PROPERTIES
          • activity : Object

            Represents activity for a template or project.

            OBJECT PROPERTIES
            • created : Integer

              The number of passes created.

            • installed : Integer

              The number of passes that were installed.

            • uninstalled : Integer

              The number of passes that were uninstalled.

          • date : String

            The date for a specific activity instance in wallet statistics. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • endDate : String

        The end date for a statistics report. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • id : Integer

        The ID of the template specified in the path.

      • startDate : String

        The start date for a statistics report. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • summary : Object

        Represents activity for a template or project.

        OBJECT PROPERTIES
        • created : Integer

          The number of passes created.

        • installed : Integer

          The number of passes that were installed.

        • uninstalled : Integer

          The number of passes that were uninstalled.

      • vendor : String

        The device vendor the template is designed for, Apple or Google.

        Possible values: Apple, Google

Template Statistics

Example Request

GET /v1/template/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
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 /template/{templateId}/stats

Returns statistics for a given template by ID, including the total number of passes installed and uninstalled.

This endpoint does not count repeated actions by the same user.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : IntegerREQUIRED

    The ID of the template you want to return statistics for.

Responses

  • 200

    Returns an object containing usage information about a template.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • id : Integer

        The template specified in the request.

      • installed : Integer

        The number of installed passes based on this template.

      • lastUpdated : String

        The date and time when the template was last updated. Format: date-time

      • total : Integer

        A count of the total number of passes created from the template.

      • uninstalled : Integer

        The number of uninstalled passes based on this template.

      • vendor : String

        The device vendor the template is designed for, Apple or Google.

        Possible values: Apple, Google

Statistics with external IDs

These endpoints gather statistics from objects with external IDs. You can get pass creation, installation, and uninstallation counts for projects and templates.

Endpoints for /activity report net total activities, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, a response will show two passes installed and one pass removed. Endpoints for /stats will not count repeated actions from the same user.

Pass Statistics with external ID

Example Request

GET /v1/pass/id/my_pass/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
  "total": 1,
  "installed": 1,
  "uninstalled": 0,
  "templates": [
    {
      "id": 5350,
      "installed": 1,
      "uninstalled": 0
    }
  ]
}

GET /pass/id/{externalId}/stats

Returns statistics for a pass with an external ID, including the total number of installs and uninstalls. The response payload lists the internal Wallet ID for the template rather than the external ID.

This endpoint does not count repeated actions by the same user.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : IntegerREQUIRED

    The external ID of the pass you want to return statistics for.

Responses

  • 200

    Returns a summary of statistics for the pass.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • installed : Integer

        The number of installed passes with this external ID.

      • templates : Array [Object]

        The individual pass statistics for each template used to create passes with this external ID. Each object in the array represents a template.

        ARRAY ITEM
        • OBJECT PROPERTIES
          • id : Integer

            The template used to create passes with this external ID.

          • installed : Integer

            The number of installed passes based on this template.

          • uninstalled : Integer

            The number of uninstalled passes based on this template.

      • total : Integer

        A count of the total number of passes with this external ID.

      • uninstalled : Integer

        The number of uninstalled passes with this external ID.

Project Activity with external ID

Example Request

GET /v1/project/id/myExternalProject/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
    "id": 12345,
    "startDate": "2015/08/19",
    "endDate": "2015/08/20",
    "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
            }
        }
    ]
}

GET /project/id/{externalId}/activity

Returns daily pass activity for a project by external ID. You can also add start and end date parameters in the path to return activity between two dates, in the format /template/id/{externalId}/activity/2018-08-10/2018-10-01. If your request did not specify a date range, the response includes all activity, organized by day, since the template’s createdAt date.

This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : IntegerREQUIRED

    The external ID of the project you want to return activity for.

Responses

  • 200

    Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the projects’s createdAt date.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • details : Array [Object]

        Each object in this array represents pass activity for a single day. Each object represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the object shows two passes installed and one pass removed.

        ARRAY ITEM
        • OBJECT PROPERTIES
          • activity : Object

            Represents activity for a template or project.

            OBJECT PROPERTIES
            • created : Integer

              The number of passes created.

            • installed : Integer

              The number of passes that were installed.

            • uninstalled : Integer

              The number of passes that were uninstalled.

          • date : String

            The date for a specific activity instance in wallet statistics. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • endDate : String

        The end date for a statistics report. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • id : Integer

        The ID of the project specified in the path.

      • startDate : String

        The start date for a statistics report. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • summary : Object

        Represents activity for a template or project.

        OBJECT PROPERTIES
        • created : Integer

          The number of passes created.

        • installed : Integer

          The number of passes that were installed.

        • uninstalled : Integer

          The number of passes that were uninstalled.

Project Statistics with external ID

Example Request

GET /v1/project/id/ext_54321/stats HTTP/1.1
Authorization: Basic <Base64 key>
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 /project/id/{externalId}/stats

Returns statistics for a given project with an external ID. The response payload lists the internal Wallet ID for the template rather than the external ID.

This endpoint does not count repeated actions by the same user.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : IntegerREQUIRED

    The external ID of the project you want to return statistics for.

Responses

  • 200

    Returns a summary of pass statistics for every template in the project.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • id : Integer

        The identifier for the project.

      • installed : Integer

        The total number of passes from this project that are installed.

      • lastUpdated : String

        The date and time when the item was last updated. Format: date-time

      • templates : Array [Object]

        Contains statistics for each template belonging to the project.

        ARRAY ITEM
        • Each object in the array represents a template.

          OBJECT PROPERTIES
          • id : Integer

            The identifier for a specific template.

          • installed : Integer

            The total number of passes from this template that are installed.

          • lastUpdated : String

            The date and time when the item was last updated. Format: date-time

          • total : Integer

            The total number of passes created from the template.

          • uninstalled : Integer

            The total number of passes created from this template that are uninstalled.

          • vendor : String

            The device vendor the template is designed for, Apple or Google.

            Possible values: Apple, Google

      • total : Integer

        The total number of passes created in the project.

      • uninstalled : Integer

        The total number of passes created from this project that are uninstalled.

Template Activity with external ID

Example Request

GET /v1/template/id/myExternalId/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
    "id": 1234,
    "vendor": "Apple",
    "startDate": "2015/08/19",
    "endDate": "2015/08/20",
    "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
            }
        }
    ]
}

GET /template/id/{externalId}/activity

Returns daily activity of passes created, installed, and uninstalled for a template, specified by external ID. You can also add start and end date parameters in the path to return activity between two dates, in the format /template/id/{externalId}/activity/2018-08-10/2018-10-01. If your request did not specify a date range, the response includes all activity, organized by day, since the template’s createdAt date.

This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : IntegerREQUIRED

    The external ID of the template you want to return statistics for.

Responses

  • 200

    Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the template’s createdAt date.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • details : Array [Object]

        Each object in this array represents pass activity for a single day.

        ARRAY ITEM
        • OBJECT PROPERTIES
          • activity : Object

            Represents activity for a template or project.

            OBJECT PROPERTIES
            • created : Integer

              The number of passes created.

            • installed : Integer

              The number of passes that were installed.

            • uninstalled : Integer

              The number of passes that were uninstalled.

          • date : String

            The date for a specific activity instance in wallet statistics. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • endDate : String

        The end date for a statistics report. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • id : Integer

        The ID of the template specified in the path.

      • startDate : String

        The start date for a statistics report. Format: date Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01]))

      • summary : Object

        Represents activity for a template or project.

        OBJECT PROPERTIES
        • created : Integer

          The number of passes created.

        • installed : Integer

          The number of passes that were installed.

        • uninstalled : Integer

          The number of passes that were uninstalled.

      • vendor : String

        The device vendor the template is designed for, Apple or Google.

        Possible values: Apple, Google

Template Statistics with external ID

Example Request

GET /v1/template/id/ext_54321/stats HTTP/1.1
Authorization: Basic <Base64 key>
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 /template/id/{externalId}/stats

Returns statistics for a given template by external ID, including the total number of passes installed and uninstalled. The response payload lists the internal Wallet ID for the template rather than the external ID.

This endpoint does not count repeated actions by the same user.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • externalId : IntegerREQUIRED

    The ID of the template you want to return statistics for.

Responses

  • 200

    Returns an object containing usage information about a template.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • id : Integer

        The template specified in the request.

      • installed : Integer

        The number of installed passes based on this template.

      • lastUpdated : String

        The date and time when the template was last updated. Format: date-time

      • total : Integer

        A count of the total number of passes created from the template.

      • uninstalled : Integer

        The number of uninstalled passes based on this template.

      • vendor : String

        The device vendor the template is designed for, Apple or Google.

        Possible values: Apple, Google

Certificates

Get certificates

Example Request

GET /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Content-Type: application/json; charset=utf-8

Example Response

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

{
  "certificates": [
    {
    "id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
    "vendor": "Apple",
    "baseName": "pass.com.company.sample.alpha",
    "teamIdentifier": "PGJV57GD94",
    "nfcSupport": true,
    "enabled": true,
    "default": false,
    "createdAt": "2022-04-05T03:22:47.000Z",
    "updatedAt": "2022-04-05T03:22:47.000Z",
    "validityEnd": "2022-12-03T04:45:52.000Z",
    "validityStart": "2021-11-03T03:45:53.000Z",
    "expired": true
    }
  ]                
}

Example Response

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

{
    "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": "pass.com.myName.test",
            "name": "editable name",
            "comment": "something about this cert",
            "teamIdentifier": "9M8MY376H5",
            "nfcSupport": false,
            "enabled": false,
            "createdAt": "2018-05-26T23:23:21Z",
            "updatedAt": "2019-05-26T22:23:21Z",
            "expired": false,
            "validityStart": "2018-05-26T23:45:00Z",
            "validityEnd": "2019-05-26T23:45:00Z",
            "templates": [
                {"id": 123,"name": "templateName1"},
                {"id": 221,"name": "templateName2"}
            ]
        },
        {
            "id": "12adce15-5c52-479d-8620-54c21cd851aa",
            "vendor": "Apple",
            "baseName", "pass.wallet.myName.anotherTest",
            "name": "editable name1",
            "comment": "a plain text description of this cert",
            "teamIdentifier": "OGKV57GD95",
            "nfcSupport": true,
            "enabled": false,
            "default": false,
            "createdAt": "2018-04-26T23:23:21Z",
            "updatedAt": "2019-04-27T17:22:00Z",
            "expired": false,
            "validityStart": "2018-05-26T23:45:00Z",
            "validityEnd": "2019-05-26T23:45:00Z",
            "templates": [
                {"id": 123, "name": "templateName1"},
                {"id": 221, "name": "templateName2"}
            ]
        }
    ]
}

GET /certificates

Returns a list of certificates, including an array of templates that use the certificate.

query PARAMETERS
  • vendor : String

    The vendor of certificate you want to return. Supports Apple only.

    Possible values: Apple

  • enabled : Boolean

    Indicates whether or not the certificate is enabled.

  • order : String

    Indicates the field to order results by.

  • page : Integer

    Indicates the page of results to return.

  • pageSize : Integer

    Indicates the number of results per page.

  • direction : String

    Indicates the direction in which to return results.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

  • Content-Type : StringREQUIRED

    Possible values: application/json; charset=utf-8

Responses

  • 200

    Returns an array of certificates.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • certificates : Array [Certificate Object]

      • count : Integer

        The number of results on the current page.

      • nextPage : String

        The url for the next page of results. Format: url

      • pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

Add new certificate

Example Request

POST /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

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

Example Response

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

POST /certificates

Adds a new Apple Wallet certificate to the Wallet system. If the specified certificate exists in our system, and the baseName and teamIdentifier match the existing certificate, we will renew/update the existing certificate.

When adding a certificate, you must paste the contents of your p12 certificate into the certificate field in the request payload. You can get the contents of your p12 file with the two following commands:

  • openssl base64 -in wallet-prod.p12 -out wallet-prod.pem
  • cat wallet-prod.pem | tr -d "\n\r" | less

The response contains the ID of your new certificate. You will use the ID to perform subsequent actions (GET, PUT, or DELETE) against this certificate. The response will also contain other information gathered from the certificate. You can find information about these additional fields under Get Certificate.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Request Body

Responses

  • 201

    Returns the created certificate and new read only fields.

    RESPONSE BODY
    • Content-Type: application/json

Get a certificate

Example Request

GET /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

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

{
  "id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
  "vendor": "Apple",
  "baseName": "pass.com.company.sample.alpha",
  "teamIdentifier": "PGJV57GD94",
  "nfcSupport": true,
  "enabled": true,
  "default": false,
  "createdAt": "2022-04-05T03:22:47.000Z",
  "updatedAt": "2022-04-05T03:22:47.000Z",
  "validityStart": "2021-11-03T03:45:53.000Z",
  "validityEnd": "2022-12-03T04:45:52.000Z",
  "expired": true
}

GET /certificates/{id}

Returns information about a certificate, including an array of templates that use the certificate.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • id : StringREQUIRED

    The ID of the certificate you want to perform operations against.

Responses

  • 200

    Returns information about the certificate specified in the request

    RESPONSE BODY
    • Content-Type: application/json

Update a certificate

Example Request

PUT /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2

{
  "certificate": "<Certificate PEM BASE94 content goes here>"
}

Example Response

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

{
  "id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
  "vendor": "Apple",
  "baseName": "pass.com.urbanairship.sample.alpha",
  "teamIdentifier": "PGJV57GD94",
  "nfcSupport": true,
  "enabled": true,
  "createdAt": "2022-04-05T03:22:47.000Z",
  "updatedAt": "2024-02-06T19:01:37.415Z",
  "validityStart": "2022-12-02T22:39:50.000Z",
  "validityEnd": "2024-01-01T22:39:49.000Z",
  "expired": true
}

PUT /certificates/{id}

Updates a certificate. Note the following behaviors:

  • 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 null values.
  • 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.
  • A single certificate must be set as the default. You cannot set the current default certificate to "default": false.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • id : StringREQUIRED

    The ID of the certificate you want to perform operations against.

Request Body

Responses

  • 200

    Returns the created certificate and new read only fields.

    RESPONSE BODY
    • Content-Type: application/json

Remove a certificate

Example Request

DELETE /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2

Example Response

HTTP/1.1 204 No Content

DELETE /certificates/{id}

Removes a certificate from the system.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • id : StringREQUIRED

    The ID of the certificate you want to perform operations against.

Responses

  • 204

    A successful request returns no content.

Event Passes

Event passes

Example Request

GET /v1/events/project/{projectId}/{eventId}/passes HTTP/1.1
Authorization: Basic <authorization string>

Example Response

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

{
          "passes": [{
              "id": 616,
              "templateId": 1000057,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/616/download",
              "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da0b8",
              "createdAt": "2023-04-19T06:17:01.000Z",
              "updatedAt": "2023-04-19T06:17:01.000Z",
              "status": "installed",
              "installedAt": "2023-04-19T06:17:02.000Z",
              "platform": "android"
            },
            {
              "id": 610,
              "templateId": 1000083,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/610/download",
              "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e216",
              "createdAt": "2023-04-05T17:55:23.000Z",
              "updatedAt": "2023-04-05T17:55:23.000Z",
              "status": "installed",
              "installedAt": "2023-04-05T17:55:23.000Z",
              "platform": "android"
            }
          ],
          "pagination": {
            "order": "id",
            "direction": "desc",
            "page": 1,
            "start": 0,
            "pageSize": 2
          }
}

GET /events/project/{projectId}/{eventId}/passes

List passes for an event.

Security:

query PARAMETERS
  • status : String

    Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • pageSize : Integer

    The number of passes per page. Defaults to 10.

  • page : Integer

    The page of results you want to retrieve, starting at 1.

  • order : String

    The order you want passes returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

  • direction : String

    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project that the event belongs to.

  • eventId : IntegerREQUIRED

    The event you want to get passes for.

Responses

  • 200

    A successful request returns a paged list of passes for a particular event.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • count : Integer

        The total number of passes associated with a event

      • pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

      • passes : Array [Object]

        The metadata for passes associated with the event. Each object in the array represents a pass.

        ARRAY ITEM
        • Pass Metadata

          Meta information about passes.

          OBJECT PROPERTIES
          • createdAt : String

            The date and time when the item was last updated. Format: date-time

          • id : Integer

            The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

          • installedAt : String

            The date and time when pass was first installed on the device. Format: date-time

          • platform : String

            Wallet platform (iOS or Android).

            Possible values: iOS, Android

          • serialNumber : String

            The serial number of the pass.

          • status : String

            Recent on-device pass status.

            Possible values: installed, uninstalled, not_been_installed

          • templateId : Integer

            The identifier for the template. You can recall the template by ID in other operations.

          • uninstalledAt : String

            The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

          • updatedAt : String

            The date and time when the item was created. Format: date-time

          • url : String

            Pass download URL.

  • 404

    The event ID does not exist.

Flight Passes

Flight passes

Example Request

GET /v1/flights/project/{projectId}/{flightId}/passes HTTP/1.1
Authorization: Basic <authorization string>

Example Response

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

{
          "passes": [{
              "id": 600,
              "templateId": 100005,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/600/download",
              "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da023",
              "createdAt": "2023-04-19T06:17:01.000Z",
              "updatedAt": "2023-04-19T06:17:01.000Z",
              "status": "installed",
              "installedAt": "2023-04-19T06:19:02.000Z",
              "platform": "android"
            },
            {
              "id": 601,
              "templateId": 100008,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/601/download",
              "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e212",
              "createdAt": "2023-05-05T17:55:23.000Z",
              "updatedAt": "2023-05-06T17:55:23.000Z",
              "status": "installed",
              "installedAt": "2023-04-05T19:55:23.000Z",
              "platform": "android"
            }
          ],
          "pagination": {
            "order": "id",
            "direction": "desc",
            "page": 1,
            "start": 0,
            "pageSize": 2
          }
}

GET /flights/project/{projectId}/{flightId}/passes

List passes for a flight.

Security:

query PARAMETERS
  • status : String

    Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • pageSize : Integer

    The number of passes per page. Defaults to 10.

  • page : Integer

    The page of results you want to retrieve, starting at 1.

  • order : String

    The order you want passes returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

  • direction : String

    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project that the flight belongs to.

  • flightId : IntegerREQUIRED

    The flight you want to get passes for.

Responses

  • 200

    A successful request returns a paged list of passes for a particular flight.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • count : Integer

        The total number of passes associated with a flight

      • pagination : Object

        Contains information about pagination, according to your query parameters.

        OBJECT PROPERTIES
        • direction : String

          The direction of results, ascending, or descending.

          Possible values: ASC, DESC

        • order : String

          The key in the result set that you want to order results by. Defaults to id.

        • page : Integer

          The page you are on. Multiply by the page size to determine the result set on the page.

        • pageSize : Integer

          The number of results per page.

        • start : Integer

          The first result on the page; results begin with 0.

      • passes : Array [Object]

        The metadata for passes associated with the flight. Each object in the array represents a pass.

        ARRAY ITEM
        • Pass Metadata

          Meta information about passes.

          OBJECT PROPERTIES
          • createdAt : String

            The date and time when the item was last updated. Format: date-time

          • id : Integer

            The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

          • installedAt : String

            The date and time when pass was first installed on the device. Format: date-time

          • platform : String

            Wallet platform (iOS or Android).

            Possible values: iOS, Android

          • serialNumber : String

            The serial number of the pass.

          • status : String

            Recent on-device pass status.

            Possible values: installed, uninstalled, not_been_installed

          • templateId : Integer

            The identifier for the template. You can recall the template by ID in other operations.

          • uninstalledAt : String

            The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format: date-time

          • updatedAt : String

            The date and time when the item was created. Format: date-time

          • url : String

            Pass download URL.

  • 404

    The flight ID does not exist.

Apple Passes Only

View Apple Wallet JSON with external ID

Example Request

GET /v1/pass/id/123/viewJSONPass HTTP/1.1
Authorization: Basic <Base64 key>
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 Airship Reach",
            "value": "Find out more and create your own passes at https://wallet.urbanairship.com\n\nAirship, Inc.,1417 NW Everett St., Portland, OR 97209 800.720.2098 support@urbanairship.com"
         }
      ],
      "primaryFields":[
         {
            "key": "Program Name",
            "label": "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": "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 /pass/id/{passExternalId}/viewJSONPass

View the JSON of an Apple Wallet Pass. The Airship request payload is different from the JSON payload contained in an Apple Wallet pass. You can use this endpoint to view the JSON payload as passed to Apple Wallet.

See Apple’s developer documentation for information about Apple Wallet payloads.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passExternalId : StringREQUIRED

    The custom identifier of the pass you want to return Apple Wallet JSON for.

Responses

  • 200

    Returns JSON as passed to Apple Wallet.

    RESPONSE BODY
    • Content-Type: application/json

List Beacons on Pass (external ID)

Example Request

GET /v1/pass/template/123/id/mypass/beacons HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
   "beacons":[
      {
         "uuid": "55502220-A123-A88A-F321-555A444B333C",
         "relevantText": "You are near the Ship",
         "major": 2,
         "minor": 346
      }
   ]
}

GET /pass/template/{templateId}/id/{passExternalId}/beacons

Lists location beacons assigned to the specified Apple Wallet pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The template of the Apple Wallet pass that you want to get beacons from.

  • passExternalId : StringREQUIRED

    The external ID of the Apple Wallet pass you want to get beacons from.

Responses

  • 200

    An array of beacons belonging to the pass.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • beacons : Array [Beacon Object (iOS Only)]

        An array of objects, each representing a beacon associated with the Apple Wallet pass.

  • 404

    The pass or template ID does not exist.

Add or Update Beacons for Pass (external ID)

Example Request

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

 {
    "beacons":[
       {
          "uuid": "55502220-A123-A88A-F321-555A444B333C",
          "relevantText": "You are near the Ship",
          "major": 2,
          "minor": 346
       }
    ]
 }

Example Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
   "ticketId": 7
}

PUT /pass/template/{templateId}/id/{passExternalId}/beacons

Add or replace beacons on a pass with an external ID.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The template of the Apple Wallet pass that you want to apply beacons to.

  • passExternalId : StringREQUIRED

    The external ID of the Apple Wallet pass you want to apply beacons to.

Request Body

An array of beacons that you want to associate with the pass.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • beacons : Array [Beacon Object (iOS Only)]

      An array of objects, each representing a beacon you want to add to an Apple Wallet pass.

Responses

  • 201

    A successful call results in a ticket to apply beacons to the pass.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ticketId : Integer

        A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.

  • 404

    The pass or template ID does not exist.

Download Apple Wallet .pkpass with external ID

Example Request

GET /v1/pass/template/123/id/mypass/download HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2 

GET /pass/template/{templateId}/id/{passExternalId}/download

Download the contents of an Apple Wallet .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes.

See Apple’s developer documentation for information about .pkpass files and contents.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The template used to create the pass.

  • passExternalId : StringREQUIRED

    The external ID of the pass you want to download.

Responses

  • 200

    Returns the .pkpass file as a .zip extension.

  • 404

    The pass or template ID does not exist.

Download Apple Wallet .pkpass

Example Request

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

GET /pass/{pass_id}/download

Download the contents of an Apple Wallet .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes.

See Apple’s developer documentation for information about .pkpass files and contents.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • pass_id : StringREQUIRED

    The id of the pass you want to download.

Responses

  • 200

    Returns the .pkpass file as a .zip extension.

View Apple Wallet JSON

Example Request

GET /v1/pass/123/viewJSONPass HTTP/1.1
Authorization: Basic <Base64 key>
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 Airship Reach",
            "value": "Find out more and create your own passes at https://wallet.urbanairship.com\n\nAirship, Inc.,1417 NW Everett St., Portland, OR 97209 800.720.2098 support@urbanairship.com"
         }
      ],
      "primaryFields":[
         {
            "key": "Program Name",
            "label": "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": "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 /pass/{pass_id}/viewJSONPass

Returns the JSON of an Apple Wallet pass. The Airship request payload is translated when sent to Apple. You can use this endpoint to view the JSON payload as passed to Apple Wallet for debugging purposes.

See Apple’s developer documentation for information about Apple Wallet payloads.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • pass_id : StringREQUIRED

    The id of the pass you want to return Apple Wallet JSON for.

Responses

  • 200

    A successful request returns Apple JSON

    RESPONSE BODY
    • Content-Type: application/json

Google Passes Only

Get Messages for Google Pass (external ID)

Example Request

GET /v1/pass/template/123/id/mypass/message HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

{
   "messages": [
      {
         "header": "expires",
         "body": "wallet object expiring soon",
         "createdAt": "2019-03-05T23:11:29.000Z",
         "updatedAt": "2019-03-05T23:11:29.000Z",
         "messageType": "expirationNotification"
      }
   ]
}

GET /pass/template/{templateId}/id/{passExternalId}/message

Returns an array of messages associated with the specified pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The template of the Google Pass that you want to get messages from.

  • passExternalId : StringREQUIRED

    The external ID of the Google Pass you want to get messages from.

Responses

  • 200

    A successful response returns details for the added messages.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • messages : Array [Object]

        An array of messages associated with the pass.

        ARRAY ITEM
        • Google Wallet Message Response

          Information about messages associated with specified Google Wallet passes.

          OBJECT PROPERTIES
          • body : String

            The body of the message.

          • createdAt : String

            The date and time when the item was created. Format: date-time

          • header : String

            The header for the message.

          • messageType : String

            The type of message.

            Possible values: expirationNotification, text

          • updatedAt : String

            The date and time when the item was last updated. Format: date-time

  • 404

    The pass or template ID does not exist.

Add Message to Google Pass (external ID)

Example Request

POST /v1/pass/template/123/id/mypass/message HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
   "body":"wallet object expires soon",
   "header":"expires",
   "startTime": "2018-06-03T21:10:00.000Z",
   "endTime": "2018-06-05T21:50:00.000Z",
   "messageType":"expirationNotification"
}

Example Response

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

{
   "header": "expires",
   "body": "wallet object expires soon",
   "startTime": "2018-06-03T21:10:00.000Z",
   "endTime": "2018-06-05T21:50:00.000Z",
   "createdAt": "2021-08-18T23:25:05.075Z",
   "updatedAt": "2021-08-18T23:25:05.075Z",
   "messageType": "expirationNotification"
}

POST /pass/template/{templateId}/id/{passExternalId}/message

Add messages to Google Wallet passes.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • templateId : StringREQUIRED

    The template of the Google Pass that you want to apply messages to.

  • passExternalId : StringREQUIRED

    The external ID of the Google Pass you want to apply messages to.

Request Body

A valid request contains one message for the pass.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • body : String

      The message body text.

    • endTime : Object

      The date-time when the notification will end. If you do not set an end time, the notification displays indefinitely.

      OBJECT PROPERTIES
      • date : String

        Format: date-time

    • header : String

      The header text for the message

    • messageType : String

      Use expirationNotification to warn users of expiring messages, and text for all other notifications. expirationNotification is based on the start value in the displayInterval; the maximum display interval is 30 days from now. If the expiration start date is more than 30 days from now, the message will not appear until the 30-day mark.

      Possible values: expirationNotification, text

    • startTime : Object

      The date-time when the notification will begin appearing to users.

      OBJECT PROPERTIES
      • date : String

        Format: date-time

Responses

  • 200

    A successful response returns details for the added message.

    RESPONSE BODY
    • Content-Type: application/json

      Information about messages associated with specified Google Wallet passes.

      OBJECT PROPERTIES
      • body : String

        The body of the message.

      • createdAt : String

        The date and time when the item was created. Format: date-time

      • header : String

        The header for the message.

      • messageType : String

        The type of message.

        Possible values: expirationNotification, text

      • updatedAt : String

        The date and time when the item was last updated. Format: date-time

  • 404

    The pass or template ID does not exist.

Get Messages for Google Pass

Example Request

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

Example Response

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

{
   "messages": [
      {
         "header": "expires",
         "body": "wallet object expiring soon",
         "createdAt": "2019-03-05T23:11:29.000Z",
         "updatedAt": "2019-03-05T23:11:29.000Z",
         "messageType": "expirationNotification"
      }
   ]
}

GET /pass/{passId}/message

Returns an array of messages associated with the specified pass.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passId : StringREQUIRED

    The Id of the Google Pass you want to get messages from.

Responses

  • 200

    A successful response returns details for the added messages.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • messages : Array [Object]

        An array of messages associated with the pass.

        ARRAY ITEM
        • Google Wallet Message Response

          Information about messages associated with specified Google Wallet passes.

          OBJECT PROPERTIES
          • body : String

            The body of the message.

          • createdAt : String

            The date and time when the item was created. Format: date-time

          • header : String

            The header for the message.

          • messageType : String

            The type of message.

            Possible values: expirationNotification, text

          • updatedAt : String

            The date and time when the item was last updated. Format: date-time

  • 404

    The pass ID does not exist.

Add Message to Google Pass

Example Request

POST /v1/pass/mypass/message HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
   "body":"wallet object expires soon",
   "header":"expires",
   "startTime": "2018-06-03T21:10:00.000Z",
   "endTime": "2018-06-05T21:50:00.000Z",
   "messageType":"expirationNotification"
}

Example Response

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

{
   "header": "expires",
   "body": "wallet object expires soon",
   "startTime": "2018-06-03T21:10:00.000Z",
   "endTime": "2018-06-05T21:50:00.000Z",
   "createdAt": "2021-08-18T23:25:05.075Z",
   "updatedAt": "2021-08-18T23:25:05.075Z",
   "messageType": "expirationNotification"
}

POST /pass/{passId}/message

Add messages to Google Wallet passes.

Security:

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • passId : StringREQUIRED

    The Id of the Google Pass you want to apply messages to.

Request Body

A valid request contains one message for the pass.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • body : String

      The message body text.

    • endTime : Object

      The date-time when the notification will end. If you do not set an end time, the notification displays indefinitely.

      OBJECT PROPERTIES
      • date : String

        Format: date-time

    • header : String

      The header text for the message

    • messageType : String

      Use expirationNotification to warn users of expiring messages, and text for all other notifications. expirationNotification is based on the start value in the displayInterval; the maximum display interval is 30 days from now. If the expiration start date is more than 30 days from now, the message will not appear until the 30-day mark.

      Possible values: expirationNotification, text

    • startTime : Object

      The date-time when the notification will begin appearing to users.

      OBJECT PROPERTIES
      • date : String

        Format: date-time

Responses

  • 200

    A successful response returns details for the added message.

    RESPONSE BODY
    • Content-Type: application/json

      Information about messages associated with specified Google Wallet passes.

      OBJECT PROPERTIES
      • body : String

        The body of the message.

      • createdAt : String

        The date and time when the item was created. Format: date-time

      • header : String

        The header for the message.

      • messageType : String

        The type of message.

        Possible values: expirationNotification, text

      • updatedAt : String

        The date and time when the item was last updated. Format: date-time

  • 404

    The pass ID does not exist.

Save to Google Wallet

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

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 /pass/{template_id}/saveToWallet

Creates a pass from the specified template and returns code for a “Save to Google Wallet” button. Clicking or tapping this button installs the pass.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • template_id : StringREQUIRED

    The id of the template you want to generate a “Save to Google Wallet” button for.

Request Body

The request is much like creating a pass with the addition of functions to perform upon success or failure.

  • Content-Type: application/json

    Object

    OBJECT PROPERTIES
    • externalId : String

      An external identifier for the pass that you might want to use to update the pass in the future.

    • fields : Object

      OBJECT PROPERTIES
      • field.label : Object

        The label of a field you want to update on the resulting pass.

        OBJECT PROPERTIES
        • value : String

          The value you want to provide to the field.

    • onFail : String

      A javascript function that you want to be called when a user

    • onSuccess : String

      A javascript function that you want to be called when a user successfully adds the pass to Google Wallet.

    • tag : String

      A single tag you want to add to the pass.

Responses

  • 200

    A response includes the javascript for a “Save to Google Wallet” button.

Schedules

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

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

{
   "count": 2,
   "next_page": "https://wallet-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://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
      },
      {
         "schedule": {},
         "update": {},
         "url": "http://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed10A"
      }
   ],
   "total_count": 4
}

GET /schedules/{projectId}

Get a list of all schedules that have not yet occurred for the project.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project ID.

Responses

  • 200

    Returns a list of schedules, ordered scheduled_time closest to the present.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • count : Integer

        The number of schedules on the page.

      • next_page : String

        The URL of the next page in the result set. Format: url

      • ok : Boolean

        If true, the operation completed successfully.

      • schedules : Array [Object]

        The list of upcoming schedules.

        ARRAY ITEM
        • Schedule Object

          Specifies updates to passes or adaptive links at a particular date and time.

          OBJECT PROPERTIES
          • name : String

            A name for the schedule.

          • schedule : Object

            OBJECT PROPERTIES
            • scheduled_time : String

              The ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC. Format: date-time

          • update : Object

            The updates you want to make to an audience or pass, generated from a template within the project.

            OBJECT PROPERTIES
            • audience : Audience Selector

              Determines the passes you want to target.

            • pass : Object

              OBJECT PROPERTIES
              • fields : Object

                OBJECT PROPERTIES
                • Field Title (String) : Object

                  OBJECT PROPERTIES
                  • value : String

                    The value you want to change for a field on a pass.

              • template : Integer

                The ID of the template you want to update.

            • url : String

              A URL to get the schedule object. Format: url

      • total_count : Integer

        The total number of schedules.

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

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

{
  "ok": true,
  "operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
  "schedule_urls": [
     "https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
  ],
  "schedules": [
     {
        "url": "https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109",
        "ticket": "https://wallet-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 /schedules/{projectId}

Schedule an update to a project. The body of the request is an object containing a name, a schedule object, and an update object (which itself contains the audience, pass, and template updates you want to perform).

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project ID.

Request Body

  • Content-Type: application/json

    Schedule Object : Object

    Specifies updates to passes or adaptive links at a particular date and time.

    OBJECT PROPERTIES
    • name : String

      A name for the schedule.

    • schedule : Object

      OBJECT PROPERTIES
      • scheduled_time : String

        The ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC. Format: date-time

    • update : Object

      The updates you want to make to an audience or pass, generated from a template within the project.

      OBJECT PROPERTIES
      • audience : Audience Selector

        Determines the passes you want to target.

      • pass : Object

        OBJECT PROPERTIES
        • fields : Object

          OBJECT PROPERTIES
          • Field Title (String) : Object

            OBJECT PROPERTIES
            • value : String

              The value you want to change for a field on a pass.

        • template : Integer

          The ID of the template you want to update.

      • url : String

        A URL to get the schedule object. Format: url

Responses

  • 200

    Returns the schedule request along with identifiers for the operation and the schedule itself.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ok : Boolean

        If true, the operation completed successfully.

      • operation_id : String

        Identifies the operation for troubleshooting and logging. Format: uuid

      • schedule_urls : Array [String]

        URLs for the schedules created by the operation. Items in the array are ordered just as they were in the request.

      • schedules : Array [Object]

        ARRAY ITEM
        • Schedule Object

          Specifies updates to passes or adaptive links at a particular date and time.

          OBJECT PROPERTIES
          • name : String

            A name for the schedule.

          • schedule : Object

            OBJECT PROPERTIES
            • scheduled_time : String

              The ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC. Format: date-time

          • update : Object

            The updates you want to make to an audience or pass, generated from a template within the project.

            OBJECT PROPERTIES
            • audience : Audience Selector

              Determines the passes you want to target.

            • pass : Object

              OBJECT PROPERTIES
              • fields : Object

                OBJECT PROPERTIES
                • Field Title (String) : Object

                  OBJECT PROPERTIES
                  • value : String

                    The value you want to change for a field on a pass.

              • template : Integer

                The ID of the template you want to update.

            • url : String

              A URL to get the schedule object. Format: url

Get a 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
Content-Type: application/json; charset=utf-8

{
  "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 /schedules/{projectId}/{scheduleId}

Return a single project’s schedule.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project ID.

  • scheduleId : StringREQUIRED

    The schedule ID. This is appended to the end of the url in the response for schedule operations.

Responses

  • 200

    Returns a single schedule object.

    RESPONSE BODY
    • Content-Type: application/json

      Specifies updates to passes or adaptive links at a particular date and time.

      OBJECT PROPERTIES
      • name : String

        A name for the schedule.

      • schedule : Object

        OBJECT PROPERTIES
        • scheduled_time : String

          The ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC. Format: date-time

      • update : Object

        The updates you want to make to an audience or pass, generated from a template within the project.

        OBJECT PROPERTIES
        • audience : Audience Selector

          Determines the passes you want to target.

        • pass : Object

          OBJECT PROPERTIES
          • fields : Object

            OBJECT PROPERTIES
            • Field Title (String) : Object

              OBJECT PROPERTIES
              • value : String

                The value you want to change for a field on a pass.

          • template : Integer

            The ID of the template you want to update.

        • url : String

          A URL to get the schedule object. Format: url

Update a Schedule

Example Request

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

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

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

{
  "ok": true,
  "operation_id": "efb18e92-9a60-6689-45c2-82fedab36490",
  "schedule_urls": [
     "https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
  ],
  "schedules": [
     {
        "url": "https://wallet-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 /schedules/{projectId}/{scheduleId}

Update a schedule. The payload to update a schedule is identical to the request to create a schedule.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project ID.

  • scheduleId : StringREQUIRED

    The schedule ID. This is appended to the end of the url in the response for schedule operations.

Request Body

  • Content-Type: application/json

    Schedule Object : Object

    Specifies updates to passes or adaptive links at a particular date and time.

    OBJECT PROPERTIES
    • name : String

      A name for the schedule.

    • schedule : Object

      OBJECT PROPERTIES
      • scheduled_time : String

        The ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC. Format: date-time

    • update : Object

      The updates you want to make to an audience or pass, generated from a template within the project.

      OBJECT PROPERTIES
      • audience : Audience Selector

        Determines the passes you want to target.

      • pass : Object

        OBJECT PROPERTIES
        • fields : Object

          OBJECT PROPERTIES
          • Field Title (String) : Object

            OBJECT PROPERTIES
            • value : String

              The value you want to change for a field on a pass.

        • template : Integer

          The ID of the template you want to update.

      • url : String

        A URL to get the schedule object. Format: url

Responses

  • 200

    Returns the updated schedule object.

    RESPONSE BODY
    • Content-Type: application/json

      OBJECT PROPERTIES
      • ok : Boolean

        If true, the operation completed successfully.

      • operation_id : String

        Identifies the operation for troubleshooting and logging. Format: uuid

      • schedule_urls : Array [String]

        URL for the updated schedule.

      • schedules : Array [Object]

        ARRAY ITEM
        • Schedule Object

          Specifies updates to passes or adaptive links at a particular date and time.

          OBJECT PROPERTIES
          • name : String

            A name for the schedule.

          • schedule : Object

            OBJECT PROPERTIES
            • scheduled_time : String

              The ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC. Format: date-time

          • update : Object

            The updates you want to make to an audience or pass, generated from a template within the project.

            OBJECT PROPERTIES
            • audience : Audience Selector

              Determines the passes you want to target.

            • pass : Object

              OBJECT PROPERTIES
              • fields : Object

                OBJECT PROPERTIES
                • Field Title (String) : Object

                  OBJECT PROPERTIES
                  • value : String

                    The value you want to change for a field on a pass.

              • template : Integer

                The ID of the template you want to update.

            • url : String

              A URL to get the schedule object. Format: url

Delete a 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 /schedules/{projectId}/{scheduleId}

Deletes the specified schedule.

header PARAMETERS
  • Api-Revision : StringREQUIRED

    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

path PARAMETERS
  • projectId : StringREQUIRED

    The project ID.

  • scheduleId : StringREQUIRED

    The schedule ID. This is appended to the end of the url in the response for schedule operations.

Responses

  • 204

    A deleted schedule returns no content.

Data Formats

Template Objects

Template objects vary based on the vendor they’re intended for and the types of passes you want to create.

Optional Fields for Google Headers

Example Google Header Object with Optional Keys

{
  "background_color": {
    "ignoresTimeZone": null,
    "changeMessage": null,
    "label": "",
    "hideEmpty": false,
    "formatType": "String",
    "value": "#006491",
    "fieldType": "topLevel",
    "required": false
  }
}
  • Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

    OBJECT PROPERTIES
    • changeMessage : String

      The message that appears when you update this field.

    • hideEmpty : Boolean

      If true, the field is hidden if empty.

    • ignoresTimeZone : Boolean

      if true, the date-time value in a field on an Apple Wallet pass is not offset to account for the pass recipient’s time zone. This may be helpful for things like boarding passes or events, where your times are set local to an airport or venue and should not change based on a user’s device. When applied to a non-date-time field or a Google template, this setting is ignored.

    • label : String

      In most cases, you should not set a label for a Google template header. In responses, the label is typically an empty string.

    • required : Boolean

      Indicates whether or not the field is required on passes created from this template.

    • textAlignment : String

      The alignment of text on the pass.

      Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural

Google Wallet Template Request

Example Google Template Request

{
  "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"
}
  • A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.

    All of
    • General Template Headers : Object

      Meta information about templates; this object appears on all templates and identifies templates associated with a project.

      OBJECT PROPERTIES
      • deleted : Boolean

        If true, the template is deleted. You can no longer create passes from this template.

      • description : String

        A description for the template.

      • disabled : Boolean

        If true, the template is disabled; you cannot create new passes for this template until you update the template and enable it again.

      • expiryInfo : Any

        Determine when passes generated from the template should expire.

        One of
        • Expire on a date : Object

          Set the specific expiration date for passes generated from this template. Passes expire at 12:00 AM on the date you provide.

          OBJECT PROPERTIES
          • expiryDate : String

            The date when passes expire. Format: date

          • expiryTimeZone : String

            Passes expire at 12:00 AM in the time zone you set.

        • Expire after : Object

          Expire passes generated from this template after the specified number of minutes after creation.

          OBJECT PROPERTIES
          • expiryDuration : Integer

            The number of days after creation that passes will expire.

        • Never expire : Object

          Passes generated from the template will never expire.

          OBJECT PROPERTIES
          • expireNever : String

            Any string value (or null) will prevent passes generated from this template from expiring.

      • name : StringREQUIRED

        The name of the template.

      • projectId : Integer

        The ID of the project. Use this ID to reference your project in the API.

      • projectType : String

        The type of pass the template supports; matches the type setting for the parent project.

        Possible values: memberCard, coupon, boardingPass, eventTicket, generic, loyalty, giftCard

      • type : String

        The type of pass the template supports. This value corresponds to the projectType.

        Possible values: memberCard, coupon, boardingPass, eventTicket, generic, loyalty, giftCard

      • vendor : StringREQUIRED

        The device vendor the template is designed for, Apple or Google.

        Possible values: Apple, Google

      • vendorId : IntegerREQUIRED

        Corresponds to the vendor the template supports. 1 indicates an Apple template; 2 indicates a Google template.

        Possible values: 1, 2

    • Google Fields : Object

      Fields on a Google pass are organized into modules. Modules define how fields on the pass are organized and appear. Fields within each module are objects with a string names.

      OBJECT PROPERTIES
      • acctModule : Object

        Information associated with an account or membership. These are typically items like the accountIdLabel on Loyalty cards or balance items on a gift card.

        OBJECT PROPERTIES
        • Google Field Object : Object

          Represents a field on a Google pass. Each field is an object with a string name containing the following keys.

          Fields for Google templates belong to modules. Modules determine placement on the pass and, in some cases, the types of values for the field.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • col : IntegerDEPRECATED

            Determines vertical location/order within the fieldType. Use order instead.

          • hideEmpty : Boolean

            If true, the field is hidden if empty.

          • label : StringREQUIRED

            A label for the field; this is the field title as shown on the pass.

          • order : Integer

            The order of fields with the same fieldType (Apple) or belonging to the same module (Google). If there are multiple fields with the same fieldType, order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most position.

          • required : Boolean

            Indicates whether or not the field is required on passes created from this template.

          • row : IntegerDEPRECATED

            Determines horizontal location/order within the fieldType. Use order instead.

          • textAlignment : String

            The alignment of text on the pass.

            Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural

          • value : AnyREQUIRED

            The default value for the field. The data type supported by this field is determined by the formatType.

            One of
            • String

            • Number

            • Integer

      • headers : Object

        Fields appearing in the headers object for a Google pass template. Header fields typically follow the same model as other fields for Google Wallet templates and passes, but often have specific value, fieldType, and formatType values.

        OBJECT PROPERTIES
        • background_color : Object

          Sets the background color for the pass.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to topLevel for color and text headers.

              Possible values: topLevel

            • value : String

              The color objects take an rgb value in the format rgb(255, 255, 255).

              Format: rgb Pattern: rgb\({1,255}, {1,255}, {1,255}\)

        • background_image : Object

          A background image for the pass.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

        • barcodeAltText : Object

          Alternate text displayed below the barcode.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The alternate text for the barcode on the template.

        • barcode_encoding : Object

          The encoding format for the barcode.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              Presently, iso-8859-1 is the only supported value.

              Possible values: iso-8859-1

        • barcode_type : Object

          The type of barcode supported by the template. This value must be the same as the barcode_type set at the project level.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              Presently, iso-8859-1 is the only supported value.

              Possible values: pdf417, aztec, code128, qr, upc-a, ean-13, code-39

        • barcode_value : Object

          The default value for the barcode used by the template.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              This value is a default for the barcode. You may set a new or personalized value when creating adaptive links or passes.

        • The footer image for a template.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • Indicates that the value is an image.

              Possible values: image

            • Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • The URL for the header image.

              Format: url

        • foreground_color : Object

          Sets the foreground color for the template.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to topLevel for color and text headers.

              Possible values: topLevel

            • value : String

              The color objects take an rgb value in the format rgb(255, 255, 255).

              Format: rgb Pattern: rgb\({1,255}, {1,255}, {1,255}\)

        • header : Object

          Sets the generic pass header. Required for the generic pass type.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to topLevel for text headers.

              Possible values: topLevel

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              Header text field.

              Format: text

        • icon_image : Object

          The icon image for the template.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

        • logo_image : Object

          Specifies the template logo image.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

        • logo_text : Object

          Sets the text under the logo image.

          OBJECT PROPERTIES
          • fieldType : String

            Indicates that the value is an image.

            Possible values: image

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            The alternate text for the logo_image.

        • sharingStatus : Object

          A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.

          On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.

          You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • value : StringREQUIRED

            Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.

            Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

        • strip_image : Object

          The image residing in the barcode strip.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

        • subheader : Object

          Sets the optional generic pass subheader.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to topLevel for text headers.

              Possible values: topLevel

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              Header text field.

              Format: text

        • suppress_strip_shine : Object

          Determines whether or not to suppress the strip shine effect on barcodes.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : Boolean

        • thumbnail_image : Object

          An object containing the URL for the thumbnail image.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

      • imageModulesData : Object

        Contains an image on the pass outside the header. Max properties: 1

        OBJECT PROPERTIES
        • Google Field Object : Object

          Represents a field on a Google pass. Each field is an object with a string name containing the following keys.

          Fields for Google templates belong to modules. Modules determine placement on the pass and, in some cases, the types of values for the field.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • col : IntegerDEPRECATED

            Determines vertical location/order within the fieldType. Use order instead.

          • hideEmpty : Boolean

            If true, the field is hidden if empty.

          • label : StringREQUIRED

            A label for the field; this is the field title as shown on the pass.

          • order : Integer

            The order of fields with the same fieldType (Apple) or belonging to the same module (Google). If there are multiple fields with the same fieldType, order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most position.

          • required : Boolean

            Indicates whether or not the field is required on passes created from this template.

          • row : IntegerDEPRECATED

            Determines horizontal location/order within the fieldType. Use order instead.

          • textAlignment : String

            The alignment of text on the pass.

            Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural

          • value : AnyREQUIRED

            The default value for the field. The data type supported by this field is determined by the formatType.

            One of
            • String

            • Number

            • Integer

      • infoModuleData : Object

        Info module Max properties: 10

        OBJECT PROPERTIES
        • Google Field Object : Object

          Represents a field on a Google pass. Each field is an object with a string name containing the following keys.

          Fields for Google templates belong to modules. Modules determine placement on the pass and, in some cases, the types of values for the field.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • col : IntegerDEPRECATED

            Determines vertical location/order within the fieldType. Use order instead.

          • hideEmpty : Boolean

            If true, the field is hidden if empty.

          • label : StringREQUIRED

            A label for the field; this is the field title as shown on the pass.

          • order : Integer

            The order of fields with the same fieldType (Apple) or belonging to the same module (Google). If there are multiple fields with the same fieldType, order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most position.

          • required : Boolean

            Indicates whether or not the field is required on passes created from this template.

          • row : IntegerDEPRECATED

            Determines horizontal location/order within the fieldType. Use order instead.

          • textAlignment : String

            The alignment of text on the pass.

            Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural

          • value : AnyREQUIRED

            The default value for the field. The data type supported by this field is determined by the formatType.

            One of
            • String

            • Number

            • Integer

      • linkModulesData : Object

        Contains links including URLs, phone numbers, and email addresses, that you want to make available on the pass. This module typically appears at the bottom of the pass. Max properties: 10

        OBJECT PROPERTIES
        • Google Field Object : Object

          Represents a field on a Google pass. Each field is an object with a string name containing the following keys.

          Fields for Google templates belong to modules. Modules determine placement on the pass and, in some cases, the types of values for the field.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • col : IntegerDEPRECATED

            Determines vertical location/order within the fieldType. Use order instead.

          • hideEmpty : Boolean

            If true, the field is hidden if empty.

          • label : StringREQUIRED

            A label for the field; this is the field title as shown on the pass.

          • order : Integer

            The order of fields with the same fieldType (Apple) or belonging to the same module (Google). If there are multiple fields with the same fieldType, order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most position.

          • required : Boolean

            Indicates whether or not the field is required on passes created from this template.

          • row : IntegerDEPRECATED

            Determines horizontal location/order within the fieldType. Use order instead.

          • textAlignment : String

            The alignment of text on the pass.

            Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural

          • value : AnyREQUIRED

            The default value for the field. The data type supported by this field is determined by the formatType.

            One of
            • String

            • Number

            • Integer

      • offerModule : Object

        Specific to google coupons, this module contains information about redeeming the coupon.

        OBJECT PROPERTIES
        • endTime : String

          The expiration date for the offer. Format: date-time

        • multiUseOffer : Boolean

          Indicates whether the coupon/offer is available for multiple users or just a single user.

        • provider : String

          The offer provider name.

        • redemptionChannel : String

          Indicates whether the user can redeem the offer at a physical location or online.

          Possible values: online, instore, both, temporaryPriceReduction

      • pointsModule : Object

        Contains information related to points that pass users accrue or spend. This module is typically used on loyalty passes.

        OBJECT PROPERTIES
        • Google Field Object : Object

          Represents a field on a Google pass. Each field is an object with a string name containing the following keys.

          Fields for Google templates belong to modules. Modules determine placement on the pass and, in some cases, the types of values for the field.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • col : IntegerDEPRECATED

            Determines vertical location/order within the fieldType. Use order instead.

          • hideEmpty : Boolean

            If true, the field is hidden if empty.

          • label : StringREQUIRED

            A label for the field; this is the field title as shown on the pass.

          • order : Integer

            The order of fields with the same fieldType (Apple) or belonging to the same module (Google). If there are multiple fields with the same fieldType, order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most position.

          • required : Boolean

            Indicates whether or not the field is required on passes created from this template.

          • row : IntegerDEPRECATED

            Determines horizontal location/order within the fieldType. Use order instead.

          • textAlignment : String

            The alignment of text on the pass.

            Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural

          • value : AnyREQUIRED

            The default value for the field. The data type supported by this field is determined by the formatType.

            One of
            • String

            • Number

            • Integer

      • textModulesData : Object

        Contains text information for a pass. The text module typically has information in a header-body format.

        OBJECT PROPERTIES
        • Google Field Object : Object

          Represents a field on a Google pass. Each field is an object with a string name containing the following keys.

          Fields for Google templates belong to modules. Modules determine placement on the pass and, in some cases, the types of values for the field.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • col : IntegerDEPRECATED

            Determines vertical location/order within the fieldType. Use order instead.

          • hideEmpty : Boolean

            If true, the field is hidden if empty.

          • label : StringREQUIRED

            A label for the field; this is the field title as shown on the pass.

          • order : Integer

            The order of fields with the same fieldType (Apple) or belonging to the same module (Google). If there are multiple fields with the same fieldType, order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most position.

          • required : Boolean

            Indicates whether or not the field is required on passes created from this template.

          • row : IntegerDEPRECATED

            Determines horizontal location/order within the fieldType. Use order instead.

          • textAlignment : String

            The alignment of text on the pass.

            Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural

          • value : AnyREQUIRED

            The default value for the field. The data type supported by this field is determined by the formatType.

            One of
            • String

            • Number

            • Integer

      • titleModule : Object

        Contains title and header information specific to each pass type (as opposed to common items held within headers). These are items typically referenced by class in Google pass designs.

        OBJECT PROPERTIES
        • Google Field Object : Object

          Represents a field on a Google pass. Each field is an object with a string name containing the following keys.

          Fields for Google templates belong to modules. Modules determine placement on the pass and, in some cases, the types of values for the field.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • col : IntegerDEPRECATED

            Determines vertical location/order within the fieldType. Use order instead.

          • hideEmpty : Boolean

            If true, the field is hidden if empty.

          • label : StringREQUIRED

            A label for the field; this is the field title as shown on the pass.

          • order : Integer

            The order of fields with the same fieldType (Apple) or belonging to the same module (Google). If there are multiple fields with the same fieldType, order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most position.

          • required : Boolean

            Indicates whether or not the field is required on passes created from this template.

          • row : IntegerDEPRECATED

            Determines horizontal location/order within the fieldType. Use order instead.

          • textAlignment : String

            The alignment of text on the pass.

            Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural

          • value : AnyREQUIRED

            The default value for the field. The data type supported by this field is determined by the formatType.

            One of
            • String

            • Number

            • Integer

Apple Wallet Template Request

Example Apple Wallet Template Request

{
  "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": {
    "Coupon": {
      "formatType": "String",
      "changeMessage": "Enjoy %@ off your next order!",
      "order": 1,
      "fieldType": "primary",
      "textAlignment": "textAlignmentRight",
      "value": "20%",
      "label": "coupon",
      "required": false,
      "hideEmpty": true
    },
    "SiteAddress": {
      "formatType": "Number",
      "changeMessage": "New stuff, just for you at %@",
      "order": 2,
      "textAlignment": "textAlignmentCenter",
      "fieldType": "secondary",
      "value": "https://www.store.com/new?custnumb=123456",
      "label": "personalDeals",
      "required": false,
      "hideEmpty": true
    },
    "InStore": {
      "formatType": "String",
      "changeMessage": "Or visit your nearest store at %@",
      "order": 1,
      "fieldType": "secondary",
      "value": "1234 Fake St.",
      "label": "nearestStore",
      "required": false,
      "hideEmpty": false
    }
  },

  "vendor": "Apple",
  "projectType": "memberCard",
  "projectId": 1234,
  "type": "Store Card",
  "vendorId": 1,
  "deleted": "False",
  "description": "Description",
  "name": "Loyalty Card",
  "disabled": "False"
}
  • A complete iOS template includes template meta information, headers, and fields.

    All of
    • General Template Headers : Object

      Meta information about templates; this object appears on all templates and identifies templates associated with a project.

      OBJECT PROPERTIES
      • deleted : Boolean

        If true, the template is deleted. You can no longer create passes from this template.

      • description : String

        A description for the template.

      • disabled : Boolean

        If true, the template is disabled; you cannot create new passes for this template until you update the template and enable it again.

      • expiryInfo : Any

        Determine when passes generated from the template should expire.

        One of
        • Expire on a date : Object

          Set the specific expiration date for passes generated from this template. Passes expire at 12:00 AM on the date you provide.

          OBJECT PROPERTIES
          • expiryDate : String

            The date when passes expire. Format: date

          • expiryTimeZone : String

            Passes expire at 12:00 AM in the time zone you set.

        • Expire after : Object

          Expire passes generated from this template after the specified number of minutes after creation.

          OBJECT PROPERTIES
          • expiryDuration : Integer

            The number of days after creation that passes will expire.

        • Never expire : Object

          Passes generated from the template will never expire.

          OBJECT PROPERTIES
          • expireNever : String

            Any string value (or null) will prevent passes generated from this template from expiring.

      • name : StringREQUIRED

        The name of the template.

      • projectId : Integer

        The ID of the project. Use this ID to reference your project in the API.

      • projectType : String

        The type of pass the template supports; matches the type setting for the parent project.

        Possible values: memberCard, coupon, boardingPass, eventTicket, generic, loyalty, giftCard

      • type : String

        The type of pass the template supports. This value corresponds to the projectType.

        Possible values: memberCard, coupon, boardingPass, eventTicket, generic, loyalty, giftCard

      • vendor : StringREQUIRED

        The device vendor the template is designed for, Apple or Google.

        Possible values: Apple, Google

      • vendorId : IntegerREQUIRED

        Corresponds to the vendor the template supports. 1 indicates an Apple template; 2 indicates a Google template.

        Possible values: 1, 2

    • iOS Template Headers : Object

      The iOS template headers object can contain the following objects. Each object has a formatType, fieldType, and value.

      • formatType is always 1, indicating that the value is a string.

      • fieldType is topLevel — a text or color value on the top-front of the pass, image, or barcode.

      • value is the default value for the header field.

      OBJECT PROPERTIES
      • background_color : Object

        Sets the background color for the pass.

        OBJECT PROPERTIES
        • fieldType : String

          Set to topLevel for color and text headers.

          Possible values: topLevel

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The color objects take an rgb value in the format rgb(255, 255, 255).

          Format: rgb Pattern: rgb\({1,255}, {1,255}, {1,255}\)

      • background_image : Object

        A background image for the pass.

        OBJECT PROPERTIES
        • fieldType : String

          Indicates that the value is an image.

          Possible values: image

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The URL for the header image.

          Format: url

      • barcodeAltText : Object

        Alternate text displayed below the barcode.

        OBJECT PROPERTIES
        • fieldType : String

          Set to barcode for all barcode headers.

          Possible values: barcode

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The alternate text for the barcode on the template.

      • barcode_encoding : Object

        The encoding format for the barcode.

        OBJECT PROPERTIES
        • fieldType : String

          Set to barcode for all barcode headers.

          Possible values: barcode

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          Presently, iso-8859-1 is the only supported value.

          Possible values: iso-8859-1

      • barcode_type : Object

        The type of barcode supported by the template. This value must be the same as the barcode_type set at the project level.

        OBJECT PROPERTIES
        • fieldType : String

          Set to barcode for all barcode headers.

          Possible values: barcode

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          Presently, iso-8859-1 is the only supported value.

          Possible values: pdf417, aztec, code128, qr, upc-a, ean-13, code-39

      • barcode_value : Object

        The default value for the barcode used by the template.

        OBJECT PROPERTIES
        • fieldType : String

          Set to barcode for all barcode headers.

          Possible values: barcode

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          This value is a default for the barcode. You may set a new or personalized value when creating adaptive links or passes.

      • The footer image for a template.

        OBJECT PROPERTIES
        • Indicates that the value is an image.

          Possible values: image

        • For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • The URL for the header image.

          Format: url

      • foreground_color : Object

        Sets the foreground color for the template.

        OBJECT PROPERTIES
        • fieldType : String

          Set to topLevel for color and text headers.

          Possible values: topLevel

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The color objects take an rgb value in the format rgb(255, 255, 255).

          Format: rgb Pattern: rgb\({1,255}, {1,255}, {1,255}\)

      • icon_image : Object

        The icon image for the template.

        OBJECT PROPERTIES
        • fieldType : String

          Indicates that the value is an image.

          Possible values: image

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The URL for the header image.

          Format: url

      • logo_color : Object

        Specifies the color of the logo on the template.

        OBJECT PROPERTIES
        • fieldType : String

          Set to topLevel for color and text headers.

          Possible values: topLevel

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The color objects take an rgb value in the format rgb(255, 255, 255).

          Format: rgb Pattern: rgb\({1,255}, {1,255}, {1,255}\)

      • logo_image : Object

        Specifies the template logo image.

        OBJECT PROPERTIES
        • fieldType : String

          Indicates that the value is an image.

          Possible values: image

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The URL for the header image.

          Format: url

      • logo_text : Object

        Sets the text under the logo image.

        OBJECT PROPERTIES
        • fieldType : String

          Indicates that the value is an image.

          Possible values: image

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The alternate text for the logo_image.

      • sharingStatus : Object

        A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.

        On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.

        You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.

        OBJECT PROPERTIES
        • changeMessage : String

          The message that appears when you update this field.

        • value : StringREQUIRED

          Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.

          Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

      • strip_image : Object

        The image residing in the barcode strip.

        OBJECT PROPERTIES
        • fieldType : String

          Indicates that the value is an image.

          Possible values: image

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The URL for the header image.

          Format: url

      • suppress_strip_shine : Object

        Determines whether or not to suppress the strip shine effect on barcodes.

        OBJECT PROPERTIES
        • fieldType : String

          Set to barcode for all barcode headers.

          Possible values: barcode

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : Boolean

      • thumbnail_image : Object

        An object containing the URL for the thumbnail image.

        OBJECT PROPERTIES
        • fieldType : String

          Indicates that the value is an image.

          Possible values: image

        • formatType : Integer

          For iOS, a value of 1 indicates that the formatType for the field is a string.

          Possible values: 1

        • value : String

          The URL for the header image.

          Format: url

    • iOS Fields : Object

      Defines fields on iOS templates and subsequent passes generated from the template.

      OBJECT PROPERTIES
      • fields : Object

        All non-header fields on an iOS template sit inside this object.

        OBJECT PROPERTIES
        • Field Name (String) : Object

          Fields on an iOS template are objects with a string name. Where they appear and the data they contain are determined by the fields within the object.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • currencyCode : String

            Determines the type of currency if the formatType is set to currency.

            Possible values: USD, EUR, CNY, JPY, GPB, RUB, AUD, CHF, CAD, HKD, SEK, NZD, KRW, SGD, NOK, MXN, INR

          • formatType : String

            The input format for the field.

            Possible values: String, Number, URL, Date, Currency, Phone, Email

          • hideempty : Boolean

            If true, the field is hidden if empty.

          • ignoresTimeZone : Boolean

            if true, the date-time value in a field on an Apple Wallet pass is not offset to account for the pass recipient’s time zone. This may be helpful for things like boarding passes or events, where your times are set local to an airport or venue and should not change based on a user’s device. When applied to a non-date-time field or a Google template, this setting is ignored.

          • label : String

            A label for the field; this is typically the field title as shown on the pass.

          • numberStyle : String

            Determines how a template interprets number values when formatType is set to Number. This is specific to Apple Wallet passes.

            Possible values: numberStyleDecimal, numberStyleSpellOut, numberStyleScientific, numberStylePercent

          • order : Integer

            The order of fields with the same fieldType (Apple) or belonging to the same module (Google). If there are multiple fields with the same fieldType, order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most position.

          • required : Boolean

            Indicates whether or not the field is required on passes created from this template.

          • textAlignment : String

            The alignment of text on the pass.

            Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural

          • value : Any

            The default value for the field. The data type supported by this field is determined by the formatType.

            One of
            • String

            • Number

            • Integer

Apple Pass Personalization Requirements

Example Apple Loyalty Personalization Requirements

{
  "requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
  ],
  "description": "Enter your information to sign up and earn points.",
  "termsAndConditions": "Terms and conditions go here"
}
  • OBJECT PROPERTIES
    • description : StringREQUIRED

      A brief description of the rewards program that the recipient is signing up for. The description appears on the signup sheet, under the personalization logo.

    • imageUrl : String

      The URL of the image you want to appear at the top of the signup form. This image must be a 150 x 40 point PNG image.

      Format: url

    • requiredPersonalizationFields : Array [String]REQUIRED

      An array of strings representing fields that a customer must provide to sign up for your rewards/loyalty program. Some keys populate multiple fields in the personalization callback or on passes.

      • name - requires the user to enter their fullName. This also populates the givenName and familyName fields on passes and/or personalization callbacks.
      • postalCode - prompts the user for their postal code. This populates both postalCode and ISOCountryCode on passes and/or personalization callbacks.
      • emailAddress - requires the user’s email address.
      • phoneNumber - requires the user’s phone number.

      Max items: 4 Min items: 1

    • termsAndConditions : String

      The terms and conditions for the reward program. If present, this information appears after the user enters their personal information and taps Next. The user then has the option to agree to the terms, or to cancel the signup process.

Adaptive links detect the user’s platform and install the correct pass for their device vendor. An adaptive link can specify an Apple and Google template.

Adaptive Link Request

Example Adaptive Link

{
  "iosTemplateId": "12345",
  "androidTemplateId": "154321",
  "isPersonalized": "true",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "expirationDate": "2022-10-01",
  "availablePasses": 100000,
  "ttlInDays": 30,
  "parameterEncoding": "base64",
  "locationRadius": 10,
  "maxResultLocations": 5,
  "payload": {},
  "locations": [
      {
         "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?"
      }
    ]
  }
  • An adaptive link request contains identifiers for the templates you used to generate passes from the link, and any fields you want to set when users create passes from the link.

    All of
    • Object

      OBJECT PROPERTIES
      • The custom identifier of the Google template for passes issued from this adaptive link.

      • The Google template for passes issued from the adaptive link.

      • The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.

      • The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.

      • The iOS template for passes issued from the adaptive link.

      • If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters, isPersonalized is automatically set to true.

        If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When isPersonalized is false, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link.

      • The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason. Format: url

      • When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.

        Possible values: base64

    • Object

      OBJECT PROPERTIES
      • A dynamic link for Android passes. Format: uuid

      • When set, indicates the date this adaptive link expires. An expired adaptive link will return a JSON object with an error message instead of a pass.

        Format: date-time

      • The number of times a user can install the pass. When the pass reaches its limit, attempts to install the pass are met with errors.

        This limit only affects the adaptive link itself, not actual Apple pass files. If you want to prevent users from installing shared passes on Apple devices, you should also set sharingStatus to prohibit sharing.

      • The number of times a user can install the pass that has an externalId. When the pass reaches its limit, attempts to install the pass are met with errors.

        This limit only affects the adaptive link itself, not actual Apple pass files. If you want to prevent users from installing shared passes on Apple devices, you should also set sharingStatus to prohibit sharing.

      • A dynamic link for iOS passes. Format: uuid

      • Determines the range, in miles, that a passholder can be from a location to associate their pass with a location. If absent, the default location radius is 10 miles.

      • An array of up to 10,000 locations associated with the adaptive link. Apple Wallet supports up to 10 locations per pass. If you exceed this limit, Apple Wallet passes will use the 10 locations nearest to a user (located by IP address) when they install the pass.

        You can also include a location radius and the maximum number of locations to be matched upon pass creation. Wallet sorts locations to be matched in order from closest to/furthest from the location provided by the device.

      • The maximum number of locations the pass recipient can match. If the passholder matches multiple locations, locations are returned in order from closest to farthest.

      • The field names and values you want to update for those pass fields. Changing a value will result in a change message notifying the user of the changed value.

        While the payload object is required, it can be an empty object.

        OBJECT PROPERTIES
        • A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.

          On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.

          You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.

          OBJECT PROPERTIES
          • The message that appears when you update this field.

          • Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.

            Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

        • OBJECT PROPERTIES

Adaptive Link Response

Example Adaptive Link Response Object

{
  "adaptiveLinkId": "abchd345",
  "url": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkId>/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": "true",
  "isExpired": true,
  "expirationDate": "2020-10-01",
  "availablePasses": 100000,
  "ttlInDays": 730
}
  • An adaptive link response includes URLs that users can access to detect and install a pass.

    All of
    • Object

      OBJECT PROPERTIES
      • The custom identifier of the Google template for passes issued from this adaptive link.

      • The Google template for passes issued from the adaptive link.

      • The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.

      • The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.

      • The iOS template for passes issued from the adaptive link.

      • If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters, isPersonalized is automatically set to true.

        If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When isPersonalized is false, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link.

      • The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason. Format: url

      • When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.

        Possible values: base64

    • Object

      OBJECT PROPERTIES
      • A unique identifier for the adaptive link. Use this value to reference the adaptive link in future operations.

      • A dynamic link for Android passes. This field cannot be provided for links/adaptive/multiple requests, nor is it provided in those responses (e.g., boarding passes, event tickets, etc.). Format: uuid

      • A pass URL specific to Android users. Format: url

      • The date and time when the item was created. Format: date-time

      • The date this adaptive link expires. This property appears in the response only if it has been explicitly set with a previous API request. Cannot be set to a date more than 1080 days in the future.

        Format: date

      • A dynamic link for iOS passes. This field cannot be provided for links/adaptive/multiple requests, nor is it provided in those responses (e.g., boarding passes, event tickets, etc.). Format: uuid

      • A pass URL specific to iOS users. Format: url

      • If true, the adaptive link is expired. An expired adaptive link will return a JSON object with an error message instead of a pass.

      • The ID of the project.

      • The number of days of inactivity before this adaptive link automatically expires.

      • The date and time when the item was last updated. Format: date-time

      • The adaptive link URL itself; using this URL on an Android or iOS device will detect device types and install the correct pass.

        Format: url

Flights and Boarding Passes

Schemas for creating flights and boarding pass adaptive links. A Boarding pass includes both flight information and an array of passengers.

Boarding Pass Adaptive Link Request

Example Boarding Pass Adaptive Link

{
  "iosTemplateExternalId": "<iosTemplateExternalId>",
  "androidTemplateExternalId": "<androidTemplateExternalId>",
  "payload": {
    "isEventTicketUpdatePermitted": false,
    "flights": [
      {
        "flightExternalId": "<flightExternalId1>",
        "fields": {
          "flightNumber": { "value": "815" },
          "airlineCode": { "value": "WN" },
          "airlineName": { "value": "Southwest Airlines" },
          "departureAirport": {
            "label": "San Francisco",
            "value": "SFO"
          },
          "departureGate": {
            "label": "Gate #",
            "value": "25"
          },
          "boardingTime": { "value": "2018-07-30T08:35:00" },
          "departureTime": { "value": "2018-07-30T09:00:00" },
          "arrivalAirport": {
            "label": "Portland",
            "value": "PDX"
          },
          "arrivalTime": { "value": "2018-07-30T11:00:00" },
          "flightStatus": { "value": "scheduled" }
        },
        "passGroups": ["sfo-pdx-20180730"]
        "passengers": [
          {
            "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
            "fields": {
              "seatNumber": { "value": "13A" },
              "confirmationCode": { "value": "E4583B" },
              "passengerName": { "value": "SMITH/JOE" },
              "specialAssistance": { "label": "Special Assistance", "value": "Wheelchair" },
              "barcode_value": { "value": "12345" },
              "barcodeAltText": { "value": "12345" }
            }
          },
          {
            "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
            "fields": {
              "seatNumber": { "value": "13B" },
              "confirmationCode": { "value": "E4583B" },
              "passengerName": { "value": "SMITH/SALLY" },
              "barcode_value": { "value": "12346" },
              "barcodeAltText": { "value": "12346" }
            }
          },
          {
            "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
            "fields": {
              "seatNumber": { "value": "13C" },
              "confirmationCode": { "value": "E4583B" },
              "passengerName": { "value": "SMITH/SAM" },
              "barcode_value": { "value": "12347" },
              "barcodeAltText": { "value": "12347" }
            }
          }
        ]
      }
    ]
  }
}
  • A boarding pass adaptive link requires similar information to other adaptive link types, but the payload includes flight information and an array of passengers for each flight.

    Like other adaptive links, you must provide the id or externalId of an iOS or Android template.

    All of
    • Object

      OBJECT PROPERTIES
      • androidTemplateExternalId : String

        The custom identifier of the Google template for passes issued from this adaptive link.

      • androidTemplateId : String

        The Google template for passes issued from the adaptive link.

      • availablePasses : Integer

        The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.

      • iosTemplateExternalId : String

        The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.

      • iosTemplateId : String

        The iOS template for passes issued from the adaptive link.

      • isPersonalized : Boolean

        If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters, isPersonalized is automatically set to true.

        If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When isPersonalized is false, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link.

      • landingPageUrl : String

        The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason. Format: url

      • parameterEncoding : String

        When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.

        Possible values: base64

    • Object

      OBJECT PROPERTIES
      • payload : Object

        A boarding pass adaptive link object takes both flight and passenger information.

        You can provide the flightId or flightExternalId of an existing flight. Or, you can define a new flight using the flights object. If defining a new flight, you can provide a flightExternalId.

        OBJECT PROPERTIES
        • flights : Array [Any]

          Each object in the array represents an event. Each event object must specify the flightId or flightExternalId of an existing event, or contain the fields object sufficient to create a new event.

          You can also provide the eventExternalId in conjunction with the fields object to assign an eventExternalId to a new event.

          ARRAY ITEM
          • One of
            • Flight by ID

              You can specify the flightId or flightExternalId of an existing flight, and then you need only populate the passengers for the flight.

              All of
              • One of
                • Flight ID : Object

                  OBJECT PROPERTIES
                  • flightId : Integer

                    A unique, auto-generated identifier for a flight.

                    When creating boarding passes, if you specify a flight by ID, you do not need to define the flight in the fields object.

                • Flight External ID : Object

                  OBJECT PROPERTIES
                  • flightExternalId : String

                    An external, custom identifier for a flight. You can reference flights by flightExternalId rather than the Airship-generated flightId.

                    When creating boarding passes, if you specify an existing flight by flightExternalId, you do not need to provide flight information in the fields object. If creating a new flight in the fields object, you can assign a new flightExternalId to the new flight.

              • Passengers : Object

                OBJECT PROPERTIES
                • passGroups : Array [String]

                  An array of eventId or eventExternalId values representing a group. You can reference the group to make changes to all associated events.

                  You can set pass groups when creating an event or when creating an event ticket adaptive link.

                • passengers : Passengers

                  An array of objects, each object representing a passenger/seat on a flight. Passengers are a part of the payload for boarding pass adaptive links.

            • Create a New Flight

              You can create a flight as a part of a boarding pass request. You can provide a flightExternalId for the flight you are creating, and then provide a complete flight object in addition to the array of passengers for the flight.

              All of
              • Object

                OBJECT PROPERTIES
                • flightExternalId : String

                  An external, custom identifier for a flight. You can reference flights by flightExternalId rather than the Airship-generated flightId.

                  When creating boarding passes, if you specify an existing flight by flightExternalId, you do not need to provide flight information in the fields object. If creating a new flight in the fields object, you can assign a new flightExternalId to the new flight.

              • Flight Object

                A complete flight request object.

                The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.

              • Object

                OBJECT PROPERTIES
                • passengers : Passengers

                  An array of objects, each object representing a passenger/seat on a flight. Passengers are a part of the payload for boarding pass adaptive links.

        • isEventTicketUpdatePermitted : Boolean

          True by default. If false, event information for existing events will not be updated as part of the POST call to the Adaptive Link API; a new event will still be created if it does not yet exist.

        • isFlightUpdatePermitted : Boolean

          True by default. If false, flight information for existing flights will not be updated as part of the POST call to the Adaptive Link API; a new flight will still be created if it does not yet exist.

Flight Object

Example Flight Request Object

{
  "passGroups": ["sfo-pdx-20180730"],
  "fields": {
    "flightNumber": { "value": "815" },
    "airlineCode": { "value": "WN" },
    "airlineName": { "value": "Southwest Airlines" },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "25"
    },
    "boardingTime": { "value": "2018-07-30T08:35:00" },
    "departureTime": { "value": "2018-07-30T09:00:00" },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalTime": { "value": "2018-07-30T11:00:00" },
    "flightStatus": { "value": "scheduled" }
  }
}
  • A complete flight request object.

    The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.

    OBJECT PROPERTIES
    • fields : Object

      OBJECT PROPERTIES
      • actualArrivalTime : Object

        The date and time when the flight actually lands. This field is normally populated in updates to the flight, as real-time information becomes available for the benefit of ticket holders.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Format: date-time

      • actualDepartureTime : Object

        The date and time when the flight actually departs. This field is normally populated in updates to the flight, as real-time information becomes available.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Format: date-time

      • A URL for the airline alliance logo, if the airline belongs to an alliance.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Format: url

      • airlineCode : ObjectREQUIRED

        The airline code.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

      • A URL for the airline logo, shown on the front of the pass.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Format: url

      • airlineName : ObjectREQUIRED

        The airline name.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

      • arrivalAirport : ObjectREQUIRED

        The airport the flight arrives at.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

      • arrivalGate : Object

        The gate that the flight arrives at.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

      • arrivalTerminal : Object

        The terminal that the flight arrives at.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

      • arrivalTime : Object

        The date and time the flight is scheduled to arrive at the arrivalAirport.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Format: date-time

      • boardingPolicy : Object

        The boarding policy for the airline and flight. If unset, Google will use zoneBased.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Possible values: boardingPolicyOther, groupBased, zoneBased

      • boardingTime : Object

        The date and time when the flight boards.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Format: date-time

      • departureAirport : ObjectREQUIRED

        The airport that the flight departs from.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

      • departureGate : Object

        The airport gate the flight departs from.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

      • departureTerminal : Object

        The airport terminal the flight departs from.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

      • departureTime : Object

        The date and time when the flight is scheduled to depart.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Format: date-time

      • flightNumber : ObjectREQUIRED

        The flight number.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

      • flightStatus : Object

        The status of the flight.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Possible values: active, cancelled, landed, redirected, scheduled

      • seatingPolicy : Object

        The seating policy for the airline and flight. If unset, Google will use cabinBased.

        OBJECT PROPERTIES
        • label : String

          A label representing the field on the pass.

        • value : String

          Possible values: cabinBased, classBased, seatClassPolicyOther, tierBased

    • passGroups : Array [String]

      An array of eventId or eventExternalId values representing a group. You can reference the group to make changes to all associated events.

      You can set pass groups when creating an event or when creating an event ticket adaptive link.

Flight Response

Example Flight Response Object

{
    "flightId": "<uaFlightId>",
    "flightExternalId": "<flightExternalId>",
    "projectId": "<uaProjectId>",
    "projectExternalId": "<projectExternalId>",
    "createdAt": "2018-07-05T09:12:32Z",
    "updatedAt": "2018-07-05T09:12:32Z",
    "passGroups": ["sfo-pdx-20180730"],
    "fields": {
      "flightNumber": {
        "label": "Flight Number",
        "value": "815"
      },
      "airlineCode": {
        "label": "Airline Code",
        "value": "WN"
      },
      "airlineName": {
        "label": "Airline Name",
        "value": "Southwest Airlines"
      },
      "departureAirport": {
        "label": "San Francisco",
        "value": "SFO"
      },
      "departureGate": {
        "label": "Gate #",
        "value": "25"
      },
      "boardingTime": {
        "label": "Boarding Time",
        "value": "2018-07-30T08:35:00"
      },
      "departureTime": {
        "label": "Departure Time",
        "value": "2018-07-30T09:00:00"
      },
      "arrivalAirport": {
        "label": "Portland",
        "value": "PDX"
      },
      "arrivalGate": {
        "label": "Arrival Gate",
        "value": ""
      },
      "arrivalTime": {
        "label": "Arrival Time",
        "value": "2018-07-30T11:00:00"
      },
      "flightStatus": {
        "label": "Flight Status",
        "value": "scheduled"
      }
    }
  }
  • A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

    All of
    • Flight Object

      A complete flight request object.

      The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.

    • Object

      OBJECT PROPERTIES
      • createdAt : String

        The date and time when the item was created. Format: date-time

      • flightId : Integer

        A unique, auto-generated identifier for the flight. Use this ID to reference the flight in future operations.

      • projectExternalId : String

        The identifier for the external project that the flight is associated with. Presently only if the project uses an external identifier.

      • projectId : String

        The project the flight is associated with.

      • updatedAt : String

        The date and time when the item was last updated. Format: date-time

Passengers

Example Array of Passengers

{
  "passengers": [
    {
      "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
      "fields": {
        "seatNumber": { "value": "13A" },
        "confirmationCode": { "value": "E4583B" },
        "passengerName": { "value": "SMITH/JOE" },
        "specialAssistance": { "label": "Special Assistance", "value": "Wheelchair" },
        "barcode_value": { "value": "12345" },
        "barcodeAltText": { "value": "12345" }
      }
    },
    {
      "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
      "fields": {
        "seatNumber": { "value": "13B" },
        "confirmationCode": { "value": "E4583B" },
        "passengerName": { "value": "SMITH/SALLY" },
        "barcode_value": { "value": "12346" },
        "barcodeAltText": { "value": "12346" }
      }
    },
    {
      "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
      "fields": {
        "seatNumber": { "value": "13C" },
        "confirmationCode": { "value": "E4583B" },
        "passengerName": { "value": "SMITH/SAM" },
        "barcode_value": { "value": "12347" },
        "barcodeAltText": { "value": "12347" }
      }
    }
  ]
}
  • An array of objects, each object representing a passenger/seat on a flight. Passengers are a part of the payload for boarding pass adaptive links.

    ARRAY ITEM
    • OBJECT PROPERTIES
      • adaptiveLinkExternalId : String

        The external ID you want to assign to a passenger’s adaptive link.

      • fields : Object

        OBJECT PROPERTIES
        • barcodeAltText : Pass Field Updates

          Like other pass creation operations, when providing barcode information, you need only provide the value.

        • barcode_value : Pass Field Updates

          Like other pass creation operations, when providing barcode information, you need only provide the value.

        • boardingDoor : Object

          The door the passenger uses to board the plane.

          OBJECT PROPERTIES
          • value : String

            Possible values: front, back

        • boardingGroup : Object

          The boarding group for the passenger.

          OBJECT PROPERTIES
          • value : String

        • boardingPosition : Object

          The value of the boarding position.

          OBJECT PROPERTIES
          • value : String

        • boardingPrivilegeImage : Object

          The URL of the image; recommended size is 80px tall by 80-780px wide.

          OBJECT PROPERTIES
          • value : String

            Format: url

        • confirmationCode : StringREQUIRED

          Confirmation code needed to check into this flight. This is the number that the passenger would enter into a kiosk at the airport to look up the flight and print a boarding pass.

        • eticketNumber : Object

          The eTicket Number for the passenger’s boarding pass.

          OBJECT PROPERTIES
          • value : String

        • frequentFlyerNumber : Object

          The passenger’s frequent flyer number.

          OBJECT PROPERTIES
          • value : String

        • frequentFlyerProgramName : Object

          The name of the frequent flyer program the passenger belongs to.

          OBJECT PROPERTIES
          • value : String

        • passengerName : ObjectREQUIRED

          The name of the passenger as it will appear on the pass.

          OBJECT PROPERTIES
          • value : String

        • seatClass : Object

          The passenger’s seat class.

          OBJECT PROPERTIES
          • value : String

        • seatNumber : Object

          The seat number the passenger will sit in.

          OBJECT PROPERTIES
          • value : String

        • The URL of the logo for the security program. Recommended size is 80 px tall and 80–780 px wide.

          Format: url

        • sequenceNumber : Object

          The sequence number on the boarding pass. This usually matches the sequence in which the passengers checked in.

          OBJECT PROPERTIES
          • value : String

        • sharingStatus : Object

          A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.

          On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.

          You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • value : StringREQUIRED

            Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.

            Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

Event Tickets

Schemas for creating events and event ticket adaptive links. An event ticket includes both event information and an array of attendees.

Attendees

Array of Attendees

{
  "attendees": [
     {
        "adaptiveLinkExternalId": "<adaptiveLinkExternalId4>",
        "fields": {
           "ticketHolderName": { "label": "Name", "value":"SMITH/SAM" },
           "seat": { "value":"11" },
           "ticketType": { "value":"VIP" },
           "ticketNumber": { "value":"20595923485" },
           "barcode_value": { "value": "1237" },
           "barcodeAltText": { "value": "1237" },
           "faceValue": { "value": "100" }
        }
     },
     {
        "adaptiveLinkExternalId": "<adaptiveLinkExternalId5>",
        "fields":{
           "ticketHolderName": { "label": "Name", "value":"SMITH/MARY" },
           "seat": { "value":"12" },
           "ticketType": { "value":"VIP" },
           "ticketNumber": { "value":"20595923486" },
           "barcode_value": { "value": "1238" },
           "barcodeAltText": { "value": "1238" },
           "faceValue": { "value": "100" }
        }
     },
     {
        "fields": {
           "ticketHolderName": { "label": "Name", "value":"SMITH/SARA" },
           "seat":{ "value":"13" },
           "ticketType":{ "value":"VIP" },
           "ticketNumber":{ "value":"20595923487" },
           "barcode_value": { "value": "1239" },
           "barcodeAltText": { "value": "1239" },
           "faceValue": { "value": "100" }
        }
     }
  ]
}
  • An array of attendees for an event. Each object in the array represents a single attendee.

    ARRAY ITEM
    • OBJECT PROPERTIES
      • adaptiveLinkExternalId : String

        A custom identifier for a particular attendee’s adaptive link.

      • fields : Object

        The information about or for the individual attendee’s event ticket.

        OBJECT PROPERTIES
        • barcodeAltText : Pass Field Updates

          Like other pass creation operations, when providing barcode information,

          you need only provide the value.

        • barcode_value : Pass Field Updates

          Like other pass creation operations, when providing barcode information, you need only provide the value.

        • confirmationCode : Object

          The confirmation code for the ticket holder’s event reservation.

          OBJECT PROPERTIES
          • label : String

            The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

          • value : String

            The value for this field.

        • faceValue : Object

          The face value of the ticket, matching what would be printed on a physical version of the ticket.

          OBJECT PROPERTIES
          • currencyCode : String

            Determines the type of currency if the formatType is set to currency.

            Possible values: USD, EUR, CNY, JPY, GPB, RUB, AUD, CHF, CAD, HKD, SEK, NZD, KRW, SGD, NOK, MXN, INR

          • micros : Integer

            The face value amount in micros. Format: int64

        • gate : Object

          The gate the ticket holder should use to enter the venue.

          OBJECT PROPERTIES
          • label : String

            The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

          • value : String

            The value for this field.

        • row : Object

          The row of the ticket holder’s seat.

          OBJECT PROPERTIES
          • label : String

            The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

          • value : String

            The value for this field.

        • seat : Object

          The seat number for the ticket holder.

          OBJECT PROPERTIES
          • label : String

            The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

          • value : String

            The value for this field.

        • section : Object

          The section that the ticket holder’s seat is in.

          OBJECT PROPERTIES
          • label : String

            The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

          • value : String

            The value for this field.

        • sharingStatus : Object

          A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.

          On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.

          You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • value : StringREQUIRED

            Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.

            Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

        • ticketHolderName : Object

          The name of the ticket holder, if the ticket is assigned to a person.

          OBJECT PROPERTIES
          • label : String

            The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

          • value : String

            The value for this field.

        • ticketNumber : Object

          The number of the ticket.

          OBJECT PROPERTIES
          • label : String

            The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

          • value : String

            The value for this field.

        • ticketType : Object

          The type of ticket, if applicable. Use this field to include information like “Adult”, “Child”, “VIP”, etc.

          OBJECT PROPERTIES
          • label : String

            The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

          • value : String

            The value for this field.

Event Request

Example Event Request Object

{
  "passGroups": ["giants_2019-09-25"],
  "fields": {
    "eventName": {
      "label": "Event",
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "label": "Venue",
      "value": "AT&T Park"
    },
    "venueAddress": {
      "label": "Address",
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T08:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T09:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T11:00:00"
    }
  }
}
  • Represents an event scheduled at a specific time and venue.

    OBJECT PROPERTIES
    • fields : ObjectREQUIRED

      Contains the objects representing an event.

      OBJECT PROPERTIES
      • doorsOpen : Object

        The date and time when ticket holders can begin to enter the venue.

        OBJECT PROPERTIES
        • label : String

          The title for this event field as you want it to appear on a pass. Defaults to Doors Open.

        • value : String

          Format: date-time

      • endTime : Object

        The date and time when the event ends.

        OBJECT PROPERTIES
        • label : String

          The title for this event field, as you want it to appear on a pass. Defaults to End Time.

        • value : String

          Format: date-time

      • eventName : ObjectREQUIRED

        The value represents the event name.

        OBJECT PROPERTIES
        • label : String

          The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

        • value : String

      • startTime : Object

        The date and time when the event begins.

        OBJECT PROPERTIES
        • label : String

          The title for this event field, as you want it to appear on a pass. Defaults to Start Time.

        • value : String

          Format: date-time

      • venueAddress : ObjectREQUIRED

        The address of the venue.

        OBJECT PROPERTIES
        • label : String

          The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

        • value : String

      • venueTitle : ObjectREQUIRED

        The name of the venue where the event will take place.

        OBJECT PROPERTIES
        • label : String

          The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.

        • value : String

    • passGroups : Array [String]

      An array of eventId or eventExternalId values representing a group. You can reference the group to make changes to all associated events.

      You can set pass groups when creating an event or when creating an event ticket adaptive link.

Event Response

Example Response Object

{
  "eventId": "<uaEventId>",
  "eventExternalId": "<eventExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-09-24T09:12:32Z",
  "updatedAt": "2018-09-24T09:12:32Z",
  "passGroups": ["giants_2019-09-25"],
  "fields": {
    "eventName": {
      "label": "Event",
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "label": "Venue",
      "value": "AT&T Park"
    },
    "venueAddress": {
      "label": "Address",
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T08:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T09:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T11:00:00"
    }
  }
}
  • An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

    All of
    • Event Request

      Represents an event scheduled at a specific time and venue.

    • Object

      OBJECT PROPERTIES
      • createdAt : String

        The date and time when the item was created. Format: date-time

      • eventExternalId : String

        An external identifier for an event. You can only assign an external identifier when creating an event. If you do assign an external identifier, requests for events or passes referencing the event will return the external ID in addition to the eventId created within Airship.

      • eventId : Integer

        The Airship-created identifier for an event.

      • projectExternalId : String

        Returned if you created the event using an external ID for the project.

      • projectId : Integer

        The ID of the project. Use this ID to reference your project in the API.

      • updatedAt : String

        The date and time when the item was last updated. Format: date-time

Event Ticket Adaptive Link Request

Example Event Ticket Request Object

{
    "iosTemplateExternalId": "<iosTemplateExternalId>",
    "androidTemplateExternalId": "<androidTemplateExternalId>",
    "payload": {
        "events": [
            {
                "eventExternalId": "<eventExternalId1>",
                "passGroups": [
                    "giants_2019-09-25"
                ],
                "fields": {
                    "eventName": {
                        "value": "LA Dodgers at SF Giants"
                    },
                    "venueTitle": {
                        "value": "AT&T Park"
                    },
                    "venueAddress": {
                        "label": "Address",
                        "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
                    },
                    "doorsOpen": {
                        "label": "Doors Open",
                        "value": "2019-09-25T08:35:00"
                    },
                    "startTime": {
                        "label": "Start Time",
                        "value": "2019-09-25T09:00:00"
                    },
                    "endTime": {
                        "label": "End Time",
                        "value": "2019-09-25T11:00:00"
                    }
                },
                "attendees": [
                    {
                        "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
                        "fields": {
                            "ticketHolderName": {
                                "label": "Name",
                                "value": "SMITH/JOE"
                            },
                            "seat": {
                                "value": "33"
                            },
                            "ticketType": {
                                "value": "VIP"
                            },
                            "barcode_value": {
                                "value": "1234"
                            },
                            "barcodeAltText": {
                                "value": "1234"
                            },
                            "faceValue": {
                                "value": "50"
                            }
                        }
                    },
                    {
                        "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
                        "fields": {
                            "ticketHolderName": {
                                "label": "Name",
                                "value": "SMITH/SALLY"
                            },
                            "seat": {
                                "value": "34"
                            },
                            "ticketType": {
                                "value": "VIP"
                            },
                            "barcode_value": {
                                "value": "1235"
                            },
                            "barcodeAltText": {
                                "value": "1235"
                            },
                            "faceValue": {
                                "value": "50"
                            }
                        }
                    },
                    {
                        "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
                        "fields": {
                            "ticketHolderName": {
                                "label": "Name",
                                "value": "SMITH/JACK"
                            },
                            "seat": {
                                "value": "35"
                            },
                            "ticketType": {
                                "value": "VIP"
                            },
                            "barcode_value": {
                                "value": "1236"
                            },
                            "barcodeAltText": {
                                "value": "1236"
                            },
                            "faceValue": {
                                "value": "50"
                            }
                        }
                    }
                ]
            }
        ]
    }
}
  • An event ticket requires similar information to other adaptive link types, but does not support some of the same fields, and requires event and attendee information.

    Like other adaptive links, you must provide the id or externalId of an iOS or Android template. You can create the event within this request or specify an event by eventId or eventExternalId. In either case, you must also provide an array of attendees for the event.

    All of
    • Object

      OBJECT PROPERTIES
      • androidTemplateExternalId : String

        The custom identifier of the Google template for passes issued from this adaptive link.

      • androidTemplateId : String

        The Google template for passes issued from the adaptive link.

      • availablePasses : Integer

        The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.

      • iosTemplateExternalId : String

        The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.

      • iosTemplateId : String

        The iOS template for passes issued from the adaptive link.

      • isPersonalized : Boolean

        If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters, isPersonalized is automatically set to true.

        If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When isPersonalized is false, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link.

      • landingPageUrl : String

        The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason. Format: url

      • parameterEncoding : String

        When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.

        Possible values: base64

    • Object

      OBJECT PROPERTIES
      • payload : Object

        OBJECT PROPERTIES
        • events : Array [Any]

          Each object in the array represents an event. Each event object must specify the eventId or eventExternalId of an existing event, or contain the fields object sufficient to create a new event.

          You can also provide the eventExternalId in conjunction with the fields object to assign an eventExternalId to a new event.

          ARRAY ITEM
          • One of
            • Existing Event by ID

              If you specify the eventId or eventExternalId of an existing event, you need only provide the attendees for the event ticket.

              All of
              • One of
                • Event ID : Object

                  OBJECT PROPERTIES
                  • eventId : Integer

                    The Airship-created identifier for an event.

                • External Event ID : Object

                  OBJECT PROPERTIES
                  • eventExternalId : String

                    An external identifier for an event. You can only assign an external identifier when creating an event. If you do assign an external identifier, requests for events or passes referencing the event will return the external ID in addition to the eventId created within Airship.

              • Object

                OBJECT PROPERTIES
                • attendees : Attendees

                  An array of attendees for an event. Each object in the array represents a single attendee.

                • passGroups : Array [String]

                  An array of eventId or eventExternalId values representing a group. You can reference the group to make changes to all associated events.

                  You can set pass groups when creating an event or when creating an event ticket adaptive link.

            • Create New Event

              If creating an event, you can provide an external ID for the event. You must then provide a complete event object.

              All of
              • Object

                OBJECT PROPERTIES
                • eventExternalId : String

                  An external identifier for an event. You can only assign an external identifier when creating an event. If you do assign an external identifier, requests for events or passes referencing the event will return the external ID in addition to the eventId created within Airship.

              • Event Request

                Represents an event scheduled at a specific time and venue.

              • Object

                OBJECT PROPERTIES
                • attendees : Attendees

                  An array of attendees for an event. Each object in the array represents a single attendee.

Passes

Schemas used when creating passes (as opposed to adaptive links).

Beacon Object (iOS Only)

Example Beacon Object

{
  "uuid": "55502220-A123-A88A-F321-555A444B333C",
  "relevantText": "You are near the Ship",
  "major": 2,
  "minor": 346
}
  • Associates a pass with an iBeacon. Apple Wallet supports up to 10 beacons per pass. When the passholder comes into proximity with an iBeacon bearing the same UUID, the pass becomes relevant (displayed on the lock screen).

    OBJECT PROPERTIES
    • major : IntegerREQUIRED

      Major identifier of a beacon. Format: int32

    • minor : IntegerREQUIRED

      Minor identifier of a beacon. Format: int32

    • relevantText : StringREQUIRED

      Text displayed on the lock screen.

    • uuid : StringREQUIRED

      Unique identifier of a beacon.

Google Wallet Pass Request

Example Google Pass Request

{
    "headers": {
         "expirationDate":{
            "value":"2014-08-20T9:41-08:00"
         },
         "barcodeAltText": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         },
         "barcode_value": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         }
    },
    "fields": {
      "Coupon": {
         "changeMessage": "Enjoy %@ off your next order!",
         "value": "20%",
         "label": "Coupon"
      },
      "SiteAddress": {
         "changeMessage": "Check out things we think you would like at %@",
         "value": "https://www.store.com/new?custnumb=123456",
         "label": "personal deals"
      },
      "InStore": {
         "changeMessage": "Or visit your nearest store at %@",
         "value": "1234 Fake St.",
         "label": "nearestStore"
      }
    },
    "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"
        }
    ],
    "publicUrl": {
        "type": "single"
    }
}
  • A pass for Google Wallet. Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module that the field belongs to.

    Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

    OBJECT PROPERTIES
    • fields : Object

      Fields for the pass. The template defines a field’s location on the pass and its default value(s). When creating a pass, you only need to populate the fields you want to update, and even then, you only need to provide the value you want to change for the field and the changeMessage if you want to notify passholders of the change in the value.

      OBJECT PROPERTIES
      • * : Pass Field Updates

        When updating a field on a pass or an adaptive link, you need only provide the following items. You cannot update the position of the field or other information held by the template — only the field label, value, and the message the user receives when their pass is updated.

    • headers : Object

      Include objects from the template headers object if you want to change the label, value, or changeMessage for fields in the pass header — like barcodes and titles.

      OBJECT PROPERTIES
      • expirationDate : String

        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.

        Format: date-time

      • Google Headers : Object

        Fields appearing in the headers object for a Google pass template. Header fields typically follow the same model as other fields for Google Wallet templates and passes, but often have specific value, fieldType, and formatType values.

        OBJECT PROPERTIES
        • background_color : Object

          Sets the background color for the pass.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to topLevel for color and text headers.

              Possible values: topLevel

            • value : String

              The color objects take an rgb value in the format rgb(255, 255, 255).

              Format: rgb Pattern: rgb\({1,255}, {1,255}, {1,255}\)

        • background_image : Object

          A background image for the pass.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

        • barcodeAltText : Object

          Alternate text displayed below the barcode.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The alternate text for the barcode on the template.

        • barcode_encoding : Object

          The encoding format for the barcode.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              Presently, iso-8859-1 is the only supported value.

              Possible values: iso-8859-1

        • barcode_type : Object

          The type of barcode supported by the template. This value must be the same as the barcode_type set at the project level.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              Presently, iso-8859-1 is the only supported value.

              Possible values: pdf417, aztec, code128, qr, upc-a, ean-13, code-39

        • barcode_value : Object

          The default value for the barcode used by the template.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              This value is a default for the barcode. You may set a new or personalized value when creating adaptive links or passes.

        • The footer image for a template.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • Indicates that the value is an image.

              Possible values: image

            • Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • The URL for the header image.

              Format: url

        • foreground_color : Object

          Sets the foreground color for the template.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to topLevel for color and text headers.

              Possible values: topLevel

            • value : String

              The color objects take an rgb value in the format rgb(255, 255, 255).

              Format: rgb Pattern: rgb\({1,255}, {1,255}, {1,255}\)

        • header : Object

          Sets the generic pass header. Required for the generic pass type.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to topLevel for text headers.

              Possible values: topLevel

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              Header text field.

              Format: text

        • icon_image : Object

          The icon image for the template.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

        • logo_image : Object

          Specifies the template logo image.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

        • logo_text : Object

          Sets the text under the logo image.

          OBJECT PROPERTIES
          • fieldType : String

            Indicates that the value is an image.

            Possible values: image

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            The alternate text for the logo_image.

        • sharingStatus : Object

          A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.

          On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.

          You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.

          OBJECT PROPERTIES
          • changeMessage : String

            The message that appears when you update this field.

          • value : StringREQUIRED

            Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.

            Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

        • strip_image : Object

          The image residing in the barcode strip.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

        • subheader : Object

          Sets the optional generic pass subheader.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to topLevel for text headers.

              Possible values: topLevel

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              Header text field.

              Format: text

        • suppress_strip_shine : Object

          Determines whether or not to suppress the strip shine effect on barcodes.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Set to barcode for all barcode headers.

              Possible values: barcode

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : Boolean

        • thumbnail_image : Object

          An object containing the URL for the thumbnail image.

          All of
          • Optional Fields for Google Headers

            Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

          • Object

            OBJECT PROPERTIES
            • fieldType : String

              Indicates that the value is an image.

              Possible values: image

            • formatType : String

              Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

              In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

              Possible values: String

            • value : String

              The URL for the header image.

              Format: url

    • locations : Array [Location Object]

      A list of locations associated with a pass.

    • publicUrl : ObjectREQUIRED

      A public URL from which users can download a pass.

      For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify type: single in the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.

      For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.

      OBJECT PROPERTIES
      • installs : Integer

        The number of users who have installed the pass from the URL specified in the path field.

      • path : String

        The URL for the pass.

      • type : StringREQUIRED

        Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.

        Possible values: single, multiple

      • used : Boolean

        If true, a user has accessed the path URL.

    • templateId : Integer

      The identifier for the template. You can recall the template by ID in other operations.

Google Wallet Pass Response

Example Google Pass Response

{
  "createdAt": "2018-10-25T19:13:14Z",
  "headers": {
      "background_color": {
          "ignoresTimeZone": null,
          "changeMessage": null,
          "label": "",
          "hideEmpty": false,
          "formatType": "String",
          "value": "#006491",
          "fieldType": "topLevel",
          "required": false
      },
      "strip_image": {
          "ignoresTimeZone": null,
          "changeMessage": null,
          "label": "",
          "hideEmpty": false,
          "formatType": "String",
          "value": "https://s3.amazonaws.com/passtools_prod/1169167/images/587ac4e3d188b0fcd4f05038d8814fefd82ac834_iOS_Logo_320x100_WHITE.png",
          "fieldType": "image",
          "required": false
      },
      "expirationDate": {
          "ignoresTimeZone": null,
          "changeMessage": null,
          "label": "",
          "hideEmpty": false,
          "formatType": "String",
          "value": "2019-10-25T19:13:14Z",
          "fieldType": "topLevel",
          "required": false
      }
  },
  "serialNumber": "06bad8bd-b399-4c86-83b6-06fcee2e52b6",
  "uaEntityId": "9e3bf713-f6e6-4d6e-b2d4-c9ab6028892e",
  "id": "47400533",
  "templateId": "63621",
  "fields": {
      "image": {
          "ignoresTimeZone": null,
          "title.string": "https://s3.amazonaws.com/passtools_prod/1169167/images/9af688aea35f473e29ca187438c12083202f1eeb_Android_Logo_660x660.png",
          "hideEmpty": false,
          "formatType": "String",
          "fieldType": "titleModule",
          "description.string": "Logo Image"
      },
      "Details": {
          "col": 0,
          "ignoresTimeZone": null,
          "header": "Coupon Details",
          "hideEmpty": false,
          "row": 0,
          "formatType": "String",
          "body": "25% off when you spend £20 or more online using code WNTRBLOG",
          "fieldType": "textModulesData"
      },
      "FinePrint": {
          "col": 0,
          "ignoresTimeZone": null,
          "header": "Terms & Conditions ",
          "hideEmpty": false,
          "row": 0,
          "formatType": "String",
          "body": "Please go to http://www.dominos.co.uk and click on “Boring Legal Stuff”",
          "fieldType": "textModulesData"
      },
      "offerModule": {
          "multiUserOffer": false,
          "redemptionChannel": "both",
          "provider": "Domino's Snap Offer",
          "endTime": "2018-01-31T00:00:00.000Z"
      },
      "Merchant Website": {
          "ignoresTimeZone": null,
          "description": "Visit Us Online",
          "hideEmpty": false,
          "formatType": "URL",
          "uri": "https://www.dominos.co.uk/?vc=WNTRBLOG",
          "fieldType": "linksModuleData",
          "order": 1
      },
      "imageModulesData": {
          "image": "https://s3.amazonaws.com/passtools_prod/1169167/images/834420d3cbf287f56c8be46806e58e23e8296e94_Android_Hero_1032x336_Opt1.png",
          "ignoresTimeZone": null,
          "imageDescription": "Logo Image",
          "hideEmpty": false,
          "formatType": "String",
          "fieldType": "imageModulesData"
      },
      "Coupon Title": {
          "col": 0,
          "ignoresTimeZone": null,
          "title.string": "Coupon",
          "hideEmpty": false,
          "row": 0,
          "formatType": "String",
          "fieldType": "titleModule",
          "description.string": "25% Off Online "
      }
  },
  "url": "https://wallet-api.urbanairship.com/v1/pass/47400533/download",
  "updatedAt": "2018-10-25T19:13:14Z",
  "tags": [],
  "status": "installed"
}
  • A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.

    Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module (an object) that the field belongs to.

    Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.

    OBJECT PROPERTIES
    • createdAt : String

      The date and time when the item was created. Format: date-time

    • externalId : String

      The external ID for the pass, returned only if you created the pass using an external ID.

    • fields : Object

      Contains all populated fields from the template. The fieldType within each object indicates the module it belonged to.

      While all fields take a similar shape, the response may contain different keys to represent the value or label from the originating template field. This has to do with the way that Google Wallet interprets templates and passes.

      OBJECT PROPERTIES
      • offerModule : Object

        Specific to google coupons, this module contains information about redeeming the coupon.

        OBJECT PROPERTIES
        • endTime : String

          The expiration date for the offer. Format: date-time

        • multiUseOffer : Boolean

          Indicates whether the coupon/offer is available for multiple users or just a single user.

        • provider : String

          The offer provider name.

        • redemptionChannel : String

          Indicates whether the user can redeem the offer at a physical location or online.

          Possible values: online, instore, both, temporaryPriceReduction

      • * : Object

        A field on a pass contains information from the template noting the type of field and other positioning information. The value and label keys from the template are represented by keys native to each google fieldType. The label is sometimes represented as header, title.string, etc. ; the value is sometimes represented as body, description.string, uri, etc.

        OBJECT PROPERTIES
        • col : IntegerDEPRECATED

          Determines vertical location/order within the fieldType. Use order instead.

        • fieldType : String

          Represents the module or parent object that a field belongs to on a template.

          Possible values: titleModule, acctModule, infoModuleData, textModulesData, linkModulesData, pointsModule, notAssigned, loyaltyPoints

        • formatType : String

          The input format for the field.

          Possible values: String, Number, URL, Date, Currency, Phone, Email

        • hideEmpty : Boolean

          If true, the field is hidden if empty.

        • order : Integer

          The order of fields with the same fieldType (Apple) or belonging to the same module (Google). If there are multiple fields with the same fieldType, order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most position.

        • row : IntegerDEPRECATED

          Determines horizontal location/order within the fieldType. Use order instead.

    • headers : Object

      Fields appearing in the headers object for a Google pass template. Header fields typically follow the same model as other fields for Google Wallet templates and passes, but often have specific value, fieldType, and formatType values.

      OBJECT PROPERTIES
      • background_color : Object

        Sets the background color for the pass.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Set to topLevel for color and text headers.

            Possible values: topLevel

          • value : String

            The color objects take an rgb value in the format rgb(255, 255, 255).

            Format: rgb Pattern: rgb\({1,255}, {1,255}, {1,255}\)

      • background_image : Object

        A background image for the pass.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Indicates that the value is an image.

            Possible values: image

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            The URL for the header image.

            Format: url

      • barcodeAltText : Object

        Alternate text displayed below the barcode.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Set to barcode for all barcode headers.

            Possible values: barcode

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            The alternate text for the barcode on the template.

      • barcode_encoding : Object

        The encoding format for the barcode.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Set to barcode for all barcode headers.

            Possible values: barcode

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            Presently, iso-8859-1 is the only supported value.

            Possible values: iso-8859-1

      • barcode_type : Object

        The type of barcode supported by the template. This value must be the same as the barcode_type set at the project level.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Set to barcode for all barcode headers.

            Possible values: barcode

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            Presently, iso-8859-1 is the only supported value.

            Possible values: pdf417, aztec, code128, qr, upc-a, ean-13, code-39

      • barcode_value : Object

        The default value for the barcode used by the template.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Set to barcode for all barcode headers.

            Possible values: barcode

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            This value is a default for the barcode. You may set a new or personalized value when creating adaptive links or passes.

      • The footer image for a template.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • Indicates that the value is an image.

            Possible values: image

          • Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • The URL for the header image.

            Format: url

      • foreground_color : Object

        Sets the foreground color for the template.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Set to topLevel for color and text headers.

            Possible values: topLevel

          • value : String

            The color objects take an rgb value in the format rgb(255, 255, 255).

            Format: rgb Pattern: rgb\({1,255}, {1,255}, {1,255}\)

      • header : Object

        Sets the generic pass header. Required for the generic pass type.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Set to topLevel for text headers.

            Possible values: topLevel

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            Header text field.

            Format: text

      • icon_image : Object

        The icon image for the template.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Indicates that the value is an image.

            Possible values: image

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            The URL for the header image.

            Format: url

      • logo_image : Object

        Specifies the template logo image.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Indicates that the value is an image.

            Possible values: image

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            The URL for the header image.

            Format: url

      • logo_text : Object

        Sets the text under the logo image.

        OBJECT PROPERTIES
        • fieldType : String

          Indicates that the value is an image.

          Possible values: image

        • formatType : String

          Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

          In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

          Possible values: String

        • value : String

          The alternate text for the logo_image.

      • sharingStatus : Object

        A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.

        On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.

        You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.

        OBJECT PROPERTIES
        • changeMessage : String

          The message that appears when you update this field.

        • value : StringREQUIRED

          Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.

          Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

      • strip_image : Object

        The image residing in the barcode strip.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Indicates that the value is an image.

            Possible values: image

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            The URL for the header image.

            Format: url

      • subheader : Object

        Sets the optional generic pass subheader.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Set to topLevel for text headers.

            Possible values: topLevel

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            Header text field.

            Format: text

      • suppress_strip_shine : Object

        Determines whether or not to suppress the strip shine effect on barcodes.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Set to barcode for all barcode headers.

            Possible values: barcode

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : Boolean

      • thumbnail_image : Object

        An object containing the URL for the thumbnail image.

        All of
        • Optional Fields for Google Headers

          Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Object

          OBJECT PROPERTIES
          • fieldType : String

            Indicates that the value is an image.

            Possible values: image

          • formatType : String

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String

          • value : String

            The URL for the header image.

            Format: url

    • id : Integer

      The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

    • publicUrl : Object

      A public URL from which users can download a pass.

      For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify type: single in the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.

      For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.

      OBJECT PROPERTIES
      • installs : Integer

        The number of users who have installed the pass from the URL specified in the path field.

      • path : String

        The URL for the pass.

      • type : StringREQUIRED

        Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.

        Possible values: single, multiple

      • used : Boolean

        If true, a user has accessed the path URL.

    • serialNumber : String

      Format: uuid

    • status : String

      Indicates whether a pass has been installed or not.

      Possible values: installed, not_been_installed

    • tags : Array [String]

      Tags associated with the pass.

    • uaEntityId : String

      Format: uuid

    • updatedAt : String

      The date and time when the item was last updated. Format: date-time

    • url : String

      The URL for the pass. Format: url

Apple Wallet Pass Request

Example Pass for Apple Wallet

{
    "headers": {
        "expirationDate": {
           "value": "2014-08-20T09:41-08:00"
         },
         "barcodeAltText": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         },
         "barcode_value": {
            "changeMessage": null,
            "value": "abc1234567890",
            "label": ""
         }
    },
    "fields": {
      "Coupon": {
         "changeMessage": "Enjoy %@ off your next order!",
         "value": "20%",
         "label": "Coupon"
      },
      "SiteAddress": {
         "changeMessage": "Check out things we think you would like at %@",
         "value": "https://www.store.com/new?custnumb=123456",
         "label": "personal deals"
      },
      "InStore": {
         "changeMessage": "Or visit your nearest store at %@",
         "value": "1234 Fake St.",
         "label": "nearestStore"
      },
      "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
        }
    ],
    "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"
        }
    ],
    "publicUrl": {
        "type": "single"
    }
}
  • A pass for Apple Wallet.

    OBJECT PROPERTIES
    • beacons : Array [Beacon Object (iOS Only)]

      Beacons for an Apple pass.

    • fields : Object

      Fields for an Apple wallet pass. Provide only the field objects and values you want to differentiate or personalize from the template.

      OBJECT PROPERTIES
      • Field Name (string) : Pass Field Updates

        When updating a field on a pass or an adaptive link, you need only provide the following items. You cannot update the position of the field or other information held by the template — only the field label, value, and the message the user receives when their pass is updated.

    • headers : Object

      Headers on an Apple Wallet pass. Provide only the header objects and values you want to differentiate or personalize from the template. See Apple Template Headers for information about available header objects for Apple Wallet templates and passes.

      OBJECT PROPERTIES
      • expirationDate : String

        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.

        Format: date-time

      • sharingStatus : Object

        A field determining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as other fields, you only need to set the value within the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.

        On iOS devices, oneUserOneDevice prohibits sharing ("sharingProhibited": true); all other values allow sharing.

        You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.

        OBJECT PROPERTIES
        • changeMessage : String

          The message that appears when you update this field.

        • value : StringREQUIRED

          Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting: oneUserOneDevice prohibits sharing; all other values allow sharing.

          Possible values: multipleHolders, oneUserAllDevices, oneUserOneDevice

      • Header object with string name. : Pass Field Updates

        When updating a field on a pass or an adaptive link, you need only provide the following items. You cannot update the position of the field or other information held by the template — only the field label, value, and the message the user receives when their pass is updated.

    • locations : Array [Location Object]

      A list of locations associated with a pass.

    • nfc : Object

      If your Apple certificate is NFC-enabled, and your terminals use Apple’s Value Added Services protocol, you can include this object in Loyalty passes to identify passholders and provide their credentials over NFC.

      OBJECT PROPERTIES
      • encryptionPublicKey : StringREQUIRED

        The public encryption key for NFC communications. Use a Base64 encoded X.509 SubjectPublicKeyInfo structure containing a ECDH public key for group P256.

      • message : StringREQUIRED

        The payload for an Apple Pay terminal, 64 bytes or less. Messages longer than 64 bytes are truncated.

    • publicUrl : Object

      A public URL from which users can download a pass.

      For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify type: single in the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.

      For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.

      OBJECT PROPERTIES
      • installs : Integer

        The number of users who have installed the pass from the URL specified in the path field.

      • path : String

        The URL for the pass.

      • type : StringREQUIRED

        Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.

        Possible values: single, multiple

      • used : Boolean

        If true, a user has accessed the path URL.

    • tags : Array [String]

      An array of tags associated with the pass.

    • templateId : Integer

      The identifier for the template. You can recall the template by ID in other operations.

Apple Wallet Pass Response

  • A pass response includes both identifiers and the content of all fields on a pass.

    All of
    • Apple Wallet Pass Request

      A pass for Apple Wallet.

    • Object

      OBJECT PROPERTIES
      • createdAt : String

        The date and time when the item was created. Format: date-time

      • externalId : String

        The external ID for the pass, returned only if you created the pass using an external ID.

      • id : Integer

        The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

      • publicUrl : Object

        A public URL from which users can download a pass.

        For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify type: single in the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.

        For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.

        OBJECT PROPERTIES
        • installs : Integer

          The number of users who have installed the pass from the URL specified in the path field.

        • path : String

          The URL for the pass.

        • type : StringREQUIRED

          Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.

          Possible values: single, multiple

        • used : Boolean

          If true, a user has accessed the path URL.

      • serialNumber : String

        Format: uuid

      • status : String

        Indicates whether a pass has been installed or not.

        Possible values: installed, not_been_installed

      • tags : Array [String]

        Tags associated with the pass.

      • uaEntityId : String

        Format: uuid

      • updatedAt : String

        The date and time when the item was last updated. Format: date-time

      • url : String

        The URL for the pass. Format: url

Project Objects

Request and Response schemas for /project endpoints.

Project Response

Example Project Response

{
  "updatedAt": "2013-06-27T20:55:06.000Z",
  "id": "12345",
  "contextId":"myvWLcm8QN3Iq2K4fXT-Bv",
  "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"
    }
  ],
  "description": "Aztec Barcode",
  "createdAt": "2013-06-27T20:51:02.000Z",
  "settings": {
    "barcode_alt_text": "123456789",
    "barcode_default_value": "123456789",
    "barcode_encoding": "iso-8859-1",
    "barcode_label": "Member ID",
    "barcode_type_text": "Aztec",
    "barcode_type": "aztec"
  },
  "name": "Aztec Barcode",
  "projectType": "loyalty"
}
  • A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.

    All of
    • Project Request

      A project request determines the type of passes you can create and the types of barcode your passes will use.

    • Object

      OBJECT PROPERTIES
      • contextId : String

        Append this value to go.urbanairship.com/projects/ to access your project.

      • createdAt : String

        The date and time when the item was created. Format: date-time

      • externalId : String

        The custom, external identifier of the project. This key only appears if you assigned an external ID to the project.

      • id : Integer

        The identifier for the project, used to reference the project in other payloads.

      • templates : Array [Object]

        An array of templates belonging to the project. When creating a new project, this array is empty.

        ARRAY ITEM
        • All of
          • Object

            OBJECT PROPERTIES
            • createdAt : String

              The date and time when the item was created. Format: date-time

            • id : Integer

              The identifier for the template. You can recall the template by ID in other operations.

            • updatedAt : String

              The date and time when the item was last updated. Format: date-time

          • General Template Headers : Object

            Meta information about templates; this object appears on all templates and identifies templates associated with a project.

            OBJECT PROPERTIES
            • deleted : Boolean

              If true, the template is deleted. You can no longer create passes from this template.

            • description : String

              A description for the template.

            • disabled : Boolean

              If true, the template is disabled; you cannot create new passes for this template until you update the template and enable it again.

            • expiryInfo : Any

              Determine when passes generated from the template should expire.

              One of
              • Expire on a date : Object

                Set the specific expiration date for passes generated from this template. Passes expire at 12:00 AM on the date you provide.

                OBJECT PROPERTIES
                • expiryDate : String

                  The date when passes expire. Format: date

                • expiryTimeZone : String

                  Passes expire at 12:00 AM in the time zone you set.

              • Expire after : Object

                Expire passes generated from this template after the specified number of minutes after creation.

                OBJECT PROPERTIES
                • expiryDuration : Integer

                  The number of days after creation that passes will expire.

              • Never expire : Object

                Passes generated from the template will never expire.

                OBJECT PROPERTIES
                • expireNever : String

                  Any string value (or null) will prevent passes generated from this template from expiring.

            • name : StringREQUIRED

              The name of the template.

            • projectId : Integer

              The ID of the project. Use this ID to reference your project in the API.

            • projectType : String

              The type of pass the template supports; matches the type setting for the parent project.

              Possible values: memberCard, coupon, boardingPass, eventTicket, generic, loyalty, giftCard

            • type : String

              The type of pass the template supports. This value corresponds to the projectType.

              Possible values: memberCard, coupon, boardingPass, eventTicket, generic, loyalty, giftCard

            • vendor : StringREQUIRED

              The device vendor the template is designed for, Apple or Google.

              Possible values: Apple, Google

            • vendorId : IntegerREQUIRED

              Corresponds to the vendor the template supports. 1 indicates an Apple template; 2 indicates a Google template.

              Possible values: 1, 2

      • updatedAt : String

        The date and time when the item was last updated. Format: date-time

Project Request

Example Project Request

{
  "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"
  }
}
  • A project request determines the type of passes you can create and the types of barcode your passes will use.

    OBJECT PROPERTIES
    • description : StringREQUIRED

      A description for the project.

    • name : StringREQUIRED

      The name of your project.

    • projectType : StringREQUIRED

      The type of pass the template supports; matches the type setting for the parent project.

      Possible values: memberCard, coupon, boardingPass, eventTicket, generic, loyalty, giftCard

    • settings : Object

      Contains barcode information for the project.

      OBJECT PROPERTIES
      • barcode_alt_text : String

        Alternate text for the barcode. This text assists the user if they hover over the barcode or the barcode doesn’t render.

      • barcode_default_value : String

        The default value for the barcode. If you do not set a new value when creating a pass, the pass will use this value.

      • barcode_encoding : String

        Barcode encoding is set at the project level and inherited by templates and passes.

        Possible values: iso-8859-1

      • barcode_label : String

        The title of the barcode; appears above the barcode in templates. You can change this value when creating or updating templates or passes.

      • barcode_type : String

        The format of the barcode supported by the project and resulting passes.

        Possible values: pdf417, aztec, code128, qr, upc-a, ean-13, code-39

Audience Selection

Select an audience of passes for scheduled updates or other operations.

Atomic Selector

Example Atomic Selector Tag

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

Example Atomic Selector Segment

{
  "audience": {
      "segment": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a"
  }
}
  • Determines the tag or segment you want to target.

    OBJECT PROPERTIES
    • segment : Array [String]

      The segment ID.

    • tag : Array [String]

      A tag is arbitrary metadata string used to identify and target passes.

Audience Selector

Example pass objects tagged for baseball or basketball and in time zone PST

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

Example pass objects tagged for time zone ET and not for time zone PST

{
  "audience": {
      "AND": [
        {
            "tag": "TZ_ET"
        },
        {
            "NOT": {
              "tag": "TZ_PST"
            }
        }
      ]
  }              
}
  • Determines the passes you want to target.

    One of
    • Compound Selector

      Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. The syntax can be either implicit, using an array of values associated with an atomic selector, or explicit, employing a boolean operator followed by an array of atomic expression objects.

    • Atomic Selector

      Determines the tag or segment you want to target.

    • All : String

      All passes.

      Possible values: all

Compound Selector

Example Implicit OR

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

Example Explicit OR

{
  "audience": {
      "OR": [
        {
            "tag": "apples"
        },
        {
            "tag": "oranges"
        },
        {
            "tag": "bananas"
        }
      ]
  }
}
  • Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. The syntax can be either implicit, using an array of values associated with an atomic selector, or explicit, employing a boolean operator followed by an array of atomic expression objects.

    One of
    • Atomic Selector

      Determines the tag or segment you want to target.

    • Object

      AND selector

      OBJECT PROPERTIES
      • AND : Array [Any]

        ARRAY ITEM
        • One of
          • Compound Selector

            Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. The syntax can be either implicit, using an array of values associated with an atomic selector, or explicit, employing a boolean operator followed by an array of atomic expression objects.

          • Atomic Selector

            Determines the tag or segment you want to target.

    • Object

      OR selector

      OBJECT PROPERTIES
      • OR : Array [Any]

        ARRAY ITEM
        • One of
          • Compound Selector

            Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. The syntax can be either implicit, using an array of values associated with an atomic selector, or explicit, employing a boolean operator followed by an array of atomic expression objects.

          • Atomic Selector

            Determines the tag or segment you want to target.

    • Object

      NOT selector

      OBJECT PROPERTIES
      • NOT : Array [Any]

        ARRAY ITEM
        • One of
          • Compound Selector

            Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. The syntax can be either implicit, using an array of values associated with an atomic selector, or explicit, employing a boolean operator followed by an array of atomic expression objects.

          • Atomic Selector

            Determines the tag or segment you want to target.

Callback Object

Example Callback Object

{
    "passId": 149440311,
    "templateId": 158327,
    "serialNumber": "3388000000005047792.158327_92a3e4d1-5110-3aca-a26e-fb21618aa5f2_149440311",
    "createdAt": "2020-09-11T22:47:22.000Z",
    "updatedAt": "2020-09-11T22:47:22.000Z",
    "externalId": "coolexample",
    "platform": "android"
}
  • OBJECT PROPERTIES
    • createdAt : String

      The date-time when the pass was created. Format: date-time

    • externalId : String

      The external ID for the pass, if set.

    • passId : Integer

      The ID of the pass installed or uninstalled.

    • platform : String

      The platform on which the pass is installed.

      Possible values: android, ios

    • serialNumber : String

      The serial number of the pass. This string is generated by the vendor — Apple or Google.

    • templateId : Integer

      The ID of the template the pass was created from.

    • updatedAt : String

      The date-time when the pass was last updated. Format: date-time

Callback Personalization Object

Example Callback with Personalization Object

{
  "passId": "12345",
  "templateId": "25035",
  "serialNumber": "6779a823-7c8f-4145-a640-c688069a3465",
  "createdAt": "2022-01-23T20:46:50Z",
  "platform": "ios",
  "personalizationInfo": {
      "fullName": "John LastName",
      "givenName": "John",
      "familyName": "LastName",
      "emailAddress": "test@abc.com",
      "postalCode": "95051",
      "ISOCountryCode": "US",
      "phoneNumber": "408-409-1234"
  }
}

Certificate Object

Example Apple Certificate Response

{
    "id": "40adce15-5c52-479d-8620-54c21cd851a6",
    "vendor": "Apple",
    "baseName": "pass.com.myName.test",
    "name": "editable name",
    "comment": "something about this cert",
    "teamIdentifier": "9M8MY376H5",
    "nfcSupport": false,
    "enabled": false,
    "createdAt": "2018-05-26T23:23:21Z",
    "updatedAt": "2019-05-26T22:23:21Z",
    "expired": false,
    "validityStart": "2018-05-26T23:45:00Z",
    "validityEnd": "2019-05-26T23:45:00Z",
    "templates": [
        {"id": 123,"name": "templateName1"},
        {"id": 221,"name": "templateName2"}
    ]
}
  • OBJECT PROPERTIES
    • baseName : String

    • certificate : String

      A base64-encoded string of the p12 certificate with the private key.

    • comment : String

      A description for the certificate.

    • createdAt : String

      The date and time when the item was created. Format: date-time

    • default : Boolean

      If true, the certificate is the default for new projects. If you have multiple certificates and set a new default to true, the current default is set to false.

    • enabled : Boolean

      Indicates whether or not the certificate is in use.

    • expired : Boolean

      If true, the certificate has expired and cannot be used to generate new passes.

    • name : String

      A name for the certificate.

    • nfcSupport : Boolean

      If true, the certificate supports passes that can make use of NFC.

    • password : String

      The password for the p12 file, if the certificate was exported with a password.

    • teamIdentifier : String

    • updatedAt : String

      The date and time when the item was last updated. Format: date-time

    • vendor : String

      The vendor of the certificate. This endpoint presently supports Apple certificates only.

      Possible values: Apple

Pass Field Updates

Example Update to a field called "Coupon"

{
  "Coupon": {
      "changeMessage": "Enjoy %@ off your next order!",
      "value": "20%",
      "label": "Coupon"
   }
}
  • When updating a field on a pass or an adaptive link, you need only provide the following items. You cannot update the position of the field or other information held by the template — only the field label, value, and the message the user receives when their pass is updated.

    OBJECT PROPERTIES
    • changeMessage : String

      The message that appears when you change the value or label for a field. Use %@ to pass variables to the field.

    • label : String

      The field label, usually represented as a title on the pass. Only provide the label if you want to use a different label than is provided by the template.

    • value : StringREQUIRED

      The default value for the field.

Location Object

Example Location Object

{
   "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"
}
  • Represents a location on a pass or an adaptive link.

    Place objects in the locations array to add location information to passes and templates. Updating locations on a pass or template will replace all locations on that pass; if you want to add to the locations on a pass, you must provide all locations already included on the pass and any additional locations you want to add.

    Apple Wallet supports up to 10 locations per pass. If you exceed this limit for an iOS pass, we will use the 10 locations nearest to a user (located by IP address) when they install the pass.

    As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services. This affects a majority of Google passes. Google has not committed to a timetable to resolve the issue and make location triggers available to all Google passes again.

    OBJECT PROPERTIES
    • city : String

      The location city.

    • country : String

      The country abbreviation or name.

    • latitude : NumberREQUIRED

      The latitude of the location. Format: double

    • longitude : NumberREQUIRED

      The longitude of the location. Format: double

    • region : String

      The region or state name.

    • regionCode : String

      The region or zip code.

    • relevantText : String

      An optional value shown as lock screen text for iOS when the device is close to this location.

    • streetAddress1 : String

      The first line of the location address.

    • streetAddress2 : String

      The second line of the location address.

Segment Selector

Segment Selector

{
    "and": [
       {
          "tag": "TZ_PST"
       },
       {
          "not": {
             "tag": "TZ_ET"
          }
       }
    ]
 }
  • Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.

    Any of
    • Object

      AND selector

      OBJECT PROPERTIES
      • and : Array [Any]

        ARRAY ITEM
        • One of
          • Tag Selector : Object

            OBJECT PROPERTIES
            • tag : String

          • Segment Selector

            Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.

    • Object

      OR selector

      OBJECT PROPERTIES
      • or : Array [Any]

        ARRAY ITEM
        • One of
          • Tag Selector : Object

            OBJECT PROPERTIES
            • tag : String

          • Segment Selector

            Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.

    • Object

      NOT selector

      OBJECT PROPERTIES
      • not : Object

        Defines an event value to match.

        ARRAY ITEM
        • Tag Selector

          OBJECT PROPERTIES
          • tag : String