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.
If you want to use external IDs, you should use them for all assets — projects, templates, passes, etc.
In general you can support External IDs by appending /id/{externalId} to an endpoint path that would either take or generate a standard id.
Base URL
- The base URL for Wallet endpoints, including the API major version number. In addition to the major version, all requests must include an
Api-Revisionheader, with a more specific version number e.g.1.2. - The deprecated base URL for Wallet (fka Reach) endpoints. Use https://wallet-api.urbanairship.com/v1 instead.
Authentication
HTTP Authentication
basic masterAll Wallet operations use basic authorization. The authorization header contains the word
Basicfollowed 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.2Example 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
}
}List the projects belonging to you.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.pageSize query
IntegerOptionalThe number of results per page.
page query
IntegerOptionalThe page of the search you want to return.
order query
StringOptionalDetermines the order of results.
Possible values:
id,name,createdAt,updatedAt.direction query
StringOptionalThe 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
StringOptionalThe total number of results.
pagination
ObjectOptionalContains information about pagination, according to your query parameters.
direction
StringOptionalThe direction of results, ascending or descending.
Possible values:
ASC,DESC.order
StringOptionalThe key in the result set that you want to order results by. Defaults to
id.page
IntegerOptionalThe page you are on. Multiply by the page size to determine the result set on the page.
pageSize
IntegerOptionalThe number of results per page.
start
IntegerOptionalThe first result on the page; results begin with 0.
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"
}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
StringRequiredThe 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.2Example 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"
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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.2Example 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 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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe 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"
}Update a project with a given external ID.
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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe 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"
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe 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.2Example 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 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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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"
}Update a project.
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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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.
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.2Example Response
HTTP/1.1 200 OK
{
"templateId": 12346
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.template_id path
StringRequiredThe
idof 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
IntegerOptionalThe 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.2Example 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"
}
}List the headers for templates you created.
Security:
Request Parameters
Api-Revision header
StringRequiredThe 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
StringOptionalThe total number of results.
pagination
ObjectOptionalContains information about pagination, according to your query parameters.
direction
StringOptionalThe direction of results, ascending or descending.
Possible values:
ASC,DESC.order
StringOptionalThe key in the result set that you want to order results by. Defaults to
id.page
IntegerOptionalThe page you are on. Multiply by the page size to determine the result set on the page.
pageSize
IntegerOptionalThe number of results per page.
start
IntegerOptionalThe first result on the page; results begin with 0.
templateHeaders
Array<Object>OptionalA list of template header objects.
- All of:
Type: Object
createdAt
StringOptionalThe date and time when the item was created.
Format:
date-time.id
IntegerOptionalThe identifier for the template. You can recall the template by ID in other operations.
updatedAt
StringOptionalThe 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
BooleanOptionalIf true, the template is deleted. You can no longer create passes from this template.
description
StringOptionalA description for the template.
disabled
BooleanOptionalIf true, the template is disabled; you cannot create new passes for this template until you update the template and enable it again.
name
StringRequiredThe name of the template.
projectId
IntegerOptionalThe
idof the project the template belongs to.projectType
StringOptionalThe type of pass the template supports; matches the
typesetting for the parent project.Possible values:
memberCard,coupon,boardingPass,eventTicket,generic,loyalty,giftCard.type
StringOptionalThe type of pass the template supports. This value corresponds to the
projectType.Possible values:
memberCard,coupon,boardingPass,eventTicket,generic,loyalty,giftCard.vendor
StringRequiredThe device vendor the template is designed for, Apple or Google.
Possible values:
Apple,Google.vendorId
IntegerRequiredCorresponds to the
vendorthe template supports.1indicates an Apple template;2indicates 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.2Delete location from template with an External ID.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe external ID of the template you want to remove a location from.
locationId path
StringRequiredThe 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
}
]Add locations to a template with an externalId.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe 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
IntegerOptionalThe identifier for a location
fieldId
IntegerOptionalRepresents 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.2Example 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 the template specified by the externalId.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.templateExternalId path
StringRequiredThe
externalIdof 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
StringOptionalThe date and time when the item was created.
Format:
date-time.id
IntegerOptionalThe identifier for the template. You can recall the template by ID in other operations.
updatedAt
StringOptionalThe 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
}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.
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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.templateExternalId path
StringRequiredThe
externalIdof 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
idto reference the template in subsequent operations.Response Body
application/json; charset=utf-8
Type: Object
templateId
IntegerOptionalThe identifier for the template. You can recall the template by ID in other operations.
Delete Template with External ID
Delete the specified template.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.templateExternalId path
StringRequiredThe
externalIdof 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
IntegerOptionalThe identifier of the deleted template.
status
StringOptionalIndicates 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.2Example 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 the template specified by the id.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.Id path
StringRequiredThe
templateIdof 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
StringOptionalThe date and time when the item was created.
Format:
date-time.id
IntegerOptionalThe identifier for the template. You can recall the template by ID in other operations.
updatedAt
StringOptionalThe 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"
}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.
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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.Id path
StringRequiredThe
templateIdof 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
idto reference the template in subsequent operations.Response Body
application/json; charset=utf-8
Type: Object
templateId
IntegerOptionalThe 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
}Create a template within the specified project. A template is specific to a vendor platform, Apple or Google.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.Id path
StringRequiredThe
projectIdof 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
idto reference the template in subsequent operations.Response Body
application/json; charset=utf-8
Type: Object
templateId
IntegerOptionalThe 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.2Example Response
HTTP/1.1 200 OK
{
"status": "Deleted",
"TemplateID": "12345"
}Delete the specified template.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.Id path
StringRequiredThe
templateIdof the template you want to delete.
Response
200
Returns the status of the deleted template.
Response Body
application/json
Type: Object
TemplateId
IntegerOptionalThe identifier of the deleted template.
status
StringOptionalIndicates 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
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.id path
StringRequiredEither the
idof the template you want to issue an update for or theexternalIdof 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
ObjectOptionalField Name (String)
ObjectOptionalvalue
StringOptionalThe
valuekey 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
IntegerOptionalA 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
}Create a template within the specified project. A template is specific to a vendor platform, Apple or Google.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project you want to associate your new template with.
templateExternalId path
StringRequiredThe 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
idto reference the template in subsequent operations.Response Body
application/json; charset=utf-8
Type: Object
templateId
IntegerOptionalThe 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
}
]Add locations to the specified template.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.template_id path
StringRequiredThe 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
IntegerOptionalThe identifier for a location
fieldId
IntegerOptionalRepresents 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.2Remove a location from template.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.template_id path
StringRequiredThe template you want to remove a location from.
location_id path
StringRequiredThe ID of the location you want to remove.
Response
200
A succesful response returns ??
Response Body
application/json; charset=utf-8
Type: Object
Apple Wallet Pass Personalization
Adding personalization to an Apple Wallet loyalty template creates a pass that prompts the user for relevant personal information when signing up for a rewards program. These endpoints help you manage the personalizeable information that you require users to provide when signing up for your loyalty/rewards program.
Get personalization requirements
Example Request
GET /v1/{template_id}/personalization HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2Example Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}Returns personalization requirements for a template.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.template_id path
StringRequiredThe loylalty card template you want to add, modify, or retrieve personalization information for.
Response
200
Your template has the following personalization requirements.
Update personalization requirements
Example Request
PUT /v1/{template_id}/personalization HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}Example Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}When updating personalization requirements for a template, you must provide a complete payload. This request overwrites all previous personalization requirements attached to the template; any information you leave out of this request will be removed from the personalization requirements for the template.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.template_id path
StringRequiredThe loylalty card template you want to add, modify, or retrieve personalization information for.
Request Body
application/json
Type: Apple Pass Personalization Requirements
Response
200
Your personalization requirements have been updated for the template.
Add personalziation requirements
Example Request
POST /v1/{template_id}/personalization HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}Example Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}Adds personalization requirements to a template. When a user attempts to install a pass with personalization requirements, they are first prompted for the requiredPersonalizationFields specified in this payload. When the user fills out the information and accepts the terms and conditions (if present), they receive a personalized pass.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.template_id path
StringRequiredThe loylalty card template you want to add, modify, or retrieve personalization information for.
Request Body
application/json
Type: Apple Pass Personalization Requirements
Response
200
Your personalization requirements have been added to the template.
Remove personalization requirements
Example Request
DELETE /v1/{template_id}/personalization HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2Example Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}Removes personalization requirements from a template.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.template_id path
StringRequiredThe loylalty card template you want to add, modify, or retrieve personalization information for.
Response
200
Your personalization requirements removed from the template.
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/jsonExample 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
}
]
}Returns a list of Adaptive Links.
Security:
Request Parameters
Api-Revision header
StringRequiredThe 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
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
}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
StringRequiredThe 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: Adaptive Link 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"
},
]
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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
idorexternalIdof an iOS or Android template. You can create the event within this request or specify an event byeventIdoreventExternalId. 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 the payload includes flight information and an array of passengers for each flight.
Like other adaptive links, you must provide the
idorexternalIdof 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
flightsoreventsarray.Response Body
application/json
Type: Object
links
Array<Object>OptionalAn array of adaptive links.
- One of:
Type: Object
The boarding pass operations return responses like other adaptive links, with the addition of the identifier of the event and an HTTP status for each individual adaptive link.
Like other adaptive links, you must provide the
idorexternalIdof an iOS or Android template. You can provide- All of:
Type: Adaptive Link Response
An adaptive link response includes URLs that users can access to detect and install a pass.
Type: Object
flightExternalId
StringOptionalAn external, custom identifier for a flight. You can reference flights by
flightExternalIdrather than the Urban Airship-generatedflightId.When creating boarding passes, if you specify an existing flight by
flightExternalId, you do not need to provide flight information in thefieldsobject. If creating a new flight in thefieldsobject, you can assign a newflightExternalIdto the new flight.flightId
IntegerOptionalA unique, auto-generated identifier for a flight.
When creating boarding passes, if you specify a flight by ID, you do not need to define the flight in the
fieldsobject.status
IntegerOptionalThe HTTP status code for the adaptive link operation.
Type: Object
The response for event ticket operations is much like any other adaptive link, with the addition of the identifier of the event and an HTTP status for each individual adaptive link.
- All of:
Type: Adaptive Link Response
An adaptive link response includes URLs that users can access to detect and install a pass.
Type: Object
eventExternalId
StringOptionalAn external identifier for an event. You can only assign an external identifier when creating an event. If you do assign an external identifier, requests for events or passes referencing the event will return the external ID in addition to the
eventIdcreated within Urban Airship.eventId
IntegerOptionalThe Urban Airship-created identifier for an event.
status
IntegerOptionalThe HTTP status code for the adaptive link operation.
Get an adaptive link
Example Request
GET /v1/links/adaptive/<adaptiveLinkId> HTTP/1.1
Authorization: Basic <authorization string>
Content-type: application/jsonExample 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
}Returns information about a single adaptive link.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.adaptiveLinkId path
StringRequiredThe adaptive link you want to return or update.
Response
200
Lists urls and available passes for an individual link
Response Body
application/json
Type: Adaptive Link 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
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.adaptiveLinkId path
StringRequiredThe 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: Adaptive Link Response
An adaptive link response includes URLs that users can access to detect and install a pass.
Delete an adaptive link
Deletes an adaptive link.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.adaptiveLinkId path
StringRequiredThe adaptive link you want to return or update.
Response
200
The adaptive link was successfully deleted. A successful operation returns no content.
Create Pass from Adaptive Link
Generates a pass from an adaptive link.
When generating passes this way, you can append request parameters mapping to pass fields to the URL to add or update values to the pass at creation time. While this document lists reserved parameters, you can provide the fieldName=value for any field contained in the adaptive link.
If you configured your Adaptive Link object with the isPersonalized flag set to false (or the flag is absent), the first request will create a pass, and subsequent requests will create new instances of this same pass. If the isPersonalized flag is true, every request will create a new pass. If a request includes url-encoded parameters, the isPersonalized flag is considered true and Urban Airship will always create a new pass for every request (instead of a pass instance).
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.adaptiveLinkId path
StringRequiredThe identifier of the adaptive link you want to create a pass from
device_type path
StringRequiredThe device type the user needs to install.
If a device type is not specified in the path, Urban Airship detects the device type from the request headers. If the device type cannot be detected Urban Airship redirects the request to a landing page URL provided by the client as part of the Adaptive Link metadata. Urban Airship recommends that this landing page provide buttons that link to the explicit device-specific Dynamic Link URLs for iOS and Android pass generation (e.g. this endpoint with the appropriate device type path parameter).
Possible values:
ios,android,web.barcode query
StringOptionalSets the barcode value for the new pass
barcodeAltText query
StringOptionalThe alternative text for the barcode on the pass. If unspecified, the barcode value is used as the barcodeAltText.
tags query
StringOptionalTags you want to associate with the pass.
exid query
StringOptionalThe external_id you want to set for this pass.
lat query
StringOptionalThe latitude of the device installing the pass, used to calculate distance to locations specified in the adaptive link.
long query
StringOptionalThe longitude of the device installing the pass, used to calculate distance to locations specified in the adaptive link.
Response
200
This endpoint produces responses specific to the device type specified in the request. Requests for iOS passes return a .pkpass file; requests for Android passes return a deep link for the pass; requests for
webdevices or without the device type specified return the landing page URL that a user can access to manually select a device type and install the pass.Response Body
application/json
Type: Object
A publicUrl for android users, or the landing page url if the device type was set to
webor was not specified.Response Body
application/vnd.apple.pkpass
Type: Object
A .pkpass file for iOS users
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.2Example Response
{
"count": 1043,
"passes":[
{
"id": "12345",
"templateId": "12345",
"updatedAt": "2013-06-27T20:58:20.000Z",
"createdAt": "2013-06-27T20:58:18.000Z",
"serialNumber": "ff9db2ed-37aa-4691-a3b6-240108ac31f9",
"url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/1273\/download"
},
{
"id": "12346",
"templateId": "12346",
"updatedAt": "2013-06-27T20:56:07.000Z",
"createdAt": "2013-06-27T20:56:03.000Z",
"serialNumber": "a2ea965a-0917-461d-ac67-749639831818",
"url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/1272\/download"
}
],
"pagination": {
"order": "id",
"page": 1,
"start": 0,
"direction": "DESC",
"pageSize": 2
}
}List 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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.template query
StringOptionalThe
idof 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
IntegerOptionalThe total number of passes associated with the template.
pagination
ObjectOptionalContains information about pagination, according to your query parameters.
direction
StringOptionalThe direction of results, ascending or descending.
Possible values:
ASC,DESC.order
StringOptionalThe key in the result set that you want to order results by. Defaults to
id.page
IntegerOptionalThe page you are on. Multiply by the page size to determine the result set on the page.
pageSize
IntegerOptionalThe number of results per page.
start
IntegerOptionalThe first result on the page; results begin with 0.
passes
Array<Object>OptionalThe metadata for passes associated with the template. Each object in the array represents a pass.
createdAt
StringOptionalThe date and time when the item was last updated.
Format:
date-time.id
IntegerOptionalThe internal identifier for the pass. Use this ID to get or modify the pass in other calls.
serialNumber
StringOptionalThe serial number of the pass.
templateId
IntegerOptionalThe identifier for the template. You can recall the template by ID in other operations.
updatedAt
StringOptionalThe date and time when the item was created.
Format:
date-time.url
StringOptionalThe 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.2Example 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 the specified pass.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe
externalIdof 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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
}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.
You can also update a pass to include an expiration date using the expirationDate key.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe
externalIdof 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
You can only include beacons for Apple Wallet passes.
fields
ObjectOptionalheaders
ObjectOptional
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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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
}
]
}Create a pass from the specified template by externalId.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe
externalIdof 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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 the specified pass.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe
externalIdof the pass you want to modify
Response
200
The pass was successfully deleted.
Response Body
application/json
Type: Object
PassId
IntegerOptionalThe internal identifier for the pass. Use this ID to get or modify the pass in other calls.
status
StringOptionalIndicates 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.2Delete the specified location from a pass using an External ID.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe
externalIdof the pass you want to remove locations from.locationId path
StringRequiredThe location you want to remove from the pass.
Response
200
Success.
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"
}
}
]Add the locations to the specified pass
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
StringRequiredThe externalId of the pass you want to add locations to.
Request Body
Set locations for the pass.
application/json
Type: Object
Response
200
Returns
passLocationIdfor 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
IntegerOptionalThe identifier for a location
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
}
]
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.templateExternalId path
StringRequiredThe
externalIdof the template you want to create your pass from.passExternalId path
StringRequiredThe
externalIdthat 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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 a Dynamic Link
Example Request
POST /v1/pass/(templateId)/dynamic&expiry=2017-05-18 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2014-08-20T09:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage" : null,,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.store.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
],
"publicURL": {
"type": "single"
},
"externalId": "abcd"
}Example Request with Payload
{
"url": "https://wallet-api.urbanairship.com/v1/pass/dynamic/44e128a5-ac7a-4c9a-be4c-224b6bf81b20","message": "Existing Dynamic Link"
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.Id path
StringRequiredThe
templateIdof the template you want to create the pass from.expiry query
StringOptionalThe 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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.2Example 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 the specified pass.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.id path
StringRequiredThe
idof 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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
}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.
You can also update a pass to include an expiration date using the expirationDate key.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.id path
StringRequiredThe
idof 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
You can only include beacons for Apple Wallet passes.
fields
ObjectOptionalheaders
ObjectOptional
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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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
}
]
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.id path
StringRequiredThe
idof 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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.2Example Response
{
"Status": "Deleted",
"PassID": "123"
} Delete the specified pass.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.id path
StringRequiredThe
idof the pass you want to delete.
Response
200
The pass was successfully deleted.
Response Body
application/json
Type: Object
PassId
IntegerOptionalThe internal identifier for the pass. Use this ID to get or modify the pass in other calls.
status
StringOptionalIndicates 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.2Delete the specified location from the specified pass.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.passId path
StringRequiredThe
idof the pass you want to remove locations from.passLocationId path
StringRequiredThe location you want to remove from the pass.
Response
200
Success.
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"
}
}
]Add the locations to the specified pass
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.passId path
StringRequiredThe pass you want to add locations to.
Request Body
Set locations for the pass.
application/json
Type: Object
Response
200
Returns
passLocationIdfor 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
IntegerOptionalThe identifier for a location
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
}
]
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.templateId path
StringRequiredThe the template you want to create your pass from.
passExternalId path
StringRequiredThe
externalIdyou 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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
fieldsModelcontains fields nested inside "module" objects, fields are collapsed in pass requests and responses. ThefieldTypecorresponds 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.2Example 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 a pass.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.id path
StringRequiredThe 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
IntegerOptionalThe total number of passes associated with the template.
pagination
ObjectOptionalContains information about pagination, according to your query parameters.
direction
StringOptionalThe direction of results, ascending or descending.
Possible values:
ASC,DESC.order
StringOptionalThe key in the result set that you want to order results by. Defaults to
id.page
IntegerOptionalThe page you are on. Multiply by the page size to determine the result set on the page.
pageSize
IntegerOptionalThe number of results per page.
start
IntegerOptionalThe first result on the page; results begin with 0.
passes
Array<Object>OptionalThe metadata for passes associated with the template. Each object in the array represents a pass.
createdAt
StringOptionalThe date and time when the item was last updated.
Format:
date-time.id
IntegerOptionalThe internal identifier for the pass. Use this ID to get or modify the pass in other calls.
serialNumber
StringOptionalThe serial number of the pass.
templateId
IntegerOptionalThe identifier for the template. You can recall the template by ID in other operations.
updatedAt
StringOptionalThe date and time when the item was created.
Format:
date-time.url
StringOptionalThe 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.2Example 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"
}
]
}List tags assigned to the specified pass.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.passId path
StringRequiredThe
idof 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>OptionalAn array of tags associated with the pass.
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
}Add tags to a pass, limited to 15 tags per pass.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.passId path
StringRequiredThe
idof 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>RequiredAn 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
IntegerOptionalThe number of tags added.
newTags
Array<String>OptionalA 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.2Example 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
}List all tags.
Security:
Request Parameters
Api-Revision header
StringRequiredThe 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
ObjectOptionalContains information about pagination, according to your query parameters.
count
IntegerOptionalThe number of items returned.
tags
Array<Object>Optional
Delete Tag
Example Request
DELETE /v1/tag/tag-name HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Example Response
{
"status": "success",
"tagId": 5,
"count": 93
}Delete the specified tag and remove it from all passes.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.tag path
StringRequiredThe tag you want to delete.
Response
200
A successful operation returns a count of affected passes.
Response Body
application/json
Type: Object
count
IntegerOptionalThe number of passes the tag was removed from.
status
StringOptionalThe oepration was successful.
Possible values:
success.tagId
IntegerOptionalThe
idof 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.2Example Response
{
"passId": 123,
"status": "success",
"tagId": 70
}Remove a tag from the specified pass.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.tag path
StringRequiredThe tag you want to remove.
pass path
StringRequiredThe 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
IntegerOptionalThe
idof the pass that the tag was removed from.status
StringOptionalThe oepration was successful.
Possible values:
success.tagId
IntegerOptionalThe
idof 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.2Example 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
}
}List the passes associated with the specified tag.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.tag path
StringRequiredA tag
idorname. 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
IntegerOptionalThe total number of results.
pagination
ObjectOptionalContains information about pagination, according to your query parameters.
direction
StringOptionalThe direction of results, ascending or descending.
Possible values:
ASC,DESC.order
StringOptionalThe key in the result set that you want to order results by. Defaults to
id.page
IntegerOptionalThe page you are on. Multiply by the page size to determine the result set on the page.
pageSize
IntegerOptionalThe number of results per page.
start
IntegerOptionalThe first result on the page; results begin with 0.
passes
ObjectOptionalMeta information about passes.
createdAt
StringOptionalThe date and time when the item was last updated.
Format:
date-time.id
IntegerOptionalThe internal identifier for the pass. Use this ID to get or modify the pass in other calls.
serialNumber
StringOptionalThe serial number of the pass.
templateId
IntegerOptionalThe identifier for the template. You can recall the template by ID in other operations.
updatedAt
StringOptionalThe date and time when the item was created.
Format:
date-time.url
StringOptionalThe 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
}Update all of the passes that have a given tag.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.tag path
StringRequiredThe 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
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.2Example Response
{
"passId": 123,
"status": "success",
"tagId": 70
}Remove this tag from all of its passes.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.tag path
StringRequiredThe tag you want to remove.
Response
200
A successful response returns a count of the affected passes.
Response Body
application/json
Type: Object
count
IntegerOptionalThe number of passes the tag was removed from.
status
StringOptionalThe oepration was successful.
Possible values:
success.tagId
IntegerOptionalThe
idof 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"
}
]
}List meta information for all segments.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe
idof 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>Optionalcreation_date
StringOptionalThe date and time when the item was created.
Format:
date-time.display_name
StringOptionalThe name of the segment.
id
StringOptionalThe identifier for the segment, used to identify the segment in other operations.
Format:
uuid.modification_date
StringOptionalThe 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"
}Create a segment for a project.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe
idof the project you want to copy.
Request Body
Contains and, or, or not operators for tags that identify your segment.
application/json
Type: Object
Boolean tag selectors specifying a group of passes. You can nest
ANDandORselectors.display_name
StringOptionalThe 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
BooleanOptionalIf true, the operation completed successfully.
operationId
StringOptionalAn identifier for the operation. Use this value to reference the operation for troubleshooting purposes.
Format:
uuid.segmentId
StringOptionalAn 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"
}Returns the selector criteria for a segment.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project containing the segment you want to look up.
segmentId path
StringRequiredThe segment you want to look up.
Response
200
A successful request returns the selection criteria for the segment.
Response Body
application/json
Type: Object
Boolean tag selectors specifying a group of passes. You can nest
ANDandORselectors.display_name
StringOptionalThe 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"
}Update selection criteria or the display name for a segment.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project containing the segment you want to look up.
segmentId path
StringRequiredThe segment you want to look up.
Request Body
application/json
Type: Object
Boolean tag selectors specifying a group of passes. You can nest
ANDandORselectors.display_name
StringOptionalThe 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
BooleanOptionalIf true, the operation completed successfully.
operationId
StringOptionalAn identifier for the operation. Use this ID to reference the operation for troubleshooting purposes.
Format:
uuid.segmentId
StringOptionalAn 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.2Example Response
HTTP/1.1 204 No ContentDelete 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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project containing the segment you want to look up.
segmentId path
StringRequiredThe 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
Returns information for a single flight.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectExternalId path
StringRequiredThe project you want to create the flight in.
flightExternalId path
StringRequiredThe external identifier you want to give to the flight.
Response
200
A successful request returns the
flightIdandflightExternalId(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
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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectExternalId path
StringRequiredThe project you want to create the flight in.
flightExternalId path
StringRequiredThe 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
flightIdandflightExternalId(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
Create flights
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectExternalId path
StringRequiredThe project you want to create the flight in.
flightExternalId path
StringRequiredThe 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
flightIdandflightExternalId(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
Deletes the specified flight.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectExternalId path
StringRequiredThe project you want to create the flight in.
flightExternalId path
StringRequiredThe external identifier you want to give to the flight.
Response
200
The flight was deleted.
Response Body
application/json
Type: Object
ok
BooleanOptionalIf 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"
}
}
}Create flights
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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
flightIdandflightExternalId(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"
}
}
}Returns information for a single flight.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project that the flight belongs to.
flightId path
IntegerRequiredThe flight you want to get, update, or delete.
Response
200
A successful request returns the
flightIdandflightExternalId(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"
}
}
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project that the flight belongs to.
flightId path
IntegerRequiredThe 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
flightIdandflightExternalId(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.2Example Response
HTTP/1.1 200 OKDeletes the specified flight.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project that the flight belongs to.
flightId path
IntegerRequiredThe flight you want to get, update, or delete.
Response
200
The flight was deleted.
Response Body
application/json
Type: Object
ok
BooleanOptionalIf 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"
}
}
}Returns information about a single event.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectExternalId path
StringRequiredThe external ID of the project you want to create the event in.
eventExternalId path
StringRequiredA custom idetnfier for an event. This is the event you want to create, get, modify, or delete.
Response
200
A successful request returns the
eventIdandeventExternalId(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"
}
}
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectExternalId path
StringRequiredThe external ID of the project you want to create the event in.
eventExternalId path
StringRequiredA 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
eventIdandeventExternalId(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"
}
}
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectExternalId path
StringRequiredThe external ID of the project you want to create the event in.
eventExternalId path
StringRequiredA 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
eventIdandeventExternalId(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
Deletes the specified event.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectExternalId path
StringRequiredThe external ID of the project you want to create the event in.
eventExternalId path
StringRequiredA 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
BooleanOptionalIf 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"
}
}
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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
eventIdandeventExternalId(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"
}
}
}Returns information about a single event.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project that the event belongs to.
eventId path
IntegerRequiredThe event you want to get, update, or delete.
Response
200
A successful request returns the
eventIdandeventExternalId(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"
}
}
}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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project that the event belongs to.
eventId path
IntegerRequiredThe 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
eventIdandeventExternalId(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
Deletes the specified event.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe project that the event belongs to.
eventId path
IntegerRequiredThe event you want to get, update, or delete.
Response
200
The event was deleted.
Response Body
application/json
Type: Object
ok
BooleanOptionalIf 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"
}
}Return the callback specification for a project.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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
/callbackendpoints.baseUrl
StringOptionalThe URL of your webhook/callback server.
headers
ObjectOptionalContains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Urban Airship appends
content-type: application/jsonand 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"
}
}Update a callback specification. The payload to update a callback is identical to the payload to create a callback.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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
StringOptionalThe URL of your webhook/callback server.
headers
ObjectOptionalContains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Urban Airship appends
content-type: application/jsonand 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
/callbackendpoints.baseUrl
StringOptionalThe URL of your webhook/callback server.
headers
ObjectOptionalContains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Urban Airship appends
content-type: application/jsonand 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"
}
}Register a callback specification which includes remote the URL and any HTTP headers required by remote URL
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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
StringOptionalThe URL of your webhook/callback server.
headers
ObjectOptionalContains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Urban Airship appends
content-type: application/jsonand 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
/callbackendpoints.baseUrl
StringOptionalThe URL of your webhook/callback server.
headers
ObjectOptionalContains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Urban Airship appends
content-type: application/jsonand 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 ContenDelete a registered callback specification. Because a project only uses a single callback specification, you specify the projectId only.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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.1Example Response
{
"Hello": "World"
}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
StringOptionalA "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 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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.ticketId path
StringRequiredThe ticket you want to know the status of.
Response
200
Returns the status of a ticket.
Response Body
application/json
Type: Object
ID
IntegerOptionalThe identifier of the ticket.
children
ObjectOptionalcreatedAt
StringOptionalThe date and time when the item was created.
Format:
date-time.status
StringOptionalThe status of the ticket.
Statistics
Get pass creation, installation, and uninstallation counts for projects and templates.
Endpoints for /activity report net total activities, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, a response will show two passes installed and one pass removed. Endpoints for /stats will not count repeated actions from the same user.
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.2Example 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
}
}
]
}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.
This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
IntegerRequiredThe
externalIdof 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
createdAtdate.Response Body
application/json
Type: Object
details
Array<Object>OptionalEach object in this array represents pass activity for a single day. Each object represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the object shows two passes installed and one pass removed.
activity
ObjectOptionalRepresents activity for a template or project.
created
IntegerOptionalThe number of passes created.
installed
IntegerOptionalThe number of passes that were installed.
uninstalled
IntegerOptionalThe number of passes that were uninstalled.
date
StringOptionalThe 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
StringOptionalThe end date for a statistics report.
Pattern:
([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).id
IntegerOptionalThe
idof the project specified in the pathstartDate
StringOptionalThe start date for a statistics report.
Pattern:
([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).summary
ObjectOptionalRepresents activity for a template or project.
created
IntegerOptionalThe number of passes created.
installed
IntegerOptionalThe number of passes that were installed.
uninstalled
IntegerOptionalThe 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.2Example 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
}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.
This endpoint does not count repeated actions by the same user.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
IntegerRequiredThe
externalIdof 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
IntegerOptionalThe identifier for the project.
installed
IntegerOptionalThe total number of passes from this project that are installed.
lastUpdated
StringOptionalThe date and time when the item was last updated.
Format:
date-time.templates
Array<Object>OptionalContains statistics for each template belonging to the project.
id
IntegerOptionalThe identifier for a specific template.
installed
IntegerOptionalThe total number of passes from this template that are installed.
lastUpdated
StringOptionalThe date and time when the item was last updated.
Format:
date-time.total
IntegerOptionalThe total number of passes created from the template.
uninstalled
IntegerOptionalThe total number of passes created from this template that are uninstalled.
vendor
StringOptionalThe device vendor the template is designed for, Apple or Google.
Possible values:
Apple,Google.
total
IntegerOptionalThe total number of passes created in the project.
uninstalled
IntegerOptionalThe 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.2Example 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
}
}
]
}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.
This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
IntegerRequiredThe
idof 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
createdAtdate.Response Body
application/json
Type: Object
details
Array<Object>OptionalEach object in this array represents pass activity for a single day. Each object represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the object shows two passes installed and one pass removed.
activity
ObjectOptionalRepresents activity for a template or project.
created
IntegerOptionalThe number of passes created.
installed
IntegerOptionalThe number of passes that were installed.
uninstalled
IntegerOptionalThe number of passes that were uninstalled.
date
StringOptionalThe 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
StringOptionalThe end date for a statistics report.
Pattern:
([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).id
IntegerOptionalThe
idof the project specified in the pathstartDate
StringOptionalThe start date for a statistics report.
Pattern:
([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).summary
ObjectOptionalRepresents activity for a template or project.
created
IntegerOptionalThe number of passes created.
installed
IntegerOptionalThe number of passes that were installed.
uninstalled
IntegerOptionalThe 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.2Example 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
}Returns Statistics for a given template by id. This endpoint does not count repeated actions by the same user.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
IntegerRequiredThe
idof 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
IntegerOptionalThe identifier for the project.
installed
IntegerOptionalThe total number of passes from this project that are installed.
lastUpdated
StringOptionalThe date and time when the item was last updated.
Format:
date-time.templates
Array<Object>OptionalContains statistics for each template belonging to the project.
id
IntegerOptionalThe identifier for a specific template.
installed
IntegerOptionalThe total number of passes from this template that are installed.
lastUpdated
StringOptionalThe date and time when the item was last updated.
Format:
date-time.total
IntegerOptionalThe total number of passes created from the template.
uninstalled
IntegerOptionalThe total number of passes created from this template that are uninstalled.
vendor
StringOptionalThe device vendor the template is designed for, Apple or Google.
Possible values:
Apple,Google.
total
IntegerOptionalThe total number of passes created in the project.
uninstalled
IntegerOptionalThe 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.2Example 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
}
}
]
}Returns day-by-day activity of passes created, installed, and uninstalled for a template specified 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.
This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
IntegerRequiredThe
externalIdof 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
createdAtdate.Response Body
application/json
Type: Object
details
Array<Object>OptionalEach object in this array represents pass activity for a single day.
activity
ObjectOptionalRepresents activity for a template or project.
created
IntegerOptionalThe number of passes created.
installed
IntegerOptionalThe number of passes that were installed.
uninstalled
IntegerOptionalThe number of passes that were uninstalled.
date
StringOptionalThe 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
StringOptionalThe end date for a statistics report.
Pattern:
([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).id
IntegerOptionalThe
idof the template specified in the path.startDate
StringOptionalThe start date for a statistics report.
Pattern:
([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).summary
ObjectOptionalRepresents activity for a template or project.
created
IntegerOptionalThe number of passes created.
installed
IntegerOptionalThe number of passes that were installed.
uninstalled
IntegerOptionalThe number of passes that were uninstalled.
vendor
StringOptionalThe 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.2Example Response
{
"id": 12345,
"vendor": "Apple",
"lastUpdated": "2015-10-01T20:15:28.000-07:00",
"total": 7,
"installed": 0,
"uninstalled": 0
}Returns Statistics for a given template by external ID, including the total number of passes installed and uninstalled based on the template. The response payload lists the internal Wallet id for the template, rather than the external ID.
This endpoint does not count repeated actions by the same user.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.externalId path
IntegerRequiredThe
idof 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
IntegerOptionalThe template specified in the request.
installed
IntegerOptionalThe number of installed passes based on this template.
lastUpdated
StringOptionalThe date and time when the item was last updated.
Format:
date-time.total
IntegerOptionalA count of the total number of passes created from the template.
uninstalled
IntegerOptionalThe number of uninstalled passes based on this template.
vendor
StringOptionalThe 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.2Example 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
}
}
]
}Returns day-by-day activity of passes created, installed, and uninstalled for a template specified by id. You can also add start and end date parameters in the path, to return activity between two dates, in the format /template/id/{externalId}/activity/2018-08-10/2018-10/01.
This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.templateId path
IntegerRequiredThe
idof 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
createdAtdate.Response Body
application/json
Type: Object
details
Array<Object>OptionalEach object in this array represents pass activity for a single day.
activity
ObjectOptionalRepresents activity for a template or project.
created
IntegerOptionalThe number of passes created.
installed
IntegerOptionalThe number of passes that were installed.
uninstalled
IntegerOptionalThe number of passes that were uninstalled.
date
StringOptionalThe 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
StringOptionalThe end date for a statistics report.
Pattern:
([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).id
IntegerOptionalThe
idof the template specified in the path.startDate
StringOptionalThe start date for a statistics report.
Pattern:
([12]\d{3}/(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])).summary
ObjectOptionalRepresents activity for a template or project.
created
IntegerOptionalThe number of passes created.
installed
IntegerOptionalThe number of passes that were installed.
uninstalled
IntegerOptionalThe number of passes that were uninstalled.
vendor
StringOptionalThe 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.2Example Response
{
"id": 12345,
"vendor": "Apple",
"lastUpdated": "2015-10-01T20:15:28.000-07:00",
"total": 7,
"installed": 0,
"uninstalled": 0
}Returns Statistics for a given template by id, including the total number of passes installed and uninstalled based on the template.
This endpoint does not count repeated actions by the same user.
Security:
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.templateId path
IntegerRequiredThe
idof 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
IntegerOptionalThe template specified in the request.
installed
IntegerOptionalThe number of installed passes based on this template.
lastUpdated
StringOptionalThe date and time when the item was last updated.
Format:
date-time.total
IntegerOptionalA count of the total number of passes created from the template.
uninstalled
IntegerOptionalThe number of uninstalled passes based on this template.
vendor
StringOptionalThe 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"}
]
}
]
}Returns a list of certificates, including an array of templates that use the certificate.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.vendor query
StringOptionalThe vendor of certificate you want to return. Supports Apple only.
Possible values:
Apple.enabled query
BooleanOptionalIndicates whether or not the certificate is enabled.
order query
StringOptionalIndicates the field to order results by.
page query
IntegerOptionalIndicates the page of results to return.
pageSize query
IntegerOptionalIndicates the number of results per page.
direction query
StringOptionalIndicates the direction in which to return results.
Possible values:
ASC,DESC.
Response
200
Returns an array of certificates.
Response Body
application/json
Type: Object
count
IntegerOptionalThe number of results on the curent page.
nextPage
StringOptionalThe url for the next page of results.
Format:
url.pagination
ObjectOptionalContains information about pagination, according to your query parameters.
direction
StringOptionalThe direction of results, ascending or descending.
Possible values:
ASC,DESC.order
StringOptionalThe key in the result set that you want to order results by. Defaults to
id.page
IntegerOptionalThe page you are on. Multiply by the page size to determine the result set on the page.
pageSize
IntegerOptionalThe number of results per page.
start
IntegerOptionalThe 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",
}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
StringRequiredThe 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.
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"}
]
}Returns information about a certificate, including an array of templates that use the certificate.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.id path
StringRequiredThe id of the certificate you want to perform operations against.
Response
200
Returns information about the certificate specified in the request
Update a certificate
Updates a certificate. Note the following behaviors:
- The following fields can be updated directly:
enabled,default,commentandname. - If fields
enabledanddefaultare not specified they won't be changed. - If fields
commentandnameare not specified, we assume the value needs to be removed. If you don't want to change the value, specify 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
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.id path
StringRequiredThe 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.
Remove a certificate
Removes a certificate from the system.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.id path
StringRequiredThe id of the certificate you want to perform operations against.
Response
204
A successful request returns no content.
Apple Passes Only
Download Apple Wallet .pkpass with External ID
Example Request
GET /v1/pass/123/download HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Download the contents of an Apple Wallet .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes.
See Apple's developer documentation for information about .pkpass files and contents.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.passExternalId path
StringRequiredThe custom identifier of the pass you want to download.
Response
200
Returns the .pkpass file as a .zip extension.
View Apple Wallet JSON with External ID
Example Request
GET /v1/pass/123/viewJSONPass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Example Response
{
"passTypeIdentifier": "pass.com....",
"storeCard": {
"backFields":[
{
"key": "Program Details",
"label": "Program Details",
"value": "Some information about how the loyalty program works and its benefits.\n\nAdditional terms and support information."
},
{
"key": "Merchant Website",
"label": "Merchant Website",
"value": "http:\/\/www.test.com"
},
{
"key": "back0",
"label": "Built with Urban Airship Reach",
"value": "Find out more and create your own passes at https://wallet.urbanairship.com\n\nUrban Airship, Inc.,1417 NW Everett St., Portland, OR 97209 800.720.2098 support@urbanairship.com"
}
],
"primaryFields":[
{
"key": "Program Name",
"label": "Urban Airship",
"value": "Program Name",
"textAlignment": "PKTextAlignmentNatural"
}
],
"headerFields":[
{
"key": "Points",
"label": "Points",
"value": 1234.0,
"textAlignment": "PKTextAlignmentNatural",
"numberStyle": "PKNumberStyleDecimal"
}
],
"secondaryFields":[
{
"key": "Tier",
"label": "Tier",
"value": 2.0,
"textAlignment": "PKTextAlignmentNatural",
"numberStyle": "PKNumberStyleDecimal"
},
{
"key": "Tier Name",
"label": "Tier Name",
"value": "Silver",
"textAlignment": "PKTextAlignmentNatural"
},
{
"key": "Member Name",
"label": "Member Name",
"value": "First Last",
"textAlignment": "PKTextAlignmentNatural"
}
]
},
"organizationName": "Urban Airship",
"backgroundColor": "rgb(0,147,201)",
"labelColor": "rgb(24,86,148)",
"authenticationToken": "df897c90-5a9b-48dd-a4b4-8020486811b7",
"serialNumber": "bcc7cdae-e491-4e36-a95e-9758e31549aa",
"barcode": {
"message": "123456789",
"messageEncoding": "iso-8859-1",
"format": "PKBarcodeFormatPDF417",
"altText": "123456789"
},
"teamIdentifier": "MN52833CEX",
"formatVersion": 1,
"webServiceURL": "https:\/\/wallet-api.urbanairship.com\/apple",
"description": "Template 1",
"foregroundColor": "rgb(255,255,255)"
}View the JSON of an Apple Wallet Pass. The Urban Airship request payload is different from the JSON payload contained in an Apple Wallet pass. You can use this endpoint to view the JSON payload as passed to Apple Wallet.
See Apple's developer documentation for information about Apple Wallet payloads.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.passExternalId path
StringRequiredThe custom identifier of the pass you want to return Apple Wallet JSON for.
Response
200
Returns JSON as passed to Apple Wallet.
Response Body
application/json
Type: Object
Download Apple Wallet .pkpass
Example Request
GET /v1/pass/123/download HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Download the contents of an Apple Wallet .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes.
See Apple's developer documentation for information about .pkpass files and contents.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.pass_id path
StringRequiredThe
idof the pass you want to download
Response
200
Returns the .pkpass file as a .zip extension.
View Apple Wallet JSON
Example Request
GET /v1/123/viewJSONPass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Example Response
{
"passTypeIdentifier": "pass.com....",
"storeCard": {
"backFields":[
{
"key": "Program Details",
"label": "Program Details",
"value": "Some information about how the loyalty program works and its benefits.\n\nAdditional terms and support information."
},
{
"key": "Merchant Website",
"label": "Merchant Website",
"value": "http:\/\/www.test.com"
},
{
"key": "back0",
"label": "Built with Urban Airship Reach",
"value": "Find out more and create your own passes at https://wallet.urbanairship.com\n\nUrban Airship, Inc.,1417 NW Everett St., Portland, OR 97209 800.720.2098 support@urbanairship.com"
}
],
"primaryFields":[
{
"key": "Program Name",
"label": "Urban Airship",
"value": "Program Name",
"textAlignment": "PKTextAlignmentNatural"
}
],
"headerFields":[
{
"key": "Points",
"label": "Points",
"value": 1234.0,
"textAlignment": "PKTextAlignmentNatural",
"numberStyle": "PKNumberStyleDecimal"
}
],
"secondaryFields":[
{
"key": "Tier",
"label": "Tier",
"value": 2.0,
"textAlignment": "PKTextAlignmentNatural",
"numberStyle": "PKNumberStyleDecimal"
},
{
"key": "Tier Name",
"label": "Tier Name",
"value": "Silver",
"textAlignment": "PKTextAlignmentNatural"
},
{
"key": "Member Name",
"label": "Member Name",
"value": "First Last",
"textAlignment": "PKTextAlignmentNatural"
}
]
},
"organizationName": "Urban Airship",
"backgroundColor": "rgb(0,147,201)",
"labelColor": "rgb(24,86,148)",
"authenticationToken": "df897c90-5a9b-48dd-a4b4-8020486811b7",
"serialNumber": "bcc7cdae-e491-4e36-a95e-9758e31549aa",
"barcode": {
"message": "123456789",
"messageEncoding": "iso-8859-1",
"format": "PKBarcodeFormatPDF417",
"altText": "123456789"
},
"teamIdentifier": "MN52833CEX",
"formatVersion": 1,
"webServiceURL": "https:\/\/wallet-api.urbanairship.com\/apple",
"description": "Template 1",
"foregroundColor": "rgb(255,255,255)"
}Returns the JSON of an Apple Wallet pass. The Urban Airship request payload is translated when sent to Apple. You can use this endpoint to view the JSON payload as passed to Apple Wallet for debugging purposes.
See Apple's developer documentation for information about Apple Wallet payloads.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.pass_id path
StringRequiredThe
idof the pass you want to return Apple Wallet JSON for.
Response
200
A successful request returns Apple JSON
Response Body
application/json
Type: Object
Google Passes Only
Save to Google Pay
Example Request
POST /v1/pass/123/saveToWallet HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"fields": {
"Points": {
"value": "600"
}
},
"tag": "abc",
"externalId": "UserName",
"onSuccess": "mySuccessFunc()",
"onFail": "myFailureFunc()"
}Example Response
<script src="https://apis.google.com/js/plusone.js" type="text/javascript"></script>
<script type="text/javascript">
function urban_airship_callback(path) {
var script = document.createElement('script');
script.src = path
document.getElementsByTagName('head')[0].appendChild(script);
}
var successHandler = function (params) {
urban_airship_callback('https://wallet-api.urbanairship.com/v1/card/register/2931580989855247863.31885_34ab7304-0148-407f-9e4a-69ae30c1efd1')
}
var failureHandler = function (params) {
urban_airship_callback('https://wallet-api.urbanairship.com/v1/card/register/2931580989855247863.31885_34ab7304-0148-407f-9e4a-69ae30c1efd1')
}
</script><g:savetowallet
jwt="eyJhbGciOiJSUzI1NiJ9..."
onsuccess="mySuccessFunc()"
onfailure="myFailureFunc()" size="small" theme="gray">
</g:savetowallet>
Creates a pass from the specified template and returns code for a "Save to Google Pay" button. Clicking or tapping this button installs the pass.
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.template_id path
StringRequiredThe
idof the template you want to generate a "save to Google Pay" button for.
Request Body
The request is much like creating a pass with the addition of functions to perform upon success or failure.
application/json
Type: Object
externalId
StringOptionalAn external identifier for the pass that you might want to use to update the pass in the future.
fields
ObjectOptionalfield.label
ObjectOptionalThe
labelof a field you want to update on the resulting pass.value
StringOptionalThe value you want to provide to the field.
onFailure
StringOptionalA javascript function that you want to be called when a user
onSuccess
StringOptionalA javascript function that you want to be called when a user successfully adds the pass to Google Pay.
tag
StringOptionalA single tag you want to add to the pass.
Response
200
A response includes the javascript for a "Save to Google Pay" button.
Schedules
List schedules
Example Request
GET /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2Example 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 a list of all schedules that have not yet occured for the project
Request Parameters
Api-Revision header
StringRequiredThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2.projectId path
StringRequiredThe 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
IntegerOptionalThe number of schedules on the page.
next_page
StringOptionalThe url of the next page in the result set.
Format:
url.ok
BooleanOptionalIf true, the operation completed successfully.
schedules
Array<Object>OptionalThe list of upcoming schedules.
name
StringOptionalA name for the schedule.
schedule
ObjectOptionalschedule_time
StringOptionalThe date and time when the update will occur.
Format:
date-time.
update
Object