Wallet API

Airship’s REST API for Mobile Wallet projects. Use this API to create Apple Wallet and Google Pay 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 Pay. 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 the Introduction to Passes.

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

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 (.com or .eu/asnapieu.com) associated with your Airship project.

Authentication

  • HTTP Authentication

    basic master

    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.

    e.g., Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0

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.

  • page : Integer

    The page of the search you want to return.

  • order : String

    Determines the order of results.

    Possible values: id, name, createdAt, updatedAt

  • direction : String

    The direction of the result set, ascending or descending.

    Possible values: ASC, DESC

header PARAMETERS
  • Api-Revision : String Required

    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 : String Required

    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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The project you want to look up.

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The project you want to look up.

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 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@xyz.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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

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

          All of
          • #/components/schemas/nfcMerchants

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

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

Add an NFC Merchant

Example Request — APPLE and GOOGLE vendors

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

{
  "vendor": "ANY",
  "merchantName": "testMerchant5",
  "merchantEmail": "test@test.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@test.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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

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

Request Body

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

      All of
      • #/components/schemas/nfcMerchants

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

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

Get an NFC Merchant

Example Request

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

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@test.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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

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

  • merchantId : String Required

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

      All of
      • #/components/schemas/nfcMerchants

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

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

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

{
  "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@xyz.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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

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

  • merchantId : String Required

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

      All of
      • #/components/schemas/nfcMerchants

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

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

Delete an NFC Merchant

Example Request

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

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

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

  • merchantId : String Required

    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.

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.

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

{
  "projects":[
    {
      "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"
    },
    {
      "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/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 template header objects and the fields it contains.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • externalId : String Required

    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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • externalId : String Required

    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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • externalId : String Required

    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

GET /project/id/{projectExternalId}/nfcMerchants

Return all NFC merchant information for a project.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : String Required

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

          All of
          • #/components/schemas/nfcMerchants

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

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

Add an NFC Merchant

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : String Required

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

Request Body

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

      All of
      • #/components/schemas/nfcMerchants

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

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

Get an NFC Merchant

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

Get an individual NFC merchant.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : String Required

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

  • merchantId : String Required

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

      All of
      • #/components/schemas/nfcMerchants

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

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

Update NFC Merchant Information

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

Update your NFC merchant information.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : String Required

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

  • merchantId : String Required

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

      All of
      • #/components/schemas/nfcMerchants

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

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

Delete an NFC Merchant

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : String Required

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

  • merchantId : String Required

    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.

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

{
   "templateId": 12346
}

POST /template/duplicate/{template_id}

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

/v1/template/duplicate/id/(externalId) duplicate the template specified by the external id, and puts the newly created template in the same project.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • template_id : String Required

    The id 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 (Google Template)

{
   "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:

header PARAMETERS
  • Api-Revision : String Required

    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.

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

          • 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 (Google 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 id.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • Id : String Required

    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.

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

      • One of
        • Apple Wallet Template Request

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

        • Google Pay 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

{
   "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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • Id : String Required

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

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • Id : String Required

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

Example Request

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

Example Response

HTTP/1.1 200 OK

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

DELETE /template/{Id}

Delete the specified template.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • Id : String Required

    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

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

{
   "ticketId": 56789
}

PUT /template/{id}/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:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • id : String Required

    Either the id of the template you want to issue an update for or the externalId of the passes you want to update.

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.

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • template_id : String Required

    The template you want to remove a location from.

  • location_id : String Required

    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

[
   {
      "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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • template_id : String Required

    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.

Remove Location from Template

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}

Delete location from template with an External ID.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • externalId : String Required

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

  • locationId : String Required

    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 externalId

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

[
   {
      "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 externalId.

 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • externalId : String Required

    The externalId 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 (Google 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 externalId.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateExternalId : String Required

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

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

      • One of
        • Apple Wallet Template Request

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

        • Google Pay 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

POST 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateExternalId : String Required

    The externalId 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 Pay 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

DELETE /template/id/{templateExternalId}

Delete the specified template.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateExternalId : String Required

    The externalId 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 External Template

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 within the specified project. A template is specific to a vendor platform, Apple or Google.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The project you want to associate your new template with.

  • templateExternalId : String Required

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

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 personalizeable information that you require users to provide when signing up for your loyalty/rewards program.

Get personalization requirements

Example Request

GET /v1/{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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • template_id : String Required

    The loylalty 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_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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • template_id : String Required

    The loylalty 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 personalziation requirements

Example Request

POST /v1/{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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • template_id : String Required

    The loylalty 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_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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • template_id : String Required

    The loylalty 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,
         "availablePasses": 999999,
         "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,
         "availablePasses": 1000000,
         "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,
         "availablePasses": 1000000,
         "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 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,
  "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 201 Created
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",
  "availablePasses": 100000
}

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 : String Required

    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.

Create Boarding Pass or Event Ticket Adaptive Links

Example Boarding Pass Request

POST /v1/links/adaptive/multiple/project/id/<projectExternalId> 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": 201,
      "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",
      "availablePasses": 1000000,
      "flightId": 465,
      "flightExternalId": "<flightExternalId1>",
      "iosPassLinkId": "eb94e8e0-4353-4e0b-bfe9-cfd21c52a540",
      "androidPassLinkId": "41c1ea48-f469-4968-b610-a98629ea19bc"
    },
    {
      "status": 201,
      "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",
      "availablePasses": 1000000,
      "flightId": 465,
      "flightExternalId": "<flightExternalId1>",
      "iosPassLinkId": "5d370e0d-0aa9-45c3-b7ab-eff0a3d4995b",
      "androidPassLinkId": "c60bd6c0-8f1e-4419-abb0-9f6fcb8a6fab"
    },
    {
      "status": 201,
      "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",
      "availablePasses": 1000000,
      "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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The project you want to create the boarding pass in.

Request Body

Operates like a normal adaptive link, execept that the fields object can include an array of flights or events, each with an array of passengers or attendees respsectively.

  • 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. You can provide

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. You can provide

            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/<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",
  "availablePasses": 100000
}

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.

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",
   "availablePasses": 100000
}

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

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.

Generate Pass from Adaptive Link

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.

  • 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • adaptiveLinkId : String Required

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

  • device_type : String Required

    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 return a deep link for the pass; requests for web devices or without the 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

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://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": false,
  "availablePasses": 100000,
  "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 externalId 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 Adapative 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 201 Created
Content-Type: application/json

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": false,
  "availablePasses": 100000,
  "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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectExternalId : String Required

    The externalId of the project containing an adaptive link.

  • adaptiveLinkExternalId : String Required

    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.

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 externalId of the pass you want to get.

  • The externalId 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.

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

          • The serial number of the pass.

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

          • The date and time when the item was created.

          • The private URL for the pass.

  • 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 201 Created
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 externalId of the pass you want to update.

  • The externalId 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://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": false,
  "availablePasses": 100000,
  "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 Adapative 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 201 Created
Content-Type: application/json

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://reach-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "isPersonalized": false,
  "availablePasses": 100000,
  "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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

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

  • adaptiveLinkExternalId : String Required

    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.

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

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

          • The serial number of the pass.

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

          • The date and time when the item was created.

          • The private URL for the pass.

  • 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 externalId 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 Pay. 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.

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

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

GET /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 both installed and 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 : String Required

    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.

          • id : Integer

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

          • serialNumber : String

            The serial number of the pass.

          • templateId : 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 created.

          • url : String

            The private URL for the pass.

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 externalId to passes generated from this endpoint.

Security:

query PARAMETERS
  • expiry : String

    The expiration date for the pass.

    Format: date

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • Id : String Required

    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 Pay Pass Request

      A pass for Google Pay. 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 Pay 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 Pay Pass Response

        A pass response for Google Pay. 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 Pay 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.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • id : String Required

    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 Pay Pass Response

        A pass response for Google Pay. 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 Pay passes are very similar to Apple Wallet passes.

Update Pass

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • id : String Required

    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 Pay Pass Response

        A pass response for Google Pay. 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 Pay 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 externalId to the pass or generate the pass from templates with externalIds. See the appropriate endpoints to assign or use external IDs.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • id : String Required

    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 Pay Pass Request

      A pass for Google Pay. 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 Pay 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 Pay Pass Response

        A pass response for Google Pay. 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 Pay 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • id : String Required

    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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • passId : String Required

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

  • passLocationId : String Required

    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
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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • passId : String Required

    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 created from a template

Example Request

GET /v1/template/1234/passes?status=installed HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Request

{
    "pagination": {
       "start": 0,
       "pageSize": 10,
       "page": 1,
       "direction": "DESC",
       "order": "id"
    },
    "passes": [
       {
          "createdAt": "2020-01-13T20:39:58Z",
          "serialNumber": "f312c188-fe9a-43a3-b328-a024b99d7fe3",
          "uaEntityId": "a642b9fb-9d49-47b0-b968-0f01d39e4975",
          "id": "115445852",
          "templateId": "101060",
          "url": "https://wallet-api.urbanairship.com/v1/pass/115445852/download",
          "updatedAt": "2020-01-13T22:07:27Z",
          "tags": [
             "test_tag"
          ]
       }
    ],
    "count": 1
 }

GET /template/{id}/passes

Get a pass.

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 both installed and 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • id : String Required

    The template you want to look up

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.

          • id : Integer

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

          • serialNumber : String

            The serial number of the pass.

          • templateId : 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 created.

          • url : String

            The private URL for the pass.

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 Pay. 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • externalId : String Required

    The externalId 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 externalId in the path. If there are multiple passes for the externalId 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 oprations against the pass in addition to the standard, unique id given by Wallet.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateExternalId : String Required

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

  • passExternalId : String Required

    The externalId 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 Pay Pass Request

      A pass for Google Pay. 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 Pay 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 Pay Pass Response

        A pass response for Google Pay. 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 Pay 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateId : String Required

    The template the pass is created from.

  • passExternalId : String Required

    The externalId you want to assign to the new 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 Pay Pass Response

        A pass response for Google Pay. 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 Pay 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateId : String Required

    The template the pass is created from.

  • passExternalId : String Required

    The externalId you want to assign to the new pass.

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 Pay Pass Request

      A pass for Google Pay. 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 Pay 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 oprations against the pass like you would use the standard, unique id given by Wallet.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateId : String Required

    The template the pass is created from.

  • passExternalId : String Required

    The externalId you want to assign to the new 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 Pay Pass Request

      A pass for Google Pay. 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 Pay 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 Pay Pass Response

        A pass response for Google Pay. 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 Pay 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

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateId : String Required

    The template the pass is created from.

  • passExternalId : String Required

    The externalId you want to assign to the new pass.

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateId : String Required

    The template of the pass that you want to delete locations from.

  • passExternalId : String Required

    The externalId of the pass you want to delete locations from.

  • locationId : String Required

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

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateId : String Required

    The template of the pass that you want to apply tags to.

  • passExternalId : String Required

    The externalId of the pass you want to apply tags 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • passId : String Required

    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.

          • 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • passId : String Required

    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: 10

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:

header PARAMETERS
  • Api-Revision : String Required

    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.

          • 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • tag : String Required

    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 oepration 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • tag : String Required

    The tag you want to remove.

  • pass : String Required

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

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

GET /tag/{tag}/passes

List the passes associated with the specified tag.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • tag : String Required

    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.

        • id : Integer

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

        • serialNumber : String

          The serial number of the pass.

        • templateId : 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 created.

        • url : String

          The private URL for the pass.

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • tag : String Required

    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/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
   "passId": 123,
   "status": "success",
   "tagId": 70
}

DELETE /tag/{tag}/passes

Remove this tag from all of its passes.

Security:

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • tag : String Required

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

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateId : String Required

    The template of the pass that you want to get tags for.

  • passExternalId : String Required

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

          • 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • templateId : String Required

    The template of the pass that you want to apply tags to.

  • passExternalId : String Required

    The externalId 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: 10

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.

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

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

header PARAMETERS
  • Api-Revision : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The id of the project you want to copy.

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
      • segments : Array [Object]

        ARRAY ITEM
        • OBJECT PROPERTIES
          • creation_date : String

            The date and time when the item was created.

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

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

{
   "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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The id of the project you want to copy.

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

{
   "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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The project containing the segment you want to look up.

  • segmentId : String Required

    The segment you want to look up.

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

{
 "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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The project containing the segment you want to look up.

  • segmentId : String Required

    The segment you want to look up.

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The project containing the segment you want to look up.

  • segmentId : String Required

    The segment you want to look up.

Responses

  • 204

    A successful delete request returns No Content.

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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    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 Pay Boarding Pass Design for more information on rendering logic for Google Pay 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 : String Required

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

    Possible values: 1.2

path PARAMETERS
  • projectId : String Required

    The project that the flight belongs to. Use either the Airship-generated project ID or the external ID.

  • passGroup : Integer Required

    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.

      OBJECT PROPERTIES

    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 : String Required

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

      Possible values: 1.2

    path PARAMETERS
    • projectId : String Required

      The project that the flight belongs to.

    • flightId : Integer Required

      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 : String Required

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

      Possible values: 1.2

    path PARAMETERS
    • projectId : String Required

      The project that the flight belongs to.

    • flightId : Integer Required

      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 Pay Boarding Pass Design for more information on rendering logic for Google Pay 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 : String Required

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

      Possible values: 1.2

    path PARAMETERS
    • projectId : String Required

      The project that the flight belongs to.

    • flightId : Integer Required

      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 : String Required

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

      Possible values: 1.2

    path PARAMETERS
    • projectId : Integer Required

      The project that the flight belongs to.

    • flightId : Integer Required

      The flight you want modify groups for. U

    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 : String Required

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

      Possible values: 1.2

    path PARAMETERS
    • projectId : Integer Required

      The project that the flight belongs to.

    • flightId : Integer Required

      The flight you want modify groups for. U

    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 : String Required

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

      Possible values: 1.2

    path PARAMETERS
    • projectId : Integer Required

      The project that the flight belongs to. Use either the Airship-generated project ID or the external ID.

    • flightId : Integer Required

      The flight you want modify groups for. Use either the Airship-generated flight ID or the external ID for the flight.

    • passGroup : String Required

      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 : String Required

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

      Possible values: 1.2

    path PARAMETERS
    • projectExternalId : String Required

      The project that the flight belongs to.

    • passGroup : String Required

      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.

        OBJECT PROPERTIES

      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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectExternalId : String Required

        The project you want to create the flight in.

      • flightExternalId : String Required

        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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectExternalId : String Required

        The project you want to create the flight in.

      • flightExternalId : String Required

        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 Pay Boarding Pass Design for more information on rendering logic for Google Pay 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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectExternalId : String Required

        The project you want to create the flight in.

      • flightExternalId : String Required

        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 Pay Boarding Pass Design for more information on rendering logic for Google Pay 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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectExternalId : String Required

        The project you want to create the flight in.

      • flightExternalId : String Required

        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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectExternalId : String Required

        The project that the flight belongs to.

      • flightExternalId : String Required

        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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectExternalId : String Required

        The project that the flight belongs to.

      • flightExternalId : String Required

        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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectExternalId : String Required

        The project that the flight belongs to. Use either the Airship-generated project ID or the external ID.

      • flightExternalId : String Required

        The flight you want modify groups for. Use either the Airship-generated flight ID or the external ID for the flight.

      • passGroup : String Required

        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
      
      {
        "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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectId : String Required

        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.

      Get an event

      Example Request

      GET /v1/events/project/<projectId>/<eventId> HTTP/1.1
      Authorization: Basic <authorization string>

      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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectId : String Required

        The project that the event belongs to.

      • eventId : Integer Required

        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
      
      {
        "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 : String Required

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

        Possible values: 1.2

      path PARAMETERS
      • projectId : String Required

        The project that the event belongs to.

      • eventId : Integer Required

        The event you want to get, update, or delete.

      Request Body

      • Content-Type: application/json

        Object

        OBJECT PROPERTIES
        • fields : Object

          OBJECT PROPERTIES

        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

        DELETE /events/project/{projectId}/{eventId}

        Deletes the specified event.

        Security:

        header PARAMETERS
        • Api-Revision : String Required

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

          Possible values: 1.2

        path PARAMETERS
        • projectId : String Required

          The project that the event belongs to.

        • eventId : Integer Required

          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/flights/project/<projectId>/<eventId>/passGroups HTTP/1.1
        Authorization: Basic <authorization string>

        Example Response