Wallet API

Scroll down for code samples, example requests and responses.

The Urban Airship Wallet API was previously known as the Reach API. In this document we use the term Wallet but if you encounter the name Reach in other literature, note that the terms are interchangeable.

The Wallet API provides programmatic access to Urban 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 Urban Airship Wallet projects and passes, see the Introduction to Passes.

See the Getting Started Guide for help setting up an Urban 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 Urban Airship Engage API.

Always specify the version of the API you want to use by adding an HTTP header called Api-Revision. The value of that header should be in the format x.y where x is the API version and y the sub-revision. For instance, 1.2 is for the /v1 API, revision 2.

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.

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

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • pageSize query

    IntegerOptional

    The number of results per page.

  • page query

    IntegerOptional

    The page of the search you want to return.

  • order query

    StringOptional

    Determines the order of results.

    Possible values: id, name, createdAt, updatedAt.

  • direction query

    StringOptional

    The direction of the result set, ascending or descending.

    Possible values: ASC, DESC.

Response

  • 200

    An array of projects belonging to you.

    Response Body

    application/json; charset=utf-8

    Type: Object

    • count

      StringOptional

      The total number of results.

    • pagination

      ObjectOptional

      Contains information about pagination, according to your query parameters.

      • direction

        StringOptional

        The direction of results, ascending or descending.

        Possible values: ASC, DESC.

      • order

        StringOptional

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

      • page

        IntegerOptional

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

      • pageSize

        IntegerOptional

        The number of results per page.

      • start

        IntegerOptional

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

    • projects

      Array<Project Response>Optional

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

Request Body

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

application/json; charset=utf-8

Type: Project Request

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

Response

  • 200

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

    Response Body

    application/json; charset=utf-8

    Type: Project Response

    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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to copy.

Response

  • 200

    A project and a list of templates within the project.

    Response Body

    application/json

    Type: Project Response

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

Get Project with External ID

Example Request

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

Example Response

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

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

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

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

Response

  • 200

    A project and a list of templates within the project.

    Response Body

    application/json

    Type: Project Response

    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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

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

Request Body

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

application/json

Type: Project Request

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

Response

  • 200

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

    Response Body

    application/json

    Type: Project Response

    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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

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

Request Body

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

application/json; charset=utf-8

Type: Project Request

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

Response

  • 200

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

    Response Body

    application/json; charset=utf-8

    Type: Project Response

    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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to look up.

Response

  • 200

    A project and a list of templates within the project.

    Response Body

    application/json

    Type: Project Response

    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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    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.

application/json

Type: Project Request

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

Response

  • 200

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

    Response Body

    application/json

    Type: Project Response

    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.

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • template_id path

    StringRequired

    The id of the template you want to copy.

Response

  • 200

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

    Response Body

    application/json; charset=utf-8

    Type: Object

    • templateId

      IntegerOptional

      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"
      },
      {
         "vendor": "Apple",
         "projectType": "memberCard",
         "projectId": "12346",
         "type": "Store Card",
         "vendorId": "1",
         "deleted": "False",
         "id": "12345",
         "updatedAt": "2013-07-01T18:28:33.000Z",
         "description": "Description",
         "createdAt": "2013-07-01T18:28:33.000Z",
         "name": "Loyalty Card",
         "disabled": "False"
      }
   ],
   "pagination": {
      "order": "id",
      "page": "1",
      "start": "0",
      "direction": "DESC",
      "pageSize": "10"
   }
}
GET /template/headers

List the headers for templates you created.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

Response

  • 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

    application/json; charset=utf-8

    Type: Object

    • count

      StringOptional

      The total number of results.

    • pagination

      ObjectOptional

      Contains information about pagination, according to your query parameters.

      • direction

        StringOptional

        The direction of results, ascending or descending.

        Possible values: ASC, DESC.

      • order

        StringOptional

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

      • page

        IntegerOptional

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

      • pageSize

        IntegerOptional

        The number of results per page.

      • start

        IntegerOptional

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

    • templateHeaders

      Array<Object>Optional

      A list of template header objects.

        • All of:
        • Type: Object

          • createdAt

            StringOptional

            The date and time when the item was created.

            Format: date-time.

          • id

            IntegerOptional

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

          • updatedAt

            StringOptional

            The date and time when the item was last updated.

            Format: date-time.

        • Type: Object

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

          • deleted

            BooleanOptional

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

          • description

            StringOptional

            A description for the template.

          • disabled

            BooleanOptional

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

          • name

            StringRequired

            The name of the template.

          • projectId

            IntegerOptional

            The id of the project the template belongs to.

          • projectType

            StringOptional

            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

            StringOptional

            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.

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

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

  • locationId path

    StringRequired

    The ID of the location you want to remove.

Response

  • 200

    A succesful response returns ??

    Response Body

    application/json; charset=utf-8

    Type: Object

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.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

    The externalId of the template you want to add locations to.

Request Body

A request includes an array of locations.

application/json

Type: Object

Response

  • 200

    A successful request returns the locations on the pass.

    Response Body

    application/json; charset=utf-8

    Type: Array<Object>

    • Type: Object

      • LocationId

        IntegerOptional

        The identifier for a location

      • fieldId

        IntegerOptional
      • value

        Location ObjectOptional

        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.

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"
   }
}
GET /template/id/{templateExternalId}

Get the template specified by the externalId.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • templateExternalId path

    StringRequired

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

Response

  • 200

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

    Response Body

    application/json

    Type: Object

      All of:
    • Type: Object

      • createdAt

        StringOptional

        The date and time when the item was created.

        Format: date-time.

      • id

        IntegerOptional

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

      • updatedAt

        StringOptional

        The date and time when the item was last updated.

        Format: date-time.

    • Type: Object

        One of:
      • Type: Apple Wallet Template Request

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

      • Type: 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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • templateExternalId path

    StringRequired

    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.

application/json

Type: Object

    One of:
  • Type: Apple Wallet Template Request

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

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

Response

  • 200

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

    Response Body

    application/json; charset=utf-8

    Type: Object

    • templateId

      IntegerOptional

      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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • templateExternalId path

    StringRequired

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

Response

  • 200

    Returns the status of the deleted template.

    Response Body

    application/json

    Type: Object

    • TemplateId

      IntegerOptional

      The identifier of the deleted template.

    • status

      StringOptional

      Indicates that the request succeeded.

      Possible values: success.

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"
   }
}
GET /template/{Id}

Get the template specified by the id.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • Id path

    StringRequired

    The templateId of the template you want to lookup.

Response

  • 200

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

    Response Body

    application/json

    Type: Object

      All of:
    • Type: Object

      • createdAt

        StringOptional

        The date and time when the item was created.

        Format: date-time.

      • id

        IntegerOptional

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

      • updatedAt

        StringOptional

        The date and time when the item was last updated.

        Format: date-time.

    • Type: Object

        One of:
      • Type: Apple Wallet Template Request

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

      • Type: 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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • Id path

    StringRequired

    The templateId of the template you want to update.

Request Body

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

application/json

Type: Object

    One of:
  • Type: Apple Wallet Template Request

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

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

Response

  • 200

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

    Response Body

    application/json; charset=utf-8

    Type: Object

    • templateId

      IntegerOptional

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

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

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • Id path

    StringRequired

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

Request Body

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

application/json

Type: Object

    One of:
  • Type: Apple Wallet Template Request

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

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

Response

  • 200

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

    Response Body

    application/json; charset=utf-8

    Type: Object

    • templateId

      IntegerOptional

      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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • Id path

    StringRequired

    The templateId of the template you want to delete.

Response

  • 200

    Returns the status of the deleted template.

    Response Body

    application/json

    Type: Object

    • TemplateId

      IntegerOptional

      The identifier of the deleted template.

    • status

      StringOptional

      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.

Using this endpoint, you can update:The only fields, images or barcode data that 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

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • id path

    StringRequired

    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.

application/json

Type: Object

  • fields

    ObjectOptional
    • Field Name (String)

      ObjectOptional
      • value

        StringOptional

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

Response

  • 200

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

    Response Body

    application/json

    Type: Object

    • ticketId

      IntegerOptional

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

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

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

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to associate your new template with.

  • templateExternalId path

    StringRequired

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

Request Body

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

application/json

Type: Object

    One of:
  • Type: Apple Wallet Template Request

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

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

Response

  • 200

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

    Response Body

    application/json; charset=utf-8

    Type: Object

    • templateId

      IntegerOptional

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

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.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • template_id path

    StringRequired

    The template you want to add locations to.

Request Body

A request includes an array of locations.

application/json

Type: Object

Response

  • 200

    A successful request returns the locations on the pass.

    Response Body

    application/json; charset=utf-8

    Type: Array<Object>

    • Type: Object

      • LocationId

        IntegerOptional

        The identifier for a location

      • fieldId

        IntegerOptional
      • value

        Location ObjectOptional

        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.

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}/locations/{location_id}

Remove a location from template.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • template_id path

    StringRequired

    The template you want to remove a location from.

  • location_id path

    StringRequired

    The ID of the location you want to remove.

Response

  • 200

    A succesful response returns ??

    Response Body

    application/json; charset=utf-8

    Type: Object

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, Urban 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.

List Adaptive Links

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.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

Response

  • 200

    Returns a list of all Adaptive Links for the account

    Response Body

    application/json

    Type: Object

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": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
   "landingPageUrl": "https://acustomer.com/landing.html",
   "availablePasses": 100000
}

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": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "landingPageUrl": "https://acustomer.com/landing.html",
  "availablePasses": 100000,
  "parameterEncoding": "base64",
  "locationRadius": 10,
  "maxResultLocations": 5,
  "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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

Request Body

A request contains adaptive link stuff.

application/json

Type: Adaptive Link Request

Adaptive link request

Response

  • 200

    A successful request results in an adaptive link.

    Response Body

    application/json

    Type: Object

      One of:
    • Type: AdaptiveLink Response

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

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    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.

application/json

Type: Object

    One of:
  • Type: 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.

  • Type: Boarding Pass Adaptive Link Request

    A boarding pass adaptive link requires similar information to other adaptive link types, but does not support some of the same fields, and requires flight/passenger information.

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

Response

  • 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

    application/json

    Type: Object

    • Array<Object>Optional

      An array of adaptive links.

Get an adaptive link

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.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • adaptiveLinkId path

    StringRequired

    The adaptive link you want to return or update.

Response

  • 200

    Lists urls and available passes for an individual link

    Response Body

    application/json

    Type: AdaptiveLink Response

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

Update an adaptive link

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.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • adaptiveLinkId path

    StringRequired

    The adaptive link you want to return or update.

Request Body

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.

application/json

Type: Adaptive Link Request

Adaptive link request

Response

  • 200

    A successful request results in an adaptive link.

    Response Body

    application/json

    Type: AdaptiveLink Response

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

Delete an adaptive link

DELETE /links/adaptive/{adaptiveLinkId}

Deletes an adaptive link.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • adaptiveLinkId path

    StringRequired

    The adaptive link you want to return or update.

Response

  • 200

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

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 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": "12346",
         "updatedAt": "2013-06-27T20:56:07.000Z",
         "createdAt": "2013-06-27T20:56:03.000Z",
         "serialNumber": "a2ea965a-0917-461d-ac67-749639831818",
         "url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/1272\/download"
      }
   ],
   "pagination": {
      "order": "id",
      "page": 1,
      "start": 0,
      "direction": "DESC",
      "pageSize": 2
   }
}
GET /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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • template query

    StringOptional

    The id of the template you want to look up.

Response

  • 200

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

    Response Body

    application/json

    Type: Object

    • count

      IntegerOptional

      The total number of passes associated with the template.

    • pagination

      ObjectOptional

      Contains information about pagination, according to your query parameters.

      • direction

        StringOptional

        The direction of results, ascending or descending.

        Possible values: ASC, DESC.

      • order

        StringOptional

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

      • page

        IntegerOptional

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

      • pageSize

        IntegerOptional

        The number of results per page.

      • start

        IntegerOptional

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

    • passes

      Array<Object>Optional

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

        • createdAt

          StringOptional

          The date and time when the item was last updated.

          Format: date-time.

        • id

          IntegerOptional

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

        • serialNumber

          StringOptional

          The serial number of the pass.

        • templateId

          IntegerOptional

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

        • updatedAt

          StringOptional

          The date and time when the item was created.

          Format: date-time.

        • url

          StringOptional

          The private URL for the pass.

Get Pass with External ID

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/{externalId}

Get the specified pass.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

    The externalId of the pass you want to look up.

Response

  • 200

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

    Response Body

    application/json

    Type: Object

      One of:
    • Type: Apple Wallet Pass Response

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

    • Type: 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 with External ID

Example Request

PUT /v1/pass/id/myExternalTemplate 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/{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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

    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.

application/json

Type: Object

Response

  • 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

    application/json

    Type: Object

      One of:
    • Type: Apple Wallet Pass Response

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

    • Type: 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 from External Template

Example Request

POST /v1/pass/id/myExternalTemplate 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/{externalId}

Create a pass from the specified template by externalId.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

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

Request Body

Create a pass; pass composition varies by vendor.

application/json

Type: Object

    One of:
  • Type: Apple Wallet Pass Request

    A pass for Apple Wallet.

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

Response

  • 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

    application/json

    Type: Object

      One of:
    • Type: Apple Wallet Pass Response

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

    • Type: 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 with External ID

DELETE /pass/id/{externalId}

Delete the specified pass.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

    The externalId of the pass you want to modify

Response

  • 200

    The pass was successfully deleted.

    Response Body

    application/json

    Type: Object

    • PassId

      IntegerOptional

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

    • status

      StringOptional

      Indicates that the pass was deleted.

      Possible values: Deleted.

Delete Location from Pass with External ID

Example Request

DELETE /v1/pass/id/myNewPass/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
DELETE /pass/id/{externalId}/location/{locationId}

Delete the specified location from a pass using an External ID.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

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

  • locationId path

    StringRequired

    The location you want to remove from the pass.

Response

  • 200

    Success.

    Response Body

    application/json

    Type: Object

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

Add the locations to the specified pass

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    StringRequired

    The externalId of the pass you want to add locations to.

Request Body

Set locations for the pass.

application/json

Type: Object

Response

  • 200

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

    Response Body

    application/json

    Type: Array<Object>

    • Type: Object

      • passLocationId

        IntegerOptional

        The identifier for a location

      • value

        Location ObjectOptional

        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.

Create Pass with an External ID

Example Request

POST /v1/pass/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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • templateExternalId path

    StringRequired

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

  • passExternalId path

    StringRequired

    The externalId that you want to give your pass.

Request Body

Create a pass; pass composition varies by vendor.

application/json

Type: Object

    One of:
  • Type: Apple Wallet Pass Request

    A pass for Apple Wallet.

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

Response

  • 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

    application/json

    Type: Object

      One of:
    • Type: Apple Wallet Pass Response

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

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

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • Id path

    StringRequired

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

  • expiry query

    StringOptional

    The expiration date for the pass.

    Format: date.

Request Body

Create a pass; pass composition varies by vendor.

application/json

Type: Object

    One of:
  • Type: Apple Wallet Pass Request

    A pass for Apple Wallet.

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

Response

  • 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

    application/json

    Type: Object

      One of:
    • Type: Apple Wallet Pass Response

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

    • Type: 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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • id path

    StringRequired

    The id of the pass you want to look up.

Response

  • 200

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

    Response Body

    application/json

    Type: Object

      One of:
    • Type: Apple Wallet Pass Response

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

    • Type: 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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • id path

    StringRequired

    The id of the pass you want to update.

Request Body

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

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

application/json

Type: Object

Response

  • 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

    application/json

    Type: Object

      One of:
    • Type: Apple Wallet Pass Response

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

    • Type: 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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • id path

    StringRequired

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

Request Body

Create a pass; pass composition varies by vendor.

application/json

Type: Object

    One of:
  • Type: Apple Wallet Pass Request

    A pass for Apple Wallet.

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

Response

  • 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

    application/json

    Type: Object

      One of:
    • Type: Apple Wallet Pass Response

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

    • Type: 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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • id path

    StringRequired

    The id of the pass you want to delete.

Response

  • 200

    The pass was successfully deleted.

    Response Body

    application/json

    Type: Object

    • PassId

      IntegerOptional

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

    • status

      StringOptional

      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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • passId path

    StringRequired

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

  • passLocationId path

    StringRequired

    The location you want to remove from the pass.

Response

  • 200

    Success.

    Response Body

    application/json

    Type: Object

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

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • passId path

    StringRequired

    The pass you want to add locations to.

Request Body

Set locations for the pass.

application/json

Type: Object

Response

  • 200

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

    Response Body

    application/json

    Type: Array<Object>

    • Type: Object

      • passLocationId

        IntegerOptional

        The identifier for a location

      • value

        Location ObjectOptional

        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.

Create Pass with an External ID

Example Request

POST /v1/pass/12345/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/{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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • templateId path

    StringRequired

    The the template you want to create your pass from.

  • passExternalId path

    StringRequired

    The externalId you want to assign to the new pass.

Request Body

Create a pass; pass composition varies by vendor.

application/json

Type: Object

    One of:
  • Type: Apple Wallet Pass Request

    A pass for Apple Wallet.

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

Response

  • 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

    application/json

    Type: Object

      One of:
    • Type: Apple Wallet Pass Response

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

    • Type: 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 all passes created from a template

Example Request

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

Example Request

{
   "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 /template/{id}/passes

Get a pass.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • id path

    StringRequired

    The template you want to look up

Response

  • 200

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

    Response Body

    application/json

    Type: Object

    • count

      IntegerOptional

      The total number of passes associated with the template.

    • pagination

      ObjectOptional

      Contains information about pagination, according to your query parameters.

      • direction

        StringOptional

        The direction of results, ascending or descending.

        Possible values: ASC, DESC.

      • order

        StringOptional

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

      • page

        IntegerOptional

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

      • pageSize

        IntegerOptional

        The number of results per page.

      • start

        IntegerOptional

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

    • passes

      Array<Object>Optional

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

        • createdAt

          StringOptional

          The date and time when the item was last updated.

          Format: date-time.

        • id

          IntegerOptional

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

        • serialNumber

          StringOptional

          The serial number of the pass.

        • templateId

          IntegerOptional

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

        • updatedAt

          StringOptional

          The date and time when the item was created.

          Format: date-time.

        • url

          StringOptional

          The private URL for the pass.

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • passId path

    StringRequired

    The id of the pass you want to list tags for.

Response

  • 200

    An array of tags belonging to the pass.

    Response Body

    application/json

    Type: Object

    • tags

      Array<Object>Optional

      An array of tags associated with the pass.

        • createdAt

          StringOptional

          The date and time when the item was created.

          Format: date-time.

        • id

          IntegerOptional

          The ID of the tag, used to reference the tag.

        • name

          StringOptional

          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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • passId path

    StringRequired

    The id of the pass you want to add tags to.

Request Body

An array of tags that you want to associate with the pass.

application/json

Type: Object

An array of tags that you want to add to a pass.

  • tags

    Array<String>Required

    An array of strings, each string representing a tag.

    Max items: 10.

Response

  • 200

    Lists the tags added to the pass.

    Response Body

    application/json

    Type: Object

    • mappings

      IntegerOptional

      The number of tags added.

    • newTags

      Array<String>Optional

      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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

Response

  • 200

    A paginated array of tags.

    Response Body

    application/json

    Type: Object

    • Pagination

      ObjectOptional

      Contains information about pagination, according to your query parameters.

      • direction

        StringOptional

        The direction of results, ascending or descending.

        Possible values: ASC, DESC.

      • order

        StringOptional

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

      • page

        IntegerOptional

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

      • pageSize

        IntegerOptional

        The number of results per page.

      • start

        IntegerOptional

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

    • count

      IntegerOptional

      The number of items returned.

    • tags

      Array<Object>Optional
        • createdAt

          StringOptional

          The date and time when the item was created.

          Format: date-time.

        • id

          IntegerOptional

          The ID of the tag, used to reference the tag.

        • name

          StringOptional

          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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • tag path

    StringRequired

    The tag you want to delete.

Response

  • 200

    A successful operation returns a count of affected passes.

    Response Body

    application/json

    Type: Object

    • count

      IntegerOptional

      The number of passes the tag was removed from.

    • status

      StringOptional

      The oepration was successful.

      Possible values: success.

    • tagId

      IntegerOptional

      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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • tag path

    StringRequired

    The tag you want to remove.

  • pass path

    StringRequired

    The pass you want to remove the tag from.

Response

  • 200

    A successful response includes the ID of the tag and the ID of the pass it was removed from.

    Response Body

    application/json

    Type: Object

    • passId

      IntegerOptional

      The id of the pass that the tag was removed from.

    • status

      StringOptional

      The oepration was successful.

      Possible values: success.

    • tagId

      IntegerOptional

      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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • tag path

    StringRequired

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

Response

  • 200

    A successful response returns a paginated array of passes.

    Response Body

    application/json

    Type: Object

    • count

      IntegerOptional

      The total number of results.

    • pagination

      ObjectOptional

      Contains information about pagination, according to your query parameters.

      • direction

        StringOptional

        The direction of results, ascending or descending.

        Possible values: ASC, DESC.

      • order

        StringOptional

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

      • page

        IntegerOptional

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

      • pageSize

        IntegerOptional

        The number of results per page.

      • start

        IntegerOptional

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

    • passes

      ObjectOptional

      Meta information about passes.

      • createdAt

        StringOptional

        The date and time when the item was last updated.

        Format: date-time.

      • id

        IntegerOptional

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

      • serialNumber

        StringOptional

        The serial number of the pass.

      • templateId

        IntegerOptional

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

      • updatedAt

        StringOptional

        The date and time when the item was created.

        Format: date-time.

      • url

        StringOptional

        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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • tag path

    StringRequired

    The tag associated with the passes you want to update.

Request Body

Provide only the fields you want to update.

application/json

Type: Object

  • fields

    ObjectOptional
    • *

      ObjectOptional
      • value

        StringOptional

        The value you want to change for field.

Response

  • 200

    A successful request returns a ticketId.

    Response Body

    application/json

    Type: Object

    • ticketId

      IntegerOptional

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:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • tag path

    StringRequired

    The tag you want to remove.

Response

  • 200

    A successful response returns a count of the affected passes.

    Response Body

    application/json

    Type: Object

    • count

      IntegerOptional

      The number of passes the tag was removed from.

    • status

      StringOptional

      The oepration was successful.

      Possible values: success.

    • tagId

      IntegerOptional

      The id of the deleted tag.

Segments

A Segment identifies a group/set of wallet passes that contains a tag or combination of tags, using boolean and, or, and not operators. Use segments to group and target passes for subsequent updates.

List segments

Example Request

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

Example Response

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

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The id of the project you want to copy.

Response

  • 200

    A response returns a segment ID that you can use to reference the segment in future operations.

    Response Body

    application/json

    Type: Object

    • segments

      Array<Object>Optional
        • creation_date

          StringOptional

          The date and time when the item was created.

          Format: date-time.

        • display_name

          StringOptional

          The name of the segment.

        • id

          StringOptional

          The identifier for the segment, used to identify the segment in other operations.

          Format: uuid.

        • modification_date

          StringOptional

          The date and time when the item was last updated.

          Format: date-time.

Create a segment

Example Request

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

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

Example Response

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

Create a segment for a project.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The id of the project you want to copy.

Request Body

Contains and, or, or not operators for tags that identify your segment.

application/json

Type: Object

  • criteria

    Segment SelectorOptional

    Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.

  • display_name

    StringOptional

    The name of the segment.

Response

  • 200

    A response returns a segment ID that you can use to reference the segment in future operations.

    Response Body

    application/json

    Type: Object

    • ok

      BooleanOptional

      If true, the operation completed successfully.

    • operationId

      StringOptional

      An identifier for the operation. Use this value to reference the operation for troubleshooting purposes.

      Format: uuid.

    • segmentId

      StringOptional

      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.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project containing the segment you want to look up.

  • segmentId path

    StringRequired

    The segment you want to look up.

Response

  • 200

    A successful request returns the selection criteria for the segment.

    Response Body

    application/json

    Type: Object

    • criteria

      Segment SelectorOptional

      Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.

    • display_name

      StringOptional

      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.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project containing the segment you want to look up.

  • segmentId path

    StringRequired

    The segment you want to look up.

Request Body

application/json

Type: Object

  • criteria

    Segment SelectorOptional

    Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.

  • display_name

    StringOptional

    The name of the segment.

Response

  • 200

    A response returns a segment ID that you can use to reference the segment in future operations.

    Response Body

    application/json

    Type: Object

    • ok

      BooleanOptional

      If true, the operation completed successfully.

    • operationId

      StringOptional

      An identifier for the operation. Use this ID to reference the operation for troubleshooting purposes.

      Format: uuid.

    • segmentId

      StringOptional

      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.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project containing the segment you want to look up.

  • segmentId path

    StringRequired

    The segment you want to look up.

Response

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

Get a flight with External IDs

GET /flights/project/id/{projectExternalId}/id/{flightExternalId}

Returns information for a single flight.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectExternalId path

    StringRequired

    The project you want to create the flight in.

  • flightExternalId path

    StringRequired

    The external identifier you want to give to the flight.

Response

  • 200

    A successful request returns the flightId and flightExternalId (if applicable) values, so you can reference the flight in later operations.

    Response Body

    application/json

    Type: Flight Response

    A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Update a flight with External IDs

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.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectExternalId path

    StringRequired

    The project you want to create the flight in.

  • flightExternalId path

    StringRequired

    The external identifier you want to give to the flight.

Request Body

application/json

Type: 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.

Response

  • 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

    application/json

    Type: Flight Response

    A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Create a flight with External IDs

POST /flights/project/id/{projectExternalId}/id/{flightExternalId}

Create flights

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectExternalId path

    StringRequired

    The project you want to create the flight in.

  • flightExternalId path

    StringRequired

    The external identifier you want to give to the flight.

Request Body

application/json

Type: 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.

Response

  • 200

    A successful request returns the flightId and flightExternalId (if applicable) values, so you can reference the flight in later operations.

    Response Body

    application/json

    Type: Flight Response

    A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Delete a flight with External IDs

DELETE /flights/project/id/{projectExternalId}/id/{flightExternalId}

Deletes the specified flight.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectExternalId path

    StringRequired

    The project you want to create the flight in.

  • flightExternalId path

    StringRequired

    The external identifier you want to give to the flight.

Response

  • 200

    The flight was deleted.

    Response Body

    application/json

    Type: Object

    • ok

      BooleanOptional

      If true, the operation completed successfully.

Create a flight

Example Request

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

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

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to create the flight in.

Request Body

application/json

Type: 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.

Response

  • 200

    A successful request returns the flightId and flightExternalId (if applicable) values, so you can reference the flight in later operations.

    Response Body

    application/json

    Type: Flight Response

    A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

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>",
  "flightExternalId": "<flightExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-07-05T09:12:32Z",
  "updatedAt": "2018-07-05T09:12:32Z",
  "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.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project that the flight belongs to.

  • flightId path

    IntegerRequired

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

Response

  • 200

    A successful request returns the flightId and flightExternalId (if applicable) values, so you can reference the flight in later operations.

    Response Body

    application/json

    Type: Flight Response

    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

{
  "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",
  "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 when creating a flight. Provide only the fields you want to update; any fields that you omit from the payload remain unchanged.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project that the flight belongs to.

  • flightId path

    IntegerRequired

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

Request Body

application/json

Type: 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.

Response

  • 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

    application/json

    Type: Flight Response

    A complete flight response, including identifiers to reference the flight and the fields defined within the flight.

Delete a flight

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 200 OK
DELETE /flights/project/{projectId}/{flightId}

Deletes the specified flight.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project that the flight belongs to.

  • flightId path

    IntegerRequired

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

Response

  • 200

    The flight was deleted.

    Response Body

    application/json

    Type: Object

    • ok

      BooleanOptional

      If true, the operation completed successfully.

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.

Get an event with external IDs

Example Request

GET /v1/events/project/id/<projectExternalId>/id/<eventExternalId> HTTP/1.1
Authorization: Basic <authorization string>

Example Response

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

{
  "eventId": "<uaEventId>",
  "eventExternalId": "<eventExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-09-24T09:12:32Z",
  "updatedAt": "2018-09-24T09:12:32Z",
  "fields": {
    "eventName": {
      "label": "Event",
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "label": "Venue",
      "value": "AT&T Park"
    },
    "venueAddress": {
      "label": "Address",
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T09:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T10:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T12:00:00"
    }
  }
}
GET /events/project/id/{projectExternalId}/id/{eventExternalId}

Returns information about a single event.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectExternalId path

    StringRequired

    The external ID of the project you want to create the event in.

  • eventExternalId path

    StringRequired

    A custom idetnfier for an event. This is the event you want to create, get, modify, or delete.

Response

  • 200

    A successful request returns the eventId and eventExternalId (if applicable) values, so you can reference the event in later operations.

    Response Body

    application/json

    Type: Event Response

    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 using external IDs

Example Request

PUT /v1/events/project/id/<projectExternalId>/id/<eventExternalId> 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>",
  "eventExternalId": "<eventExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-09-24T09:12:32Z",
  "updatedAt": "2018-09-24T09:12:32Z",
  "fields": {
    "eventName": {
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "value": "AT&T Park"
    },
    "venueAddress": {
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T09:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T10:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T12:00:00"
    }
  }
}
PUT /events/project/id/{projectExternalId}/id/{eventExternalId}

Update any of the keys provided in the fields object of an Event Request. Provide only the fields you want to update; any fields that you omit from the payload remain unchanged.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectExternalId path

    StringRequired

    The external ID of the project you want to create the event in.

  • eventExternalId path

    StringRequired

    A custom idetnfier for an event. This is the event you want to create, get, modify, or delete.

Request Body

application/json

Type: Object

  • fields

    ObjectOptional

Response

  • 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

    application/json

    Type: Event Response

    An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Create an event in a project using external IDs

Example Request

POST /v1/events/project/<projectExternalId>/id/<eventExternalId> HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/json

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

Example Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "eventId": "<uaEventId>",
  "eventExternalId": "<eventExternalId>",
  "projectId": "<uaProjectId>",
  "projectExternalId": "<projectExternalId>",
  "createdAt": "2018-09-24T09:12:32Z",
  "updatedAt": "2018-09-24T09:12:32Z",
  "fields": {
    "eventName": {
      "label": "Event",
      "value": "LA Dodgers at SF Giants"
    },
    "venueTitle": {
      "label": "Venue",
      "value": "AT&T Park"
    },
    "venueAddress": {
      "label": "Address",
      "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
    },
    "doorsOpen": {
      "label": "Doors Open",
      "value": "2019-09-25T08:35:00"
    },
    "startTime": {
      "label": "Start Time",
      "value": "2019-09-25T09:00:00"
    },
    "endTime": {
      "label": "End Time",
      "value": "2019-09-25T11:00:00"
    }
  }
}
POST /events/project/id/{projectExternalId}/id/{eventExternalId}

Create an event using external IDs.

If your request uses an eventExternalId already associated with an existing event, the call is treated as a PUT, and updates the existing event. As with the PUT method, any fields not contained in the request are unchanged.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectExternalId path

    StringRequired

    The external ID of the project you want to create the event in.

  • eventExternalId path

    StringRequired

    A custom idetnfier for an event. This is the event you want to create, get, modify, or delete.

Request Body

application/json

Type: Event Request

Represents an event scheduled at a specific time and venue.

Response

  • 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

    application/json

    Type: Event Response

    An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Delete an event with external IDs

DELETE /events/project/id/{projectExternalId}/id/{eventExternalId}

Deletes the specified event.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectExternalId path

    StringRequired

    The external ID of the project you want to create the event in.

  • eventExternalId path

    StringRequired

    A custom idetnfier for an event. This is the event you want to create, get, modify, or delete.

Response

  • 200

    The event was deleted.

    Response Body

    application/json

    Type: Object

    • ok

      BooleanOptional

      If true, the operation completed successfully.

Create an event

Example Request

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

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

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

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to create the event in.

Request Body

application/json

Type: Event Request

Represents an event scheduled at a specific time and venue.

Response

  • 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

    application/json

    Type: Event Response

    An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Get a 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",
  "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.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project that the event belongs to.

  • eventId path

    IntegerRequired

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

Response

  • 200

    A successful request returns the eventId and eventExternalId (if applicable) values, so you can reference the event in later operations.

    Response Body

    application/json

    Type: Event Response

    An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Update a event using

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

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project that the event belongs to.

  • eventId path

    IntegerRequired

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

Request Body

application/json

Type: Object

  • fields

    ObjectOptional

Response

  • 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

    application/json

    Type: Event Response

    An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.

Delete a event

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

Deletes the specified event.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project that the event belongs to.

  • eventId path

    IntegerRequired

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

Response

  • 200

    The event was deleted.

    Response Body

    application/json

    Type: Object

    • ok

      BooleanOptional

      If true, the operation completed successfully.

Callbacks

Wallet callbacks provide a pass event notification, e.g., pass install or uninstall, using webhooks.

Get callback specification

Example Request

GET /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>

Example Response

HTTP/1.1 200 OK

{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}
GET /project/{projectId}/settings/callback

Return the callback specification for a project.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to register a callback server with.

Response

  • 200

    A successful call returns the callback specification.

    Response Body

    application/json

    Type: Object

    Used for both requests and responses to /callback endpoints.

    • baseUrl

      StringOptional

      The URL of your webhook/callback server.

    • headers

      ObjectOptional

      Contains headers required by your webhook/callback server, including authorization, content-type, etc.

      By default, Urban Airship appends content-type: application/json and sends a JSON payload.

Update callback specification

Example Request

PUT /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>

{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}

Example Response

HTTP/1.1 200 OK
  
{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}
PUT /project/{projectId}/settings/callback

Update a callback specification. The payload to update a callback is identical to the payload to create a callback.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to register a callback server with.

Request Body

application/json

Type: Object

Used for both requests and responses to /callback endpoints.

  • baseUrl

    StringOptional

    The URL of your webhook/callback server.

  • headers

    ObjectOptional

    Contains headers required by your webhook/callback server, including authorization, content-type, etc.

    By default, Urban Airship appends content-type: application/json and sends a JSON payload.

Response

  • 200

    A successful call returns the callback specification.

    Response Body

    application/json

    Type: Object

    Used for both requests and responses to /callback endpoints.

    • baseUrl

      StringOptional

      The URL of your webhook/callback server.

    • headers

      ObjectOptional

      Contains headers required by your webhook/callback server, including authorization, content-type, etc.

      By default, Urban Airship appends content-type: application/json and sends a JSON payload.

Create callback specification

Example Request

POST /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>

{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}

Example Response

HTTP/1.1 200 OK
  
{
   "baseUrl": "https://www.remotehost.com/callbacks",
   "headers": {
      "Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
      "Content-Type": "application/json"
   }
}
POST /project/{projectId}/settings/callback

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

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to register a callback server with.

Request Body

application/json

Type: Object

Used for both requests and responses to /callback endpoints.

  • baseUrl

    StringOptional

    The URL of your webhook/callback server.

  • headers

    ObjectOptional

    Contains headers required by your webhook/callback server, including authorization, content-type, etc.

    By default, Urban Airship appends content-type: application/json and sends a JSON payload.

Response

  • 200

    A successful call returns the callback specification.

    Response Body

    application/json

    Type: Object

    Used for both requests and responses to /callback endpoints.

    • baseUrl

      StringOptional

      The URL of your webhook/callback server.

    • headers

      ObjectOptional

      Contains headers required by your webhook/callback server, including authorization, content-type, etc.

      By default, Urban Airship appends content-type: application/json and sends a JSON payload.

Delete a callback specification

Example Request

DELETE /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>

Example Response

HTTP/1.1 204 No Conten
DELETE /project/{projectId}/settings/callback

Delete a registered callback specification. Because a project only uses a single callback specification, you specify the projectId only.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to register a callback server with.

Response

  • 204

    A successful request returns no content.

Tickets

Return status information about tickets or the server itself. For operations that cannot complete immediately, the system returns a ticketId. You can look up this ticketId to determine the true status of the operation.

Check system status

Example Request

GET /v1/system/status HTTP/1.1

Example Response

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

Ensure that you can make a connection to the Wallet API.

Response

  • 200

    You have successfully established a connection with the server.

    Response Body

    application/json

    Type: Object

    • Hello

      StringOptional

      A "Hello World" response tells you that everything is Ok.

      Possible values: World.

Get Ticket Status

Example Request

GET /v1/ticket/123 HTTP/1.1
Authorization: Basic <Base64 key>

Example Response

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

Get the status of a ticket. Some operations can't complete immediately and return a ticketId; use this item to determine the true status of the operation.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • ticketId path

    StringRequired

    The ticket you want to know the status of.

Response

  • 200

    Returns the status of a ticket.

    Response Body

    application/json

    Type: Object

    • ID

      IntegerOptional

      The identifier of the ticket.

    • children

      ObjectOptional
    • createdAt

      StringOptional

      The date and time when the item was created.

      Format: date-time.

    • status

      StringOptional

      The status of the ticket.

Statistics

Get pass creation, installation, and uninstallation counts for projects and templates.

Get Project Activity with External ID

Example Request

GET /v1/project/id/myExternalProject/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
    "id": 12345,
    "startDate": "2015/08/19",
    "endDate": "2015/08/20",
    "summary": {
        "created": 113,
        "installed": 0,
        "uninstalled": 0
    },
    "details": [
        {
            "date": "2015/08/19",
            "activity": {
                "created": 111,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/20",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        }
    ]
}
GET /project/id/{externalId}/activity

Returns pass activity per day for a project by externalId. You can also add start and end date parameters in the path, to return activity between two dates, in the format /template/id/{externalId}/activity/2018-08-10/2018-10/01.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    IntegerRequired

    The externalId of the project you want to return activity for.

Response

  • 200

    Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the projects's createdAt date.

    Response Body

    application/json

    Type: Object

    • details

      Array<Object>Optional

      Each object in this array represents pass activity for a single day.

        • activity

          ObjectOptional

          Represents activity for a template or project.

          • created

            IntegerOptional

            The number of passes created.

          • installed

            IntegerOptional

            The number of passes that were installed.

          • uninstalled

            IntegerOptional

            The number of passes that were uninstalled.

        • date

          StringOptional

          The date for a specific activity instance in wallet statistics.

          Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • endDate

      StringOptional

      The end date for a statistics report.

      Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • id

      IntegerOptional

      The id of the project specified in the path

    • startDate

      StringOptional

      The start date for a statistics report.

      Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • summary

      ObjectOptional

      Represents activity for a template or project.

      • created

        IntegerOptional

        The number of passes created.

      • installed

        IntegerOptional

        The number of passes that were installed.

      • uninstalled

        IntegerOptional

        The number of passes that were uninstalled.

Get Project Statistics with External ID

Example Request

GET /v1/project/id/ext_54321/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

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

Returns Statistics for a given template with an external ID. The response payload lists the internal Wallet id for the template, rather than the external ID.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    IntegerRequired

    The externalId of the project you want to return stats for.

Response

  • 200

    Returns a summary of pass statistics for every template in the project.

    Response Body

    application/json

    Type: Object

    • id

      IntegerOptional

      The identifier for the project.

    • installed

      IntegerOptional

      The total number of passes from this project that are installed.

    • lastUpdated

      StringOptional

      The date and time when the item was last updated.

      Format: date-time.

    • templates

      Array<Object>Optional

      Contains statistics for each template belonging to the project.

        • id

          IntegerOptional

          The identifier for a specific template.

        • installed

          IntegerOptional

          The total number of passes from this template that are installed.

        • lastUpdated

          StringOptional

          The date and time when the item was last updated.

          Format: date-time.

        • total

          IntegerOptional

          The total number of passes created from the template.

        • uninstalled

          IntegerOptional

          The total number of passes created from this template that are uninstalled.

        • vendor

          StringOptional

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

          Possible values: Apple, Google.

    • total

      IntegerOptional

      The total number of passes created in the project.

    • uninstalled

      IntegerOptional

      The total number of passes created from this project that are uninstalled.

Get Project Activity

Example Request

GET /v1/project/12345/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
    "id": 12345,
    "startDate": "2015/08/19",
    "endDate": "2015/08/20",
    "summary": {
        "created": 113,
        "installed": 0,
        "uninstalled": 0
    },
    "details": [
        {
            "date": "2015/08/19",
            "activity": {
                "created": 111,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/20",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        }
    ]
}
GET /project/{projectId}/activity

Returns pass activity per day for a given project by id. You can also add start and end date parameters in the path, to return activity between two dates, in the format /template/{templateId}/activity/2018-08-10/2018-10/01.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    IntegerRequired

    The id of the project you want to return stats for.

Response

  • 200

    Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the projects's createdAt date.

    Response Body

    application/json

    Type: Object

    • details

      Array<Object>Optional

      Each object in this array represents pass activity for a single day.

        • activity

          ObjectOptional

          Represents activity for a template or project.

          • created

            IntegerOptional

            The number of passes created.

          • installed

            IntegerOptional

            The number of passes that were installed.

          • uninstalled

            IntegerOptional

            The number of passes that were uninstalled.

        • date

          StringOptional

          The date for a specific activity instance in wallet statistics.

          Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • endDate

      StringOptional

      The end date for a statistics report.

      Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • id

      IntegerOptional

      The id of the project specified in the path

    • startDate

      StringOptional

      The start date for a statistics report.

      Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • summary

      ObjectOptional

      Represents activity for a template or project.

      • created

        IntegerOptional

        The number of passes created.

      • installed

        IntegerOptional

        The number of passes that were installed.

      • uninstalled

        IntegerOptional

        The number of passes that were uninstalled.

Get Project Statistics

Example Request

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

Example Response

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

Returns Statistics for a given template by id.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    IntegerRequired

    The id of the template you want to return stats for.

Response

  • 200

    Returns a summary of pass statistics for every template in the project.

    Response Body

    application/json

    Type: Object

    • id

      IntegerOptional

      The identifier for the project.

    • installed

      IntegerOptional

      The total number of passes from this project that are installed.

    • lastUpdated

      StringOptional

      The date and time when the item was last updated.

      Format: date-time.

    • templates

      Array<Object>Optional

      Contains statistics for each template belonging to the project.

        • id

          IntegerOptional

          The identifier for a specific template.

        • installed

          IntegerOptional

          The total number of passes from this template that are installed.

        • lastUpdated

          StringOptional

          The date and time when the item was last updated.

          Format: date-time.

        • total

          IntegerOptional

          The total number of passes created from the template.

        • uninstalled

          IntegerOptional

          The total number of passes created from this template that are uninstalled.

        • vendor

          StringOptional

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

          Possible values: Apple, Google.

    • total

      IntegerOptional

      The total number of passes created in the project.

    • uninstalled

      IntegerOptional

      The total number of passes created from this project that are uninstalled.

Get Template Activity with External ID

Example Request

GET /v1/template/id/myExternalId/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
    "id": 1234,
    "vendor": "Apple",
    "startDate": "2015/08/19",
    "endDate": "2015/08/20",
    "summary": {
        "created": 113,
        "installed": 0,
        "uninstalled": 0
    },
    "details": [
        {
            "date": "2015/08/19",
            "activity": {
                "created": 111,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/20",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        }
    ]
}
GET /template/id/{externalId}/activity

Returns day-by-day activity for a template by externalId. You can also add start and end date parameters in the path, to return activity between two dates, in the format /template/id/{externalId}/activity/2018-08-10/2018-10/01.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    IntegerRequired

    The externalId of the template you want to return stats for.

Response

  • 200

    Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the template's createdAt date.

    Response Body

    application/json

    Type: Object

    • details

      Array<Object>Optional

      Each object in this array represents pass activity for a single day.

        • activity

          ObjectOptional

          Represents activity for a template or project.

          • created

            IntegerOptional

            The number of passes created.

          • installed

            IntegerOptional

            The number of passes that were installed.

          • uninstalled

            IntegerOptional

            The number of passes that were uninstalled.

        • date

          StringOptional

          The date for a specific activity instance in wallet statistics.

          Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • endDate

      StringOptional

      The end date for a statistics report.

      Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • id

      IntegerOptional

      The id of the template specified in the path.

    • startDate

      StringOptional

      The start date for a statistics report.

      Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • summary

      ObjectOptional

      Represents activity for a template or project.

      • created

        IntegerOptional

        The number of passes created.

      • installed

        IntegerOptional

        The number of passes that were installed.

      • uninstalled

        IntegerOptional

        The number of passes that were uninstalled.

    • vendor

      StringOptional

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

      Possible values: Apple, Google.

Get Template Statistics with External ID

Example Request

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

Example Response

{
    "id": 12345,
    "vendor": "Apple",
    "lastUpdated": "2015-10-01T20:15:28.000-07:00",
    "total": 7,
    "installed": 0,
    "uninstalled": 0
}
GET /template/id/{externalId}/stats

Returns Statistics for a given template with an external ID. The response payload lists the internal Wallet id for the template, rather than the external ID.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • externalId path

    IntegerRequired

    The id of the template you want to return stats for.

Response

  • 200

    Returns an object contatining usage information about a template.

    Response Body

    application/json

    Type: Object

    • id

      IntegerOptional

      The template specified in the request.

    • installed

      IntegerOptional

      The number of installed passes based on this template.

    • lastUpdated

      StringOptional

      The date and time when the item was last updated.

      Format: date-time.

    • total

      IntegerOptional

      A count of the total number of passes created from the template.

    • uninstalled

      IntegerOptional

      The number of uninstalled passes based on this template.

    • vendor

      StringOptional

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

      Possible values: Apple, Google.

Get Template Activity

Example Request

GET /v1/template/1234/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example Response

{
    "id": 1234,
    "vendor": "Apple",
    "startDate": "2015/08/19",
    "endDate": "2015/08/20",
    "summary": {
        "created": 113,
        "installed": 0,
        "uninstalled": 0
    },
    "details": [
        {
            "date": "2015/08/19",
            "activity": {
                "created": 111,
                "installed": 0,
                "uninstalled": 0
            }
        },
        {
            "date": "2015/08/20",
            "activity": {
                "created": 0,
                "installed": 0,
                "uninstalled": 0
            }
        }
    ]
}
GET /template/{templateId}/activity

Returns day-by-day activity for a given template by id. You can also add start and end date parameters in the path, to return activity between two dates, in the format /template/{templateId}/activity/2018-08-10/2018-10/01.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • templateId path

    IntegerRequired

    The id of the template you want to return stats for.

Response

  • 200

    Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the template's createdAt date.

    Response Body

    application/json

    Type: Object

    • details

      Array<Object>Optional

      Each object in this array represents pass activity for a single day.

        • activity

          ObjectOptional

          Represents activity for a template or project.

          • created

            IntegerOptional

            The number of passes created.

          • installed

            IntegerOptional

            The number of passes that were installed.

          • uninstalled

            IntegerOptional

            The number of passes that were uninstalled.

        • date

          StringOptional

          The date for a specific activity instance in wallet statistics.

          Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • endDate

      StringOptional

      The end date for a statistics report.

      Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • id

      IntegerOptional

      The id of the template specified in the path.

    • startDate

      StringOptional

      The start date for a statistics report.

      Pattern: ([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).

    • summary

      ObjectOptional

      Represents activity for a template or project.

      • created

        IntegerOptional

        The number of passes created.

      • installed

        IntegerOptional

        The number of passes that were installed.

      • uninstalled

        IntegerOptional

        The number of passes that were uninstalled.

    • vendor

      StringOptional

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

      Possible values: Apple, Google.

Get Template Statistics

Example Request

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

Example Response

{
    "id": 12345,
    "vendor": "Apple",
    "lastUpdated": "2015-10-01T20:15:28.000-07:00",
    "total": 7,
    "installed": 0,
    "uninstalled": 0
}
GET /template/{templateId}/stats

Returns Statistics for a given template by id.

Security:

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • templateId path

    IntegerRequired

    The id of the template you want to return stats for.

Response

  • 200

    Returns an object contatining usage information about a template.

    Response Body

    application/json

    Type: Object

    • id

      IntegerOptional

      The template specified in the request.

    • installed

      IntegerOptional

      The number of installed passes based on this template.

    • lastUpdated

      StringOptional

      The date and time when the item was last updated.

      Format: date-time.

    • total

      IntegerOptional

      A count of the total number of passes created from the template.

    • uninstalled

      IntegerOptional

      The number of uninstalled passes based on this template.

    • vendor

      StringOptional

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

      Possible values: Apple, Google.

Certificates

Get certificates

Example Response

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

{
    "nextPage": "https://wallet.urbanairship.com/v1/certificates/list/?page=11&pageSize=10",
    "count": 2,
    "pagination": {
        "order": "name",
        "page": "1",
        "start": "0",
        "direction": "DESC",
        "pageSize": 10
    },
    "certificates":[
        {
            "id": "40adce15-5c52-479d-8620-54c21cd851a6",
            "vendor": "Apple",
            "baseName": "pass.com.myName.test",
            "name": "editable name",
            "comment": "something about this cert",
            "teamIdentifier": "9M8MY376H5",
            "nfcSupport": false,
            "enabled": false,
            "createdAt": "2018-05-26T23:23:21Z",
            "updatedAt": "2019-05-26T22:23:21Z",
            "expired": false,
            "validityStart": "2018-05-26T23:45:00Z",
            "validityEnd": "2019-05-26T23:45:00Z",
            "templates": [
                {"id": 123,"name": "templateName1"},
                {"id": 221,"name": "templateName2"}
            ]
        },
        {
            "id": "12adce15-5c52-479d-8620-54c21cd851aa",
            "vendor": "Apple",
            "baseName", "pass.wallet.myName.anotherTest",
            "name": "editable name1",
            "comment": "a plain text description of this cert",
            "teamIdentifier": "OGKV57GD95",
            "nfcSupport": true,
            "enabled": false,
            "default": false,
            "createdAt": "2018-04-26T23:23:21Z",
            "updatedAt": "2019-04-27T17:22:00Z",
            "expired": false,
            "validityStart": "2018-05-26T23:45:00Z",
            "validityEnd": "2019-05-26T23:45:00Z",
            "templates": [
                {"id": 123, "name": "templateName1"},
                {"id": 221, "name": "templateName2"}
            ]
        }
    ]
}
GET /certificates

Returns a list of certificates, including an array of templates that use the certificate.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • vendor query

    StringOptional

    The vendor of certificate you want to return. Supports Apple only.

    Possible values: Apple.

  • enabled query

    BooleanOptional

    Indicates whether or not the certificate is enabled.

  • order query

    StringOptional

    Indicates the field to order results by.

  • page query

    IntegerOptional

    Indicates the page of results to return.

  • pageSize query

    IntegerOptional

    Indicates the number of results per page.

  • direction query

    StringOptional

    Indicates the direction in which to return results.

    Possible values: ASC, DESC.

Response

  • 200

    Returns an array of certificates.

    Response Body

    application/json

    Type: Object

    • certificates

      Array<Certificate Object>Optional
    • count

      IntegerOptional

      The number of results on the curent page.

    • nextPage

      StringOptional

      The url for the next page of results.

      Format: url.

    • pagination

      ObjectOptional

      Contains information about pagination, according to your query parameters.

      • direction

        StringOptional

        The direction of results, ascending or descending.

        Possible values: ASC, DESC.

      • order

        StringOptional

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

      • page

        IntegerOptional

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

      • pageSize

        IntegerOptional

        The number of results per page.

      • start

        IntegerOptional

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

Add new certificate

Example Request

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

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

Example Response

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

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

Adds a new Apple Wallet certificate to the Wallet system. If the specified certificate exists in our system, and the baseName and teamIdentifier match the existing certificate, we will renew/update the existing certificate.

When adding a certificate, you must paste the contents of your p12 certificate into the certificate field in the request payload. You can get the contents of your p12 file with the two following commands:

openssl base64 -in wallet-prod.p12 -out wallet-prod.pem cat wallet-prod.pem | tr -d "\n\r" | less

The response contains the id of your new certificate. You will use the id to perform subsequent actions (GET, PUT, or DELETE) against this certificate. The response will also contain other information gathered from the certificate. You can find information about these additional fields under Get Certificate.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

Request Body

application/json

Type: Certificate Object

Response

  • 200

    Returns the created certificate and new read only fields.

    Response Body

    application/json

    Type: Certificate Object

Get a certificate

Example Response

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

{
    "id": "40adce15-5c52-479d-8620-54c21cd851a6",
    "vendor": "Apple",
    "baseName": "pass.com.myName.test",
    "name": "editable name",
    "comment": "something about this cert",
    "teamIdentifier": "9M8MY376H5",
    "nfcSupport": false,
    "enabled": false,
    "createdAt": "2018-05-26T23:23:21Z",
    "updatedAt": "2019-05-26T22:23:21Z",
    "expired": false,
    "validityStart": "2018-05-26T23:45:00Z",
    "validityEnd": "2019-05-26T23:45:00Z",
    "templates": [
        {"id": 123,"name": "templateName1"},
        {"id": 221,"name": "templateName2"}
    ]
}
GET /certificates/{id}

Returns information about a certificate, including an array of templates that use the certificate.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • id path

    StringRequired

    The id of the certificate you want to perform operations against.

Response

  • 200

    Returns information about the certificate specified in the request

    Response Body

    application/json

    Type: Certificate Object

Update a certificate

PUT /certificates/{id}

Updates a certificate. Note the following behaviors:

  • The following fields can be updated directly: enabled, default, comment and name.
  • If fields enabled and default are not specified they won't be changed.
  • If fields comment and name are not specified, we assume the value needs to be removed. If you don't want to change the value, specify null values.
  • Some of the fields will be extracted from the certificate and will be updated indirectly: teamIdentifier and baseName.
  • The field updatedAt will change with each update.
  • The field createdAt cannot be changed.
  • If the user specifies an invalid id in the path or no certificate can be found we will return an error (see below).
  • Changing the default certificate is done by setting the new certificate "default": true.
  • A single certificate must be set as the default. You cannot set the current default certificate to "default": false

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • id path

    StringRequired

    The id of the certificate you want to perform operations against.

Request Body

application/json

Type: Certificate Object

Response

  • 200

    Returns the created certificate and new read only fields.

    Response Body

    application/json

    Type: Certificate Object

Remove a certificate

DELETE /certificates/{id}

Removes a certificate from the system.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • id path

    StringRequired

    The id of the certificate you want to perform operations against.

Response

  • 204

    A successful request returns no content.

Schedules

List schedules

Example Request

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

Example Response

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

Get a list of all schedules that have not yet occured for the project

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to register schedule updates for.

Response

  • 200

    Returns a list of schedules, ordered schedule_time closest to the present.

    Response Body

    application/json

    Type: Object

    • count

      IntegerOptional

      The number of schedules on the page.

    • next_page

      StringOptional

      The url of the next page in the result set.

      Format: url.

    • ok

      BooleanOptional

      If true, the operation completed successfully.

    • schedules

      Array<Object>Optional

      The list of upcoming schedules.

        • name

          StringOptional

          A name for the schedule.

        • schedule

          ObjectOptional
          • schedule_time

            StringOptional

            The date and time when the update will occur.

            Format: date-time.

        • update

          ObjectOptional

          The updates you want to make to an audience or pass, generated from a template within the project.

          • audience

            Audience SelectorOptional

            An audience selector forms the expression that determines the set of channels to target.

          • pass

            ObjectOptional
            • fields

              ObjectOptional
              • Field Title (String)

                ObjectOptional
                • value

                  StringOptional

                  The vallue you want to change for a field on a pass.

            • template

              IntegerOptional

              The id of the template you want to update.

          • url

            StringOptional

            A url directly to the schedule.

            Format: url.

    • total_count

      IntegerOptional

      The total number of schedules

Schedule an update

Example Request

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

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

Example Response

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

Schedule an update to a project. The body of the request is an object containing a name, a schedule object, and an update object (which itself contains the audience, pass, and template updates you want to perform).

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to register schedule updates for.

Request Body

application/json

Type: Object

Specifies updates to passes or adaptive links at a particular date and time.

  • name

    StringOptional

    A name for the schedule.

  • schedule

    ObjectOptional
    • schedule_time

      StringOptional

      The date and time when the update will occur.

      Format: date-time.

  • update

    ObjectOptional

    The updates you want to make to an audience or pass, generated from a template within the project.

    • audience

      Audience SelectorOptional

      An audience selector forms the expression that determines the set of channels to target.

    • pass

      ObjectOptional
      • fields

        ObjectOptional
        • Field Title (String)

          ObjectOptional
          • value

            StringOptional

            The vallue you want to change for a field on a pass.

      • template

        IntegerOptional

        The id of the template you want to update.

    • url

      StringOptional

      A url directly to the schedule.

      Format: url.

Response

  • 200

    Returns the schedule request along with identifiers for the operation and the schedule itself.

    Response Body

    application/json

    Type: Object

    • ok

      BooleanOptional

      If true, the operation completed successfully.

    • operation_id

      StringOptional

      Identifies the oepration for troubleshooting and logging.

      Format: uuid.

    • schedule_urls

      Array<String>Optional

      Urls for the schedules created by the opration. Items in the array are ordered just as they were in the request.

      Format: url.

    • schedules

      Array<Object>Optional
        • name

          StringOptional

          A name for the schedule.

        • schedule

          ObjectOptional
          • schedule_time

            StringOptional

            The date and time when the update will occur.

            Format: date-time.

        • update

          ObjectOptional

          The updates you want to make to an audience or pass, generated from a template within the project.

          • audience

            Audience SelectorOptional

            An audience selector forms the expression that determines the set of channels to target.

          • pass

            ObjectOptional
            • fields

              ObjectOptional
              • Field Title (String)

                ObjectOptional
                • value

                  StringOptional

                  The vallue you want to change for a field on a pass.

            • template

              IntegerOptional

              The id of the template you want to update.

          • url

            StringOptional

            A url directly to the schedule.

            Format: url.

Get a schedule

Example Request

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

Example Response

HTTP/1.1 200 OK

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

Return a single schedule.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to register schedule updates for.

  • scheduleId path

    StringRequired

    The _id of the schedule you want to return. This is appended to the end of the url in the response for schedule operations.

Response

  • 200

    Returns a single schedule object.

    Response Body

    application/json

    Type: Object

    Specifies updates to passes or adaptive links at a particular date and time.

    • name

      StringOptional

      A name for the schedule.

    • schedule

      ObjectOptional
      • schedule_time

        StringOptional

        The date and time when the update will occur.

        Format: date-time.

    • update

      ObjectOptional

      The updates you want to make to an audience or pass, generated from a template within the project.

      • audience

        Audience SelectorOptional

        An audience selector forms the expression that determines the set of channels to target.

      • pass

        ObjectOptional
        • fields

          ObjectOptional
          • Field Title (String)

            ObjectOptional
            • value

              StringOptional

              The vallue you want to change for a field on a pass.

        • template

          IntegerOptional

          The id of the template you want to update.

      • url

        StringOptional

        A url directly to the schedule.

        Format: url.

Update a schedule

Example Request

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

Example Response

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

Update a schedule. The payload to update a schedule is identical to the request to create a schedule.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to register schedule updates for.

  • scheduleId path

    StringRequired

    The _id of the schedule you want to return. This is appended to the end of the url in the response for schedule operations.

Request Body

application/json

Type: Object

Specifies updates to passes or adaptive links at a particular date and time.

  • name

    StringOptional

    A name for the schedule.

  • schedule

    ObjectOptional
    • schedule_time

      StringOptional

      The date and time when the update will occur.

      Format: date-time.

  • update

    ObjectOptional

    The updates you want to make to an audience or pass, generated from a template within the project.

    • audience

      Audience SelectorOptional

      An audience selector forms the expression that determines the set of channels to target.

    • pass

      ObjectOptional
      • fields

        ObjectOptional
        • Field Title (String)

          ObjectOptional
          • value

            StringOptional

            The vallue you want to change for a field on a pass.

      • template

        IntegerOptional

        The id of the template you want to update.

    • url

      StringOptional

      A url directly to the schedule.

      Format: url.

Response

  • 200

    Returns the updated schedule object.

    Response Body

    application/json

    Type: Object

    • ok

      BooleanOptional

      If true, the operation completed successfully.

    • operation_id

      StringOptional

      Identifies the oepration for troubleshooting and logging.

      Format: uuid.

    • schedule_urls

      Array<String>Optional

      URL for the updated schedule.

      Format: url.

    • schedules

      Array<Object>Optional
        • name

          StringOptional

          A name for the schedule.

        • schedule

          ObjectOptional
          • schedule_time

            StringOptional

            The date and time when the update will occur.

            Format: date-time.

        • update

          ObjectOptional

          The updates you want to make to an audience or pass, generated from a template within the project.

          • audience

            Audience SelectorOptional

            An audience selector forms the expression that determines the set of channels to target.

          • pass

            ObjectOptional
            • fields

              ObjectOptional
              • Field Title (String)

                ObjectOptional
                • value

                  StringOptional

                  The vallue you want to change for a field on a pass.

            • template

              IntegerOptional

              The id of the template you want to update.

          • url

            StringOptional

            A url directly to the schedule.

            Format: url.

Delete a schedule

Example Request

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

Example Response

HTTP/1.1 204 No Content
DELETE /schedules/{projectId}/{scheduleId}

Deletes the specified schedule.

Request Parameters

  • Api-Revision header

    StringRequired

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

    Possible values: 1.2.

  • projectId path

    StringRequired

    The project you want to register schedule updates for.

  • scheduleId path

    StringRequired

    The _id of the schedule you want to return. This is appended to the end of the url in the response for schedule operations.

Response

  • 204

    A deleted schedule returns not content.

Data Formats

Template Objects

Template objects vary based on the vender they're intended for, and the types of passes you want to create.

Optional Fields for Google Headers

Example Google Header Object with Optional Keys

{
  "background_color": {
    "ignoresTimeZone": null,
    "changeMessage": null,
    "label": "",
    "hideEmpty": false,
    "formatType": "String",
    "value": "#006491",
    "fieldType": "topLevel",
    "required": false
  }
}

Type: Object

Header objects for Google Pay templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

  • changeMessage

    StringOptional

    The message that appears when you update this field.

  • hideEmpty

    BooleanOptional

    If true, the field is hidden if empty.

  • ignoresTimeZone

    BooleanOptional

    if true, the date-time value in a field on an Apple Wallet pass is not offset to account for the pass recipient's time zone. This may be helpful for things like boarding passes or events, where your times are set local to an airport or venue and should not change based on a user's device. When applied to a non-date-time field or a Google template, this setting is ignored.

  • label

    StringOptional

    In most cases, you should not set a label for a Google template header. In responses, the label is typically an empty string.

  • required

    BooleanOptional

    Indicates whether or not the field is required on passes created from this template.

  • textAlignment

    StringOptional

    The alignment of text on the pass.

    Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural.

Google Pay Template Request

Example Google Template Request

{
  "infoModuleData": {
     "hexFontColor": "#666666",
     "hexBackgroundColor": "#0096e1",
     "Program ID": {
        "label": "Program ID",
        "value": "12345678",
        "row": 0,
        "col": 0,
        "formatType": "String"
     },
     "Tier Name": {
        "label": "Tier Name",
        "value": "Silver",
        "row": 0,
        "col": 1,
        "formatType": "String"
     },
     "Last Updated": {
        "label": "Last Updated",
        "value": "Five days ago",
        "row": 1,
        "col": 0,
        "formatType": "String"
     }
  },
  "headers": {
     "barcode_type": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     },
     "barcode_value": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     },
     "barcode_label": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     },
     "barcode_encoding": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     },
     "barcodeAltText": {
        "fieldType": "barcode",
        "value": "",
        "notShared": true
     }
  },
  "textModulesData": {
     "Program Details": {
        "header": "Program Details",
        "body": "Some Basic Text",
        "row": 0,
        "col": 0,
        "formatType": "String"
     }
  },
  "linksModuleData": {
     "Merchant Website": {
        "description": "Merchant Website",
        "uri": "http:\/\/www.test.com",
        "order": 1,
        "formatType": "URL"
     }
  },
  "messageModule": {
  },
  "imageModulesData": {
  },
  "pointsModule": {
     "Tier": {
        "label": "Tier",
        "value": 2,
        "row": 0,
        "col": 1,
        "formatType": "Number",
        "numberStyle": "PKNumberStyleDecimal"
     },
     "Points": {
        "label": "Points",
        "value": 1234,
        "row": 0,
        "col": 0,
        "formatType": "Number"
     }
  },
  "notAssigned": {
  },
  "titleModule": {
     "image": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
     "imageDescription": "Logo Image",
     "Program Name": {
        "label": "Program Name",
        "value": "UA",
        "row": 0,
        "col": 0,
        "formatType": "String"
    }
  },
  "vendor": "Google",
  "projectType": "memberCard",
  "type": "Loyalty1",
  "vendorId": 2,
  "deleted": "False",
  "description": "description",
  "name": "Adding Google"
}

Type: Object

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

    All of:
  • Type: Object

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

    • deleted

      BooleanOptional

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

    • description

      StringOptional

      A description for the template.

    • disabled

      BooleanOptional

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

    • name

      StringRequired

      The name of the template.

    • projectId

      IntegerOptional

      The id of the project the template belongs to.

    • projectType

      StringOptional

      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

      StringOptional

      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.

  • Type: Object

    Fields on a Google pass are organized into modules. Modules define how fields on the pass are organized and appear. Fields within each module are objects with a string names.

    • acctModule

      ObjectOptional

      Information associated with an account or membership. These are typically items like the accountIdLabel on Loyalty cards or balance items on a gift card.

      • Google Field Object

        ObjectOptional

        Represents a field on a Google pass. Each field is an object with a string name containing the following keys.

        Fields for Google templates belong to modules. Modules determine placement on the pass and, in some cases, the types of values for the field.

        • changeMessage

          StringOptional

          The message that appears when you update this field.

        • col(deprecated)

          IntegerOptional

          Determines vertical location/order within the fieldType. Use order instead.

        • hideEmpty

          BooleanOptional

          If true, the field is hidden if empty.

        • label

          StringRequired

          A label for the field; this is the field title as shown on the pass.

        • order

          IntegerOptional

          The order of fields with the same fieldType (Apple) or belonging to the same module (Google). if there are multiple fields with the same fieldType. Order begins at 0. For fields oriented vertically, 0 appears at the top of the fieldType (Apple) or module (Google); for fields oriented horizontally, a field with an order of 0 appears in the left-most postion.

        • required

          BooleanOptional

          Indicates whether or not the field is required on passes created from this template.

        • row(deprecated)

          IntegerOptional

          Determines horizontal location/order within the fieldType. Use order instead.

        • textAlignment

          StringOptional

          The alignment of text on the pass.

          Possible values: textAlignmentLeft, textAlignmentCenter, textAlignmentRight, textAlignmentNatural.

        • value

          ObjectRequired

          The default value for the field. The data type supported by this field is determined by the formatType.

            One of:
          • Type: String

          • Type: Number

          • Type: Integer

    • headers

      ObjectOptional

      Fields appearing in the headers object for a Google pass template. Header fields typically follow the same model as other fields for Google Pay templates and passes, but often have specific value, fieldType, and formatType values.

      • background_color

        ObjectOptional

        Sets the background color for the pass.

          All of:
        • Type: Optional Fields for Google Headers

          Header objects for Google Pay templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Type: Object

          • fieldType

            StringOptional

            Set to topLevel for color and text headers.

            Possible values: topLevel.

          • value

            StringOptional

            color objects take an rgb value in the format `rgb(255, 255, 255).

            Format: rgb. Pattern: rgb\({1,255}, {1,255}, {1,255}\).

      • background_image

        ObjectOptional

        A background image for the pass.

          All of:
        • Type: Optional Fields for Google Headers

          Header objects for Google Pay templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Type: Object

          • fieldType

            StringOptional

            Indicates that the value is an image.

            Possible values: image.

          • formatType

            StringOptional

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Urban Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String.

          • value

            StringOptional

            The url for the header image.

            Format: url.

      • barcodeAltText

        ObjectOptional

        Alternate text displayed below the barcode.

          All of:
        • Type: Optional Fields for Google Headers

          Header objects for Google Pay templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Type: Object

          • fieldType

            StringOptional

            Set to "barcode" for all barcode headers.

            Possible values: barcode.

          • formatType

            StringOptional

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Urban Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String.

          • value

            StringOptional

            The alternate text for the barcode on the template.

      • barcode_encoding

        ObjectOptional

        Encoding The encoding format for the barcode.

          All of:
        • Type: Optional Fields for Google Headers

          Header objects for Google Pay templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Type: Object

          • fieldType

            StringOptional

            Set to "barcode" for all barcode headers.

            Possible values: barcode.

          • formatType

            StringOptional

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Urban Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String.

          • value

            StringOptional

            Presently, iso-8859-1 is the only supported value.

            Possible values: iso-8859-1.

      • barcode_type

        ObjectOptional

        The type of barcode supported by the template. This value must be the same as the barcode_type set at the project level.

          All of:
        • Type: Optional Fields for Google Headers

          Header objects for Google Pay templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Type: Object

          • fieldType

            StringOptional

            Set to "barcode" for all barcode headers.

            Possible values: barcode.

          • formatType

            StringOptional

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Urban Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String.

          • value

            StringOptional

            Presently, iso-8859-1 is the only supported value.

            Possible values: pdf417, aztec, code128, qr, upc-a, ean-13, code-39.

      • barcode_value

        ObjectOptional

        The default value for the barcode used by the template.

          All of:
        • Type: Optional Fields for Google Headers

          Header objects for Google Pay templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.

        • Type: Object

          • fieldType

            StringOptional

            Set to "barcode" for all barcode headers.

            Possible values: barcode.

          • formatType

            StringOptional

            Indicates that the field takes a string value. While the formatType for non-header fields can be another data type, header fields always take string values.

            In general, you do not have to set this value. Urban Airship can determine the formatType from the fieldType, and objects in the headers array are always String types.

            Possible values: String.

          • value

            StringOptional

            This value is a default for the barcode. You may set a new or personalized value when creating adaptive links or passes.

      • footer_image

        Object