Wallet API
Airship’s REST API for Mobile Wallet projects. Use this API to create Apple Wallet and Google Wallet passes for your customers.
Libraries
Airship maintains open source server libraries to support your integrations with our APIs in multiple languages. Click below for library documentation.
Introduction
The Wallet API provides programmatic access to Airship Wallet service, where you can create passes for Apple Wallet and Google Wallet. Passes are:
- Created from templates within a project. The project determines the types of templates and passes you create; your templates determine the style and default data for your passes.
- Distributed as links—When creating a pass or an adaptive link, you are creating a link. Users tap this link (or scan a QR code representing the link, etc.) to install the pass on their device.
- Customizable—Add relevant data to your users when they install your pass.
- Updatable with relevant field and value changes. After users install your passes, you can update passes with relevant field and values so your users’ passes are always up to date.
For a better understanding of Airship Wallet projects and passes, see How mobile wallet works.
See the Getting Started Guide for help setting up an Airship Wallet project.
API Request Format
All API requests are HTTP requests. For all requests with a body, the body may be in JSON
format or other formats like CSV as specified for the endpoint. The proper Content-Type for
JSON is application/json and the proper content type for CSV is text/csv.
Date/Time Format
All date/time values are represented according to ISO 8601 in UTC.
A T separator is preferred but not required. It will be included in all date/time values generated by the API.
Example: 2023-01-28T15:00-05:00
Security
- Our APIs only work under 2048-bit HTTPS encrypted connections to ensure your data is private from client to server connections.
- Access is authenticated through a unique secret API key which we provide to you in your Wallet dashboard. It is your responsibility to keep this key well-guarded, as it represents your identity.
- You will use your own Apple Pass Type Certificate or Google Pay certificate to sign production passes.
Specifying a version
The current version of the Wallet API is 1.2. The versioning for the Wallet API is currently distinct from the versioning for the Airship Engage API.
Always specify the version of the API you want to use by adding an HTTP header called
Api-Revision. The value of that header should be in the format x.y where x is the API version and y the sub-revision. For instance, 1.2 is for the /v1 API, revision 2.
External IDs
Most endpoints support an externalId parameter in the path. While all assets
within this API typically have an internal id, you can use the externalId parameter to grant custom identifiers to your assets — projects, templates, passes, etc. These identifiers can make your assets more recognizable and help you integrate with an external application or system.
If you want to use external IDs, you should use them for all assets — projects, templates, passes, etc.
In general you can support external IDs by appending /id/{externalId} to an endpoint path that would either take or generate a standard id.
Base URL
Select the domain associated with your Airship project.
https://wallet-api.urbanairship.com/v1- The North American base URL for Wallet endpoints, including the API major version number. In addition to the major version, all requests must include an `Api-Revision` header, with a more specific version number, e.g., `1.2`.https://wallet-api.asnapieu.com/v1- The European base URL for Wallet endpoints, including the API major version number. In addition to the major version, all requests must include an `Api-Revision` header, with a more specific version number, e.g., `1.2`.https://reach-api.urbanairship.com/v1- The deprecated base URL for Wallet (formerly known as Reach) endpoints. Use `https://wallet-api.urbanairship.com/v1` instead.
Authentication
- Basic Auth HTTP (basic)
All 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 inprojectKey:projectSecretformat. For example,Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0.You can copy you Project Key and Secret from your Wallet project. Go to Settings, then API.
Only TLS 1.2 and TLS 1.3 are supported for Wallet API endpoint access. See also Mobile Wallet Reference: Security.
Projects
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
GET /project
Example request
GET /v1/project HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/project HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
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:
Query parameters:
- pageSize integerThe number of results per page. Defaults to 10.
- page integerThe page of the search you want to return.
- order stringDetermines the order of results. Defaults to
id.Possible values:
id,name,createdAt,updatedAt - direction stringThe direction of the result set, ascending or descending. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
An array of projects belonging to you.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json; charset=utf-8- count string
The total number of results.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- projects array
Create project
POST /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"
}
}
Response
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"
}
}
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.
See also Create project with external ID.
Security:
Request headers:
- Api-Revision 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.
Content-Type:
application/json; charset=utf-8A project request determines the type of passes you can create and the types of barcode your passes will use.
Responses
200
Create a project. Your project is based around a pass type and your certificates.
Response body:
- Content-Type:
application/json; charset=utf-8A 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
POST /project/duplicate/{projectId}
Example request
POST /v1/project/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
POST /v1/project/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"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"
}
Example request with external ID
POST /v1/project/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"createdAt":"2018-06-04T23:26:43Z",
"settings": {
"barcode_alt_text": "123json=456789",
"barcode_label": "Member ID",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_type": "pdf417"
},
"templates":[
],
"name":"Copy of LoyaltyCard",
"projectType":"loyalty",
"description":"Aztec Barcode",
"contextId":"nEkzVdIcTP2eNqP1--xQ_A",
"id":12346,
"updatedAt":"2018-06-04T23:26:43Z"
}
POST /v1/project/duplicate/id/67890 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response with external ID
POST /v1/project/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"createdAt":"2018-06-04T23:26:43Z",
"settings": {
"barcode_alt_text": "123json=456789",
"barcode_label": "Member ID",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_type": "pdf417"
},
"templates":[
],
"name":"Copy of LoyaltyCard",
"projectType":"loyalty",
"description":"Aztec Barcode",
"contextId":"nEkzVdIcTP2eNqP1--xQ_A",
"id":12346,
"updatedAt":"2018-06-04T23:26:43Z"
}
POST /v1/project/duplicate/id/67890 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"createdAt": "2024-01-25T03:23:19Z",
"settings": {},
"appleCertificateId": "f5cbc01b-3c56-460c-8dca-ba1c327691e6",
"templates": [
{
"projectType": "generic",
"description": "a new template",
"vendorId": 1,
"type": "Generic",
"createdAt": "2024-01-25T03:23:20Z",
"deleted": "False",
"vendor": "Apple",
"name": "Copy of asykes-template-1234123",
"disabled": "False",
"id": "179192",
"expiryDuration": 730,
"projectName": "Copy of my test project",
"projectId": 7425,
"updatedAt": "2024-01-25T03:23:20Z"
}
],
"name": "Copy of my test project",
"projectType": "generic",
"description": "test project",
"externalId": "Copy_of_67890",
"contextId": "4KN8Q9s-Qm68Ks9JF2A33g",
"id": 7425,
"updatedAt": "2024-01-25T03:23:19Z"
}
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project you want to duplicate. For External IDs, format the
{projectId}asid/{externalId}.
Responses
200
A project and a list of templates within the project.
Response body:
- Content-Type:
application/jsonA 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
POST /project/id/{externalId}
Example request
POST /v1/project/id/67890 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"
}
}
Response
POST /v1/project/id/67890 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"
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"updatedAt": "2013-07-01T19:57:36.190Z",
"externalId": "67890",
"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.
See also Create project.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- externalId 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.
Content-Type:
application/json; charset=utf-8A project request determines the type of passes you can create and the types of barcode your passes will use.
Responses
200
Create a project. Your project is based around a pass type and your certificates.
Response body:
- Content-Type:
application/json; charset=utf-8A 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
GET /project/{projectId}
Example request
GET /v1/project/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/project/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
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"
}
Example request with external ID
GET /v1/project/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
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 /v1/project/id/myProject HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response with external ID
GET /v1/project/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
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 /v1/project/id/myProject HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"updatedAt": "2013-06-27T20:55:06.000Z",
"externalId": "myProject",
"id": "12345",
"description": "Aztec Barcode",
"createdAt": "2013-06-27T20:51:02.000Z",
"contextId": "myvWKam4QN9Iu2K2fXK-Bd",
"templates": [
],
"settings": {
"barcode_alt_text": "123456789",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_label": "Member ID",
"barcode_type_text": "Aztec",
"barcode_type": "aztec"
},
"name": "Aztec Barcode",
"projectType": "loyalty"
}
Get 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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIRED
Responses
200
A project and a list of templates within the project.
Response body:
- Content-Type:
application/jsonA 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
PUT /project/{projectId}
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"
}
Response
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"
}
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"
}
Example request with external ID
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"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"updatedAt": "2013-07-01T19:57:36.000Z",
"id": 12345,
"templates": [
],
"description": "Significantly more detailed description",
"createdAt": "2013-07-01T19:57:36.000Z",
"settings": {
},
"name": "New And Improved Name",
"projectType": "loyalty"
}
PUT /v1/project/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"
}
Response with external ID
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"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"updatedAt": "2013-07-01T19:57:36.000Z",
"id": 12345,
"templates": [
],
"description": "Significantly more detailed description",
"createdAt": "2013-07-01T19:57:36.000Z",
"settings": {
},
"name": "New And Improved Name",
"projectType": "loyalty"
}
PUT /v1/project/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"
}
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.
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIRED
Request body:
An update request can take the same payload as a Create Project request. However, you should provide only the keys you want to update; keys you do not provide will remain unchanged.
Content-Type:
application/jsonA project request determines the type of passes you can create and the types of barcode your passes will use.
Responses
200
Returns project metadata and a list of templates for the project.
Response body:
- Content-Type:
application/jsonA project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.
List NFC merchants
GET /project/{projectId}/nfcMerchants
Example request
GET /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Example request with external ID
GET /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
GET /v1/project/id/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
GET /v1/project/id/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"merchants": [
{
"merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
"projectId": 13137,
"vendor": "APPLE",
"merchantName": "XYZ Merchant",
"merchantEmail": "xyz@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
"keyVersion": 1,
"keySource": "GENERATED",
"updatedAt": "2020-09-16T19:16:28.000Z"
},
{
"merchantId": "70407b66-ffbc-41bf-bf13-7814caf1d2bc",
"projectId": 13137,
"vendor": "GOOGLE",
"merchantName": "ABC Merchant",
"merchantEmail": "abc@example.com",
"terminalProvider": "Test Tool",
"publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEchyXj869zfmKhRi9xP7f2AK07kEo\n4lE7ZlWTN14jh4YBTny+hRGRXcUzevV9zSSPJlPHpqqu5pEwlv1xyFvE1w==\n",
"keyVersion": 1,
"keySource": "IMPORTED",
"smartTapIssuerId": "3388000000005375425",
"smartTapCollectorId": "23405818",
"updatedAt": "2020-09-09T00:19:45.000Z"
}
]
}
Return all NFC merchant information for a project.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project you want to add or lookup NFC merchant information for. For External IDs, format the
{projectId}asid/{projectExternalId}.
Responses
200
Returns all NFC merchants associated with your Airship Wallet project.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- merchants array
Add NFC merchant
POST /project/{projectId}/nfcMerchants
Example request — Apple and Google vendors
POST /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"vendor": "ANY",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
"keyVersion": 1,
"keySource": "IMPORTED"
}
Example request with external ID — Apple and Google vendors
POST /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"vendor": "ANY",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
"keyVersion": 1,
"keySource": "IMPORTED"
}
POST /v1/project/id/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"vendor": "ANY",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
"keyVersion": 1,
"keySource": "IMPORTED"
}
Response
POST /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"vendor": "ANY",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
"keyVersion": 1,
"keySource": "IMPORTED"
}
POST /v1/project/id/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"vendor": "ANY",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
"keyVersion": 1,
"keySource": "IMPORTED"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"merchantId": "a535fc29-9e90-434a-b8e9-4a5851292ccc",
"projectId": 13137,
"vendor": "APPLE",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
"keyVersion": 1,
"keySource": "IMPORTED",
"updatedAt": "2020-09-16T18:17:49.349Z"
}
Provide your merchant information and keys to support NFC interaction with passes and SmartTap for Android. When your project is NFC enabled, your audience can tap their device to a terminal to use their passes — consume point balances, use coupons, scan boarding passes, etc.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project you want to add or lookup NFC merchant information for. For External IDs, format the
{projectId}asid/{projectExternalId}.
Request body:
Content-Type:
application/jsonDescribes NFC support for your project (and related templates/passes).
OBJECT PROPERTIES- keyVersion integer
The SSH protocol version for your key. Can be set to
1. - merchantEmail string
The google merchant email address, used when configuring smartTap.
- merchantName string
The google merchant name, used when configuring smartTap.
- publicKeyPem string
The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.
- smartTapCollectorId string
Defines your Google Wallet merchant.
- terminalProvider string
The NFC terminal provider that can read NFC messages, like
Verifone. - vendor stringREQUIRED
Set the vendor you want to provide information for, where
ANYrepresents both Apple and Google vendors. If you omit this property, Airship assumesANY.Possible values:
GOOGLE,APPLE,ANY
Responses
200
A response includes your project ID and NFC merchant information. Note the
merchantId— this is how you reference your merchant information if you need to modify or delete it.Response body:
- Content-Type:
application/jsonA response contains information generated by Airship and/or gathered from Google Wallet services.
All ofDescribes NFC support for your project (and related templates/passes).
OBJECT PROPERTIES- keyVersion integer
The SSH protocol version for your key. Can be set to
1. - merchantEmail string
The google merchant email address, used when configuring smartTap.
- merchantName string
The google merchant name, used when configuring smartTap.
- publicKeyPem string
The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.
- smartTapCollectorId string
Defines your Google Wallet merchant.
- terminalProvider string
The NFC terminal provider that can read NFC messages, like
Verifone. - vendor stringREQUIRED
Set the vendor you want to provide information for, where
ANYrepresents both Apple and Google vendors. If you omit this property, Airship assumesANY.Possible values:
GOOGLE,APPLE,ANY
- OBJECT PROPERTIES
- keySource string
Set by Airship, either
GENERATEDif Airship generates your public/private keys orIMPORTEDif you provide your ownpublicKey.Possible values:
GENERATED,IMPORTED - merchantId string
The Airship-generated UUID for your NFC merchant information.
- privateKeyPem string
Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the
publicKeyPem). - projectId integer
The ID of the Wallet project.
- smartTapIssuerId stringGOOGLE ONLY
Represents your platform and may contain more than one
collectorId. - updatedAt string
The date and time when your NFC merchant information was last updated.
Get NFC merchant
GET /project/{projectId}/nfcMerchants/{merchantId}
Example request
GET /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Example request with external ID
GET /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
GET /v1/project/id/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
GET /v1/project/id/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
"projectId": 13137,
"vendor": "GOOGLE",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
"keyVersion": 1,
"keySource": "GENERATED",
"updatedAt": "2020-09-16T18:20:45.000Z"
}
Get an individual NFC merchant.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project you want to add or lookup NFC merchant information for. For External IDs, format the
{projectId}asid/{projectExternalId}. - merchantId stringREQUIREDThe merchant ID you want to modify.
Responses
200
A response includes your project ID and NFC merchant information. Note the
merchantId— this is how you reference your merchant information if you need to modify or delete it.Response body:
- Content-Type:
application/jsonA response contains information generated by Airship and/or gathered from Google Wallet services.
All ofDescribes NFC support for your project (and related templates/passes).
OBJECT PROPERTIES- keyVersion integer
The SSH protocol version for your key. Can be set to
1. - merchantEmail string
The google merchant email address, used when configuring smartTap.
- merchantName string
The google merchant name, used when configuring smartTap.
- publicKeyPem string
The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.
- smartTapCollectorId string
Defines your Google Wallet merchant.
- terminalProvider string
The NFC terminal provider that can read NFC messages, like
Verifone. - vendor stringREQUIRED
Set the vendor you want to provide information for, where
ANYrepresents both Apple and Google vendors. If you omit this property, Airship assumesANY.Possible values:
GOOGLE,APPLE,ANY
- OBJECT PROPERTIES
- keySource string
Set by Airship, either
GENERATEDif Airship generates your public/private keys orIMPORTEDif you provide your ownpublicKey.Possible values:
GENERATED,IMPORTED - merchantId string
The Airship-generated UUID for your NFC merchant information.
- privateKeyPem string
Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the
publicKeyPem). - projectId integer
The ID of the Wallet project.
- smartTapIssuerId stringGOOGLE ONLY
Represents your platform and may contain more than one
collectorId. - updatedAt string
The date and time when your NFC merchant information was last updated.
Update NFC merchant information
PUT /project/{projectId}/nfcMerchants/{merchantId}
Example request
PUT /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"merchantName": "Example Merchant",
"merchantEmail": "my_merchant@example.com"
}
Example request with external ID
PUT /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"merchantName": "Example Merchant",
"merchantEmail": "my_merchant@example.com"
}
PUT /v1/project/id/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"merchantName": "Example Merchant",
"merchantEmail": "my_merchant@example.com"
}
Response
PUT /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"merchantName": "Example Merchant",
"merchantEmail": "my_merchant@example.com"
}
PUT /v1/project/id/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"merchantName": "Example Merchant",
"merchantEmail": "my_merchant@example.com"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
"projectId": 13137,
"vendor": "GOOGLE",
"merchantName": "XYZ Merchant",
"merchantEmail": "xyz@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
"keyVersion": 1,
"keySource": "GENERATED",
"updatedAt": "2020-09-16T19:16:28.877Z"
}
Update your NFC merchant information.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project you want to add or lookup NFC merchant information for. For External IDs, format the
{projectId}asid/{projectExternalId}. - merchantId stringREQUIREDThe merchant ID you want to modify.
Request body:
You cannot update your public/private key. If you need to update keys, you should add a new NFC merchant configuration using new keys and delete the existing configuration.
Content-Type:
OBJECT PROPERTIESapplication/json- merchantEmail string
The google merchant email address, used when configuring smartTap.
- merchantName string
The google merchant name, used when configuring smartTap.
Responses
200
A response includes your project ID and NFC merchant information. Note the
merchantId— this is how you reference your merchant information if you need to modify or delete it.Response body:
- Content-Type:
application/jsonA response contains information generated by Airship and/or gathered from Google Wallet services.
All ofDescribes NFC support for your project (and related templates/passes).
OBJECT PROPERTIES- keyVersion integer
The SSH protocol version for your key. Can be set to
1. - merchantEmail string
The google merchant email address, used when configuring smartTap.
- merchantName string
The google merchant name, used when configuring smartTap.
- publicKeyPem string
The public key for NFC communications. If you do not provide a public key, Airship will generate a public/private key pair for you.
- smartTapCollectorId string
Defines your Google Wallet merchant.
- terminalProvider string
The NFC terminal provider that can read NFC messages, like
Verifone. - vendor stringREQUIRED
Set the vendor you want to provide information for, where
ANYrepresents both Apple and Google vendors. If you omit this property, Airship assumesANY.Possible values:
GOOGLE,APPLE,ANY
- OBJECT PROPERTIES
- keySource string
Set by Airship, either
GENERATEDif Airship generates your public/private keys orIMPORTEDif you provide your ownpublicKey.Possible values:
GENERATED,IMPORTED - merchantId string
The Airship-generated UUID for your NFC merchant information.
- privateKeyPem string
Returned in a POST if your public/private keys are generated by Airship. This is the key your terminal uses to decode messages from Airship (that use the
publicKeyPem). - projectId integer
The ID of the Wallet project.
- smartTapIssuerId stringGOOGLE ONLY
Represents your platform and may contain more than one
collectorId. - updatedAt string
The date and time when your NFC merchant information was last updated.
Delete NFC merchant
DELETE /project/{projectId}/nfcMerchants/{merchantId}
Example request
DELETE /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Example request with external ID
DELETE /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
DELETE /v1/project/id/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Example request
DELETE /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
DELETE /v1/project/id/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
"updatedAt": "2020-09-16T18:20:45.000Z"
}
Delete an NFC merchant. Deleting your NFC information prevents users from redeeming passes using NFC for the associated terminal, unless you have already added new/different NFC information to your project.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project you want to add or lookup NFC merchant information for. For External IDs, format the
{projectId}asid/{projectExternalId}. - merchantId stringREQUIREDThe merchant ID you want to modify.
Responses
200
The merchant information was deleted.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- merchantId string
The merchant ID that you deleted.
- updatedAt string
The date and time when the merchant information was deleted.
Templates
A template determines the format, style, field placement, and default values for passes. You must specify a template when creating passes or adaptive links.
Duplicate template
POST /template/duplicate/{templateId}
Example request
POST /v1/template/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{}
Response
POST /v1/template/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": 12346
}
Example request with external ID
POST /v1/template/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": 12346
}
POST /v1/template/duplicate/id/23456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{}
Response with external ID
POST /v1/template/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": 12346
}
POST /v1/template/duplicate/id/23456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": 23457
}
Duplicates the specified template and put it in the same project.
/v1/template/duplicate/id/(templateExternalId) duplicates the template specified by the external ID and puts the newly created template in the same project.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe templateId of the template you want to duplicate. For External IDs, format the
{id}asid/{templateExternalId}.
Responses
200
A successful request returns the ID of the newly created template.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json; charset=utf-8- templateId integer
The identifier for the template. You can recall the template by ID in other operations.
List templates
GET /template/headers
Example request
GET /v1/template/headers HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/template/headers HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"count": 2,
"templateHeaders": [
{
"vendor": "Google",
"projectType": "memberCard",
"projectId": "12345",
"type": "Loyalty1",
"vendorId": "2",
"deleted": "False",
"id": "12344",
"updatedAt": "2013-07-01T18:28:54.000Z",
"description": "description",
"createdAt": "2013-07-01T18:28:54.000Z",
"name": "New Wallet Template",
"disabled": "False",
"expiryDuration": 730
},
{
"vendor": "Apple",
"projectType": "memberCard",
"projectId": "12346",
"type": "Store Card",
"vendorId": "1",
"deleted": "False",
"id": "12345",
"updatedAt": "2013-07-01T18:28:33.000Z",
"description": "Description",
"createdAt": "2013-07-01T18:28:33.000Z",
"name": "Loyalty Card",
"disabled": "False",
"expiryDuration": 730
}
],
"pagination": {
"order": "id",
"page": 1,
"start": 0,
"direction": "DESC",
"pageSize": 10
}
}
List the headers for templates you created.
Security:
Query parameters:
- pageSize numberNumber of templates per page. Defaults to 10.
- page numberThe page you want to retrieve. Defaults to 1.
- order stringThe order you want the projects returned in. Defaults to
id.Possible values:
id,name,createdAt,updatedAt - direction stringThe values ordered ascending or descending. Defaults to
DESC.Possible values:
ASC,DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
A successful response includes an array of template headers for templates you created. Look up an individual template to see field and header information for any individual template.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json; charset=utf-8- count string
The total number of results.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- templateHeaders array
A list of template header objects.
Get template
GET /template/{id}
Example request
GET /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external ID
GET /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/template/id/myTemplate HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response — Apple template
GET /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/template/id/myTemplate HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"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.example.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
}
},
"templateHeader": {
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"id": "12345",
"updatedAt": "2013-07-01T18:28:33.000Z",
"description": "Description",
"createdAt": "2013-07-01T18:28:33.000Z",
"name": "Loyalty Card",
"disabled": "False",
"expiryDuration": 730
}
}
Get the template specified by the templateId. To get the template payload in the same format as you would use in a POST or PUT operation, use the /templates endpoint instead.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe
templateIdof the template you want to look up. For External IDs, format the{id}asid/{templateExternalId}.
Responses
200
A successful response returns returns the identifier of the template and dates when the template was created and last updated.
Response body:
- Content-Type:All of
application/json- OBJECT PROPERTIES
- createdAt string
The date and time when the item was created.
- id integer
The identifier for the template. You can recall the template by ID in other operations.
- updatedAt string
The date and time when the item was last updated.
- OBJECT PROPERTIES
Create template
POST /template/{id}
Example Apple template
POST /v1/template/1234 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.example.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"description": "Description",
"name": "Loyalty Card",
"disabled": "False",
"expiryInfo": {
"expiryDuration": 365
}
}
Example Google template
POST /v1/template/1234 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.example.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"description": "Description",
"name": "Loyalty Card",
"disabled": "False",
"expiryInfo": {
"expiryDuration": 365
}
}
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.example.com",
"order": 1,
"formatType": "URL"
}
},
"messageModule": {
},
"imageModulesData": {
},
"pointsModule": {
"Tier": {
"label": "Tier",
"value": 2,
"row": 0,
"col": 1,
"formatType": "Number",
"numberStyle": "PKNumberStyleDecimal"
},
"Points": {
"label": "Points",
"value": 1234,
"row": 0,
"col": 0,
"formatType": "Number"
}
},
"notAssigned": {
},
"titleModule": {
"image": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
"imageDescription": "Logo Image",
"Program Name": {
"label": "Program Name",
"value": "UA",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"vendor": "Google",
"projectType": "memberCard",
"type": "Loyalty1",
"vendorId": 2,
"deleted": "False",
"description": "description",
"name": "Adding Google",
"expiryDuration": 365
}
Response
POST /v1/template/1234 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.example.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"description": "Description",
"name": "Loyalty Card",
"disabled": "False",
"expiryInfo": {
"expiryDuration": 365
}
}
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.example.com",
"order": 1,
"formatType": "URL"
}
},
"messageModule": {
},
"imageModulesData": {
},
"pointsModule": {
"Tier": {
"label": "Tier",
"value": 2,
"row": 0,
"col": 1,
"formatType": "Number",
"numberStyle": "PKNumberStyleDecimal"
},
"Points": {
"label": "Points",
"value": 1234,
"row": 0,
"col": 0,
"formatType": "Number"
}
},
"notAssigned": {
},
"titleModule": {
"image": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
"imageDescription": "Logo Image",
"Program Name": {
"label": "Program Name",
"value": "UA",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"vendor": "Google",
"projectType": "memberCard",
"type": "Loyalty1",
"vendorId": 2,
"deleted": "False",
"description": "description",
"name": "Adding Google",
"expiryDuration": 365
}
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. See also Create template with external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe
projectIdof the project that will contain the new template.
Request body:
The request body is structured by the platform vendor your template and subsequent passes are intended for.
Content-Type:
One ofapplication/jsonA complete iOS template includes template meta information, headers, and fields.
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
Responses
200
A response returns the template’s unique identifier. Use this
templateIdto reference the template in subsequent operations.Response body:
- Content-Type:OBJECT PROPERTIES
application/json; charset=utf-8- templateId integer
The identifier for the template. You can recall the template by ID in other operations.
Update template
PUT /template/{id}
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.example.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 request with external ID - Google 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.example.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"
}
PUT /v1/template/id/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.example.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"
}
Response
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.example.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"
}
PUT /v1/template/id/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.example.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"
}
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.
To update the template payload in the same format as you would use in a POST or PUT operation, use the /templates endpoint instead.
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe
templateIdof the template you want to update. For External IDs, format the{id}asid/{templateExternalId}.
Request body:
The structure of your template is determined by the device/wallet vendor you create passes for.
Content-Type:
One ofapplication/jsonA complete iOS template includes template meta information, headers, and fields.
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
Responses
200
A response returns the template’s unique identifier. Use this
templateIdto reference the template in subsequent operations.Response body:
- Content-Type:OBJECT PROPERTIES
application/json; charset=utf-8- templateId integer
The identifier for the template. You can recall the template by ID in other operations.
Delete template
DELETE /template/{id}
Example request
DELETE /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external ID
DELETE /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
DELETE /v1/template/id/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
DELETE /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
DELETE /v1/template/id/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"status": "Deleted",
"TemplateID": "12345"
}
Delete the specified template.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe
templateIdof the template you want to delete. For External IDs, format the{id}asid/{externalId}.
Responses
200
Returns the status of the deleted template.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- TemplateId integer
The identifier of the deleted template.
- status string
Indicates that the request succeeded.
Possible values:
success
Create template with external ID
POST /template/{projectId}/id/{templateExternalId}
Example Apple template
POST /v1/template/1234/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.example.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"description": "Description",
"name": "Loyalty Card",
"disabled": "False",
"expiryInfo": {
"expiryDuration": 365
}
}
Example Google template
POST /v1/template/1234/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.example.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"description": "Description",
"name": "Loyalty Card",
"disabled": "False",
"expiryInfo": {
"expiryDuration": 365
}
}
POST /v1/template/project/id/someProjectExtId/id/someTemplateExtId 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.example.com",
"order": 1,
"formatType": "URL"
}
},
"messageModule": {
},
"imageModulesData": {
},
"pointsModule": {
"Tier": {
"label": "Tier",
"value": 2,
"row": 0,
"col": 1,
"formatType": "Number",
"numberStyle": "PKNumberStyleDecimal"
},
"Points": {
"label": "Points",
"value": 1234,
"row": 0,
"col": 0,
"formatType": "Number"
}
},
"notAssigned": {
},
"titleModule": {
"image": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
"imageDescription": "Logo Image",
"Program Name": {
"label": "Program Name",
"value": "UA",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"vendor": "Google",
"projectType": "memberCard",
"type": "Loyalty1",
"vendorId": 2,
"deleted": "False",
"description": "description",
"name": "Adding Google",
"expiryInfo": {
"expiryDuration": 365
}
}
Response
POST /v1/template/1234/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.example.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"description": "Description",
"name": "Loyalty Card",
"disabled": "False",
"expiryInfo": {
"expiryDuration": 365
}
}
POST /v1/template/project/id/someProjectExtId/id/someTemplateExtId 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.example.com",
"order": 1,
"formatType": "URL"
}
},
"messageModule": {
},
"imageModulesData": {
},
"pointsModule": {
"Tier": {
"label": "Tier",
"value": 2,
"row": 0,
"col": 1,
"formatType": "Number",
"numberStyle": "PKNumberStyleDecimal"
},
"Points": {
"label": "Points",
"value": 1234,
"row": 0,
"col": 0,
"formatType": "Number"
}
},
"notAssigned": {
},
"titleModule": {
"image": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
"imageDescription": "Logo Image",
"Program Name": {
"label": "Program Name",
"value": "UA",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"vendor": "Google",
"projectType": "memberCard",
"type": "Loyalty1",
"vendorId": 2,
"deleted": "False",
"description": "description",
"name": "Adding Google",
"expiryInfo": {
"expiryDuration": 365
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": 12345
}
Create a template with an external ID within the specified project. A template is specific to a vendor platform, Apple or Google. See also Create template.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project you want to associate your new template with.
- templateExternalId stringREQUIREDThe custom identifier you want to give to your new template.
Request body:
The request body is structured by the platform vendor your template and subsequent passes are intended for.
Content-Type:
One ofapplication/jsonA complete iOS template includes template meta information, headers, and fields.
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
Responses
200
A response returns the template’s unique identifier. Use this
templateIdor the external ID to reference the template in subsequent operations.Response body:
- Content-Type:OBJECT PROPERTIES
application/json; charset=utf-8- templateId integer
The identifier for the template. You can recall the template by ID in other operations.
Delete location from template
DELETE /template/{templateId}/location/{locationId}
Example request
DELETE /v1/template/12345/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external ID
DELETE /v1/template/12345/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
DELETE /v1/template/id/myTemplate/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Remove a location from template.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template you want to remove a location from. For External IDs, format the
{templateId}asid/{externalId}. - locationId stringREQUIREDThe ID of the location you want to remove.
Responses
200
The location is deleted.
Response body:
- Content-Type:
application/json; charset=utf-8Type:
object
Add locations to template
POST /template/{templateId}/locations
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 request with external ID
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"
}
]
}
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"
}
]
}
Response
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"
}
]
}
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"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"locationId": 65,
"value": {
"region": "CA",
"regionCode": "94404",
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"longitude": -122.374,
"latitude": 37.618,
"city": "San Francisco"
},
"fieldId": 1842
}
]
Add locations to the specified template.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template you want to add locations to. For External IDs, format the
{templateId}asid/{externalId}.
Request body:
A request includes an array of locations.
Content-Type:
OBJECT PROPERTIESapplication/json- Locations array
Responses
200
A successful request returns the locations on the pass.
Response body:
- Content-Type:
application/json; charset=utf-8Type:
array
Get template passes
GET /template/{templateId}/passes
Example request
GET /v1/template/12345/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/template/12345/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 3,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/3/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da051",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "uninstalled",
"uninstalledAt": "2023-05-19T06:17:02.000Z",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 1,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/1/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e253",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
Example request with external ID
GET /v1/template/12345/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 3,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/3/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da051",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "uninstalled",
"uninstalledAt": "2023-05-19T06:17:02.000Z",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 1,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/1/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e253",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
GET /v1/template/id/23456/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response with external ID
GET /v1/template/12345/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 3,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/3/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da051",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "uninstalled",
"uninstalledAt": "2023-05-19T06:17:02.000Z",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 1,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/1/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e253",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
GET /v1/template/id/23456/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 3,
"templateId": 23456,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/3/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da051",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "uninstalled",
"uninstalledAt": "2023-05-19T06:17:02.000Z",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 1,
"templateId": 23456,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/1/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e253",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
Get passes for a template.
/v1/template/id/{templateExternalId}/passes get passes associated with a template identified by external ID.
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.
Possible values:
installed,uninstalled,been_installed,not_been_installed - pageSize integerThe number of passes per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId integerREQUIREDThe
templateIdof the template you want to get passes for. For External IDs, format the{id}asid/{templateExternalId}.
Responses
200
A successful request returns a paged list of passes for a particular template.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes array[object]
The metadata for passes associated with the template. Each object in the array represents a pass.
404
Template not found.
Publish a bulk update to passes
PUT /template/{templateId}/passes
Example request
PUT /v1/template/12345/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
}
}
}
Response
PUT /v1/template/12345/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
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ticketId": 56789
}
Updates all passes based on a particular template. The only information you can modify on passes for the specified template ID are images, barcode data, and the following fields:
- Membership ID fields
- Coupon codes
- Barcode values or alternative text
- Any other field or image on the pass
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.
Possible values:
installed,uninstalled,been_installed,not_been_installed - pageSize integerThe number of passes per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId integerREQUIREDThe
templateIdof the template you want to get passes for. For External IDs, format the{id}asid/{templateExternalId}.
Request body:
Specify the fields you want to update. Any field you do not specify in this payload remains unchanged.
Content-Type:
OBJECT PROPERTIESapplication/json- fields object
Responses
200
Returns a ticket ID as a reference for the update operation.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.
404
Template with ID
templateIdwas not found.
Get template v2
GET /templates/{id}
Example request
GET /templates/179229 HTTP/1.1
Authorization: Basic <Base64 key>
Example request with external ID
GET /templates/179229 HTTP/1.1
Authorization: Basic <Base64 key>
GET /templates/id/myTemplate HTTP/1.1
Authorization: Basic <Base64 key>
Response
GET /templates/179229 HTTP/1.1
Authorization: Basic <Base64 key>
GET /templates/id/myTemplate HTTP/1.1
Authorization: Basic <Base64 key>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"type": "loyalty",
"name": "Member Card Android",
"vendorId": 2,
"vendor": "Google",
"projectId": 7311,
"description": "Member Card Android",
"projectType": "loyalty",
"createdAt": "2025-09-26T20:44:15.000Z",
"updatedAt": "2025-09-26T20:44:16.000Z",
"id": 179229,
"deleted": false,
"disabled": false,
"expiryInfo": {
"expiryDuration": 730,
"expiryNever": null
},
"headers": {
"barcode_value": {
"fieldType": "barcode",
"value": "123456789",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcode_encoding": {
"fieldType": "barcode",
"value": "iso-8859-1",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcodeAltText": {
"fieldType": "barcode",
"value": "",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcode_type": {
"fieldType": "barcode",
"value": "PDF_417",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
}
},
"fields": {
"image": {
"fieldType": "titleModule",
"value": "",
"formatType": "String",
"label": "http://storage.googleapis.com/wallet-stag-storage-bucket/1000002/images/ff9367b7cff7cad7fa67ae2c871485e3befae602_6fc517eff2d76511c062913946b9149876a17623_Metro-Logo-1200x1200.png",
"hideEmpty": false,
"required": false
},
"Program Points": {
"fieldType": "loyaltyPoints",
"value": "3600",
"formatType": "Number",
"label": "Member Points",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Program Details": {
"fieldType": "textModulesData",
"value": "Pre-Membership for Metro Members",
"formatType": "String",
"label": "Pre-Member Program",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Tier": {
"fieldType": "acctModule",
"value": "Pre-Member",
"formatType": "String",
"label": "Member Level",
"hideEmpty": false,
"required": false,
"order": 2,
"row": 0,
"col": 1
},
"Merchant Website": {
"fieldType": "linksModuleData",
"value": "Merchant Website",
"formatType": "URL",
"label": "www.metro.com.sg",
"hideEmpty": false,
"required": false,
"order": 0
},
"Member Name": {
"fieldType": "acctModule",
"value": "Henry Christian",
"formatType": "String",
"label": "Member Name",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Loyalty Program Name": {
"fieldType": "titleModule",
"value": "Metro",
"formatType": "String",
"label": "Pre-Member",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
}
},
"locations": [
]
}
Get the template specified by the templateId. The template payload returned will be in the same format you would use in a POST or PUT operation unlike the /template endpoint.
Security:
Path parameters:
- id stringREQUIREDThe
templateIdof the template you want to look up. For External IDs, format the{id}asid/{templateExternalId}.
Responses
200
A successful response returns returns the identifier of the template and dates when the template was created and last updated.
Response body:
- Content-Type:All of
application/json- OBJECT PROPERTIES
- createdAt string
The date and time when the item was created.
- id integer
The identifier for the template. You can recall the template by ID in other operations.
- updatedAt string
The date and time when the item was last updated.
- OBJECT PROPERTIES
Update template v2
PUT /templates/{id}
Example request
PUT /templates/12345 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"type": "loyalty",
"name": "Member Card Android",
"vendorId": 2,
"vendor": "Google",
"projectId": 7311,
"description": "Member Card Android",
"projectType": "loyalty",
"deleted": false,
"disabled": false,
"headers": {
"barcode_value": {
"fieldType": "barcode",
"value": "123456789",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcode_encoding": {
"fieldType": "barcode",
"value": "iso-8859-1",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcodeAltText": {
"fieldType": "barcode",
"value": "",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcode_type": {
"fieldType": "barcode",
"value": "PDF_417",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
}
},
"fields": {
"image": {
"fieldType": "titleModule",
"value": "Image description for title image"
"formatType": "String",
"label": "http://storage.googleapis.com/wallet-stag-storage-bucket/1000002/images/ff9367b7cff7cad7fa67ae2c871485e3befae602_6fc517eff2d76511c062913946b9149876a17623_Metro-Logo-1200x1200.png",
"hideEmpty": false,
"required": false
},
"Program Points": {
"fieldType": "loyaltyPoints",
"value": "3600",
"formatType": "Number",
"label": "Member Points",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Program Details": {
"fieldType": "textModulesData",
"value": "Pre-Membership for Metro Members",
"formatType": "String",
"label": "Pre-Member Program",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Tier": {
"fieldType": "acctModule",
"value": "Pre-Member",
"formatType": "String",
"label": "Member Level",
"hideEmpty": false,
"required": false,
"order": 2,
"row": 0,
"col": 1
},
"Merchant Website": {
"fieldType": "linksModuleData",
"value": "Merchant Website",
"formatType": "URL",
"label": "www.metro.com.sg",
"hideEmpty": false,
"required": false,
"order": 0
},
"Member Name": {
"fieldType": "acctModule",
"value": "Henry Christian",
"formatType": "String",
"label": "Member Name",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Loyalty Program Name": {
"fieldType": "titleModule",
"value": "Metro",
"formatType": "String",
"label": "Pre-Member",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
}
}
}
Response
PUT /templates/12345 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"type": "loyalty",
"name": "Member Card Android",
"vendorId": 2,
"vendor": "Google",
"projectId": 7311,
"description": "Member Card Android",
"projectType": "loyalty",
"deleted": false,
"disabled": false,
"headers": {
"barcode_value": {
"fieldType": "barcode",
"value": "123456789",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcode_encoding": {
"fieldType": "barcode",
"value": "iso-8859-1",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcodeAltText": {
"fieldType": "barcode",
"value": "",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcode_type": {
"fieldType": "barcode",
"value": "PDF_417",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
}
},
"fields": {
"image": {
"fieldType": "titleModule",
"value": "Image description for title image"
"formatType": "String",
"label": "http://storage.googleapis.com/wallet-stag-storage-bucket/1000002/images/ff9367b7cff7cad7fa67ae2c871485e3befae602_6fc517eff2d76511c062913946b9149876a17623_Metro-Logo-1200x1200.png",
"hideEmpty": false,
"required": false
},
"Program Points": {
"fieldType": "loyaltyPoints",
"value": "3600",
"formatType": "Number",
"label": "Member Points",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Program Details": {
"fieldType": "textModulesData",
"value": "Pre-Membership for Metro Members",
"formatType": "String",
"label": "Pre-Member Program",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Tier": {
"fieldType": "acctModule",
"value": "Pre-Member",
"formatType": "String",
"label": "Member Level",
"hideEmpty": false,
"required": false,
"order": 2,
"row": 0,
"col": 1
},
"Merchant Website": {
"fieldType": "linksModuleData",
"value": "Merchant Website",
"formatType": "URL",
"label": "www.metro.com.sg",
"hideEmpty": false,
"required": false,
"order": 0
},
"Member Name": {
"fieldType": "acctModule",
"value": "Henry Christian",
"formatType": "String",
"label": "Member Name",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Loyalty Program Name": {
"fieldType": "titleModule",
"value": "Metro",
"formatType": "String",
"label": "Pre-Member",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": 179229
}
Update the template with the whole resource specified in the request, performing a complete replacement. You can also add or remove fields from the template with this call by adding or omitting those fields from the request. The template payload will be in the same format as in a POST or PUT operation, unlike the /template endpoint.
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 will be removed.
Security:
Path parameters:
- id stringREQUIREDThe
templateIdof the template you want to update. For External IDs, format the{id}asid/{templateExternalId}.
Request body:
The structure of your template is determined by the device/wallet vendor you create passes for.
Content-Type:
One ofapplication/jsonA complete iOS template includes template meta information, headers, and fields.
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
Responses
200
A response returns the template’s unique identifier. Use this
templateIdto reference the template in subsequent operations.Response body:
- Content-Type:OBJECT PROPERTIES
application/json; charset=utf-8- templateId integer
The identifier for the template. You can recall the template by ID in other operations.
Patch template
PATCH /templates/{id}
Example patch template
PATCH /templates/179229 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields" : {
"Loyalty Program Name": {
"fieldType": "titleModule",
"value": "MVP",
"formatType": "String",
"label": "program",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
}
}
}
Response
PATCH /templates/179229 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields" : {
"Loyalty Program Name": {
"fieldType": "titleModule",
"value": "MVP",
"formatType": "String",
"label": "program",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"type": "loyalty",
"name": "Member Card Android",
"vendorId": 2,
"vendor": "Google",
"projectId": 7311,
"description": "Member Card Android",
"projectType": "loyalty",
"createdAt": "2025-09-26T20:44:15.000Z",
"updatedAt": "2025-09-26T20:44:16.000Z",
"id": 179229,
"deleted": false,
"disabled": false,
"expiryInfo": {
"expiryDuration": 730,
"expiryNever": null
},
"headers": {
"barcodeAltText": {
"fieldType": "barcode",
"value": "",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcode_type": {
"fieldType": "barcode",
"value": "PDF_417",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcode_value": {
"fieldType": "barcode",
"value": "123456789",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
},
"barcode_encoding": {
"fieldType": "barcode",
"value": "iso-8859-1",
"formatType": "String",
"label": "",
"hideEmpty": false,
"required": false
}
},
"fields": {
"image": {
"fieldType": "titleModule",
"value": "",
"formatType": "String",
"label": "http://storage.googleapis.com/wallet-stag-storage-bucket/1000002/images/ff9367b7cff7cad7fa67ae2c871485e3befae602_6fc517eff2d76511c062913946b9149876a17623_Metro-Logo-1200x1200.png",
"hideEmpty": false,
"required": false
},
"Program Points": {
"fieldType": "loyaltyPoints",
"value": "3600",
"formatType": "Number",
"label": "Member Points",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Program Details": {
"fieldType": "textModulesData",
"value": "Pre-Membership for Metro Members",
"formatType": "String",
"label": "Pre-Member Program",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Tier": {
"fieldType": "acctModule",
"value": "Pre-Member",
"formatType": "String",
"label": "Member Level",
"hideEmpty": false,
"required": false,
"order": 2,
"row": 0,
"col": 1
},
"Merchant Website": {
"fieldType": "linksModuleData",
"value": "Merchant Website",
"formatType": "URL",
"label": "www.metro.com.sg",
"hideEmpty": false,
"required": false,
"order": 0
},
"Member Name": {
"fieldType": "acctModule",
"value": "Henry Christian",
"formatType": "String",
"label": "Member Name",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
},
"Loyalty Program Name": {
"fieldType": "titleModule",
"value": "MVP",
"formatType": "String",
"label": "program",
"hideEmpty": false,
"required": false,
"order": 1,
"row": 0,
"col": 0
}
}
}
Update the template with the overrides object, performing a partial update. In the payload, you only need to provide the fields in your template that you want to override.
Security:
Path parameters:
- id stringREQUIREDThe
templateIdof the template you want to update. For External IDs, format the{id}asid/{templateExternalId}.
Request body:
The structure of your template is determined by the device/wallet vendor you create passes for.
Content-Type:
One ofapplication/jsonA complete iOS template includes template meta information, headers, and fields.
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
Responses
200
A response returns the template’s unique identifier. Use this
templateIdto reference the template in subsequent operations.Response body:
- Content-Type:OBJECT PROPERTIES
application/json; charset=utf-8- templateId integer
The identifier for the template. You can recall the template by ID in other operations.
Apple Wallet Pass Personalization
Adding personalization to an Apple Wallet loyalty template creates a pass that prompts the user for relevant personal information when signing up for a rewards program. These endpoints help you manage the personalizable information that you require users to provide when signing up for your loyalty/rewards program.
Get personalization requirements
GET /template/{templateId}/personalization
Example request
GET /v1/template/12345/personalization HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/template/12345/personalization HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe loyalty card template you want to add, modify, or retrieve personalization information for.
Responses
200
Your template has the following personalization requirements.
Response body:
- Content-Type:
application/json
Add personalization requirements
POST /template/{templateId}/personalization
Example request
POST /v1/template/12345/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"
}
Response
POST /v1/template/12345/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"
}
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe loyalty card template you want to add, modify, or retrieve personalization information for.
Request body:
Content-Type:
application/json
Responses
200
Your personalization requirements have been added to the template.
Response body:
- Content-Type:
application/json
Update personalization requirements
PUT /template/{templateId}/personalization
Example request
PUT /v1/template/12345/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"
}
Response
PUT /v1/template/12345/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"
}
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe loyalty card template you want to add, modify, or retrieve personalization information for.
Request body:
Content-Type:
application/json
Responses
200
Your personalization requirements have been updated for the template.
Response body:
- Content-Type:
application/json
Delete personalization requirements
DELETE /template/{templateId}/personalization
Example request
DELETE /v1/template/12345/personalization HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
DELETE /v1/template/12345/personalization HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe loyalty card template you want to add, modify, or retrieve personalization information for.
Responses
200
Your personalization requirements removed from the template.
Response body:
- Content-Type:
application/json
Adaptive Links
A link that detects the platform of a recipient and installs the correct pass. You can send adaptive links to both Apple and Google platform users; When a user on either platform taps the link, Airship detects the user’s device platform and returns the correct pass.
To send an adaptive link to both Google and Apple platforms, you must have configured templates for both platforms. You can send an adaptive link to an individual platform, and define the behavior for the unsupported platform.
List Adaptive Links
GET /links/adaptive
Example request
GET /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"adaptiveLinkId": "0bDEgyJEko",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/0bDEgyJEko",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/0bDEgyJEko/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/0bDEgyJEko/android",
"isPersonalized": true,
"isExpired": false,
"availablePasses": 999999,
"ttlInDays": 30,
"iosTemplateId": 4834,
"androidTemplateId": 4840
},
{
"adaptiveLinkId": "58HTBeYkqg",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/58HTBeYkqg",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/58HTBeYkqg/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/58HTBeYkqg/android",
"landingPageUrl": "https://www.urbanairship.com/",
"isPersonalized": false,
"isExpired": true,
"expirationDate": "2020-10-01",
"availablePasses": 1000000,
"ttlInDays": 30,
"iosTemplateId": 4393,
"androidTemplateId": 4387
},
{
"adaptiveLinkId": "7Qxf5ar9P6",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/7Qxf5ar9P6",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/7Qxf5ar9P6/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/7Qxf5ar9P6/android",
"isPersonalized": false,
"isExpired": false,
"availablePasses": 1000000,
"ttlInDays": 30,
"iosTemplateId": 4682,
"androidTemplateId": 4680
}
]
}
Returns a list of adaptive links.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
Returns a list of all adaptive links for the account.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- links array
Create Adaptive Link
POST /links/adaptive
Example request
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"payload": {}
}
Example request with expiration date
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"payload": {}
}
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"expirationDate": "2022-10-01",
"availablePasses": 100000,
"ttlInDays": 730,
"payload": {}
}
Example request with payload
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"payload": {}
}
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"expirationDate": "2022-10-01",
"availablePasses": 100000,
"ttlInDays": 730,
"payload": {}
}
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"payload": {"fields": {"tier": {"value": "gold"}}}
}
Example request with locations
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"payload": {}
}
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"expirationDate": "2022-10-01",
"availablePasses": 100000,
"ttlInDays": 730,
"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"}}}
}
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"ttlInDays": 30,
"parameterEncoding": "base64",
"locationRadius": 10,
"maxResultLocations": 5,
"payload": {},
"locations": [
{
"latitude": 45.5898,
"longitude": -122.5951,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97218",
"relevantText": "Welcome to Portland... Voodoo Donuts is only 11 miles away",
"streetAddress1": "7000 NE Airport Way"
},
{
"latitude": 45.525492,
"longitude": -122.686092,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97209",
"relevantText": "Welcome to the Ship!",
"streetAddress1": "1417 NW Everett St #300",
"streetAddress2": ""
},
{
"latitude": 45.5205,
"longitude": -122.6788,
"relevantText": "See you at dinner tonight… or did you already hit voodoo donuts?"
}
]
}
Response
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"payload": {}
}
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"expirationDate": "2022-10-01",
"availablePasses": 100000,
"ttlInDays": 730,
"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"}}}
}
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"ttlInDays": 30,
"parameterEncoding": "base64",
"locationRadius": 10,
"maxResultLocations": 5,
"payload": {},
"locations": [
{
"latitude": 45.5898,
"longitude": -122.5951,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97218",
"relevantText": "Welcome to Portland... Voodoo Donuts is only 11 miles away",
"streetAddress1": "7000 NE Airport Way"
},
{
"latitude": 45.525492,
"longitude": -122.686092,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97209",
"relevantText": "Welcome to the Ship!",
"streetAddress1": "1417 NW Everett St #300",
"streetAddress2": ""
},
{
"latitude": 45.5205,
"longitude": -122.6788,
"relevantText": "See you at dinner tonight… or did you already hit voodoo donuts?"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "abchd345678",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/android",
"landingPageUrl": "https://example.com/landing.html",
"isPersonalized": "true",
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 30
}
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Request body:
Content-Type:
application/jsonAn adaptive link request contains identifiers for the templates you used to generate passes from the link and any fields you want to set when users create passes from the link. If you need to create a boarding pass adaptive link, go to the boarding pass object.
Responses
200
A successful request results in an adaptive link.
Response body:
- Content-Type:
application/jsonAn adaptive link response includes URLs that users can access to detect and install a pass.
404
Could not find template(s), or could not find or create Dynamic Link object(s).
Create boarding pass or event ticket Adaptive Links
POST /links/adaptive/multiple/project/{projectId}
Example boarding pass request
POST /v1/links/adaptive/multiple/project/12345 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateExternalId": "android123ExtId",
"payload": {
"flights": [
{
"flightExternalId": "flight123ExtId",
"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": "abch3ExtId1",
"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": "abch3ExtId2",
"fields": {
"seatNumber": { "value": "13B" },
"confirmationCode": { "value": "E4583B" },
"passengerName": { "value": "SMITH/SALLY" },
"barcode_value": { "value": "12346" },
"barcodeAltText": { "value": "12346" }
}
},
{
"adaptiveLinkExternalId": "abch3ExtId2",
"fields": {
"seatNumber": { "value": "13C" },
"confirmationCode": { "value": "E4583B" },
"passengerName": { "value": "SMITH/SAM" },
"barcode_value": { "value": "12347" },
"barcodeAltText": { "value": "12347" }
}
}
],
"passGroups": ["sfo-pdx-20180730"]
}
]
}
}
Response
POST /v1/links/adaptive/multiple/project/12345 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateExternalId": "android123ExtId",
"payload": {
"flights": [
{
"flightExternalId": "flight123ExtId",
"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": "abch3ExtId1",
"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": "abch3ExtId2",
"fields": {
"seatNumber": { "value": "13B" },
"confirmationCode": { "value": "E4583B" },
"passengerName": { "value": "SMITH/SALLY" },
"barcode_value": { "value": "12346" },
"barcodeAltText": { "value": "12346" }
}
},
{
"adaptiveLinkExternalId": "abch3ExtId2",
"fields": {
"seatNumber": { "value": "13C" },
"confirmationCode": { "value": "E4583B" },
"passengerName": { "value": "SMITH/SAM" },
"barcode_value": { "value": "12347" },
"barcodeAltText": { "value": "12347" }
}
}
],
"passGroups": ["sfo-pdx-20180730"]
}
]
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"links": [
{
"status": 200,
"adaptiveLinkId": "abchd345678",
"adaptiveLinkExternalId": "abch3ExtId1",
"iosTemplateId": 12345,
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateId": 154321,
"androidTemplateExternalId": "android123ExtId",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/android",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"isPersonalized": "false",
"isExpired": false,
"availablePasses": 1000000,
"ttlInDays": 30,
"flightId": 465,
"flightExternalId": "flight123ExtId",
"iosPassLinkId": "eb94e8e0-4353-4e0b-bfe9-cfd21c52a540",
"androidPassLinkId": "41c1ea48-f469-4968-b610-a98629ea19bc"
},
{
"status": 200,
"adaptiveLinkId": "abchd345Id2",
"adaptiveLinkExternalId": "abch3ExtId2",
"iosTemplateId": 12345,
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateId": 154321,
"androidTemplateExternalId": "android123ExtId",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2/android",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"isPersonalized": "false",
"isExpired": false,
"availablePasses": 1000000,
"ttlInDays": 30,
"flightId": 465,
"flightExternalId": "flight123ExtId",
"iosPassLinkId": "5d370e0d-0aa9-45c3-b7ab-eff0a3d4995b",
"androidPassLinkId": "c60bd6c0-8f1e-4419-abb0-9f6fcb8a6fab"
},
{
"status": 200,
"adaptiveLinkId": "abchd345Id2",
"adaptiveLinkExternalId": "abch3ExtId2",
"iosTemplateId": 12345,
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateId": 154321,
"androidTemplateExternalId": "android123ExtId",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2/android",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"isPersonalized": "false",
"isExpired": false,
"availablePasses": 1000000,
"ttlInDays": 30,
"flightId": 465,
"flightExternalId": "flight123ExtId",
"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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project you want to create the boarding pass in.
Request body:
An adaptive link request where the fields object can
include an array of flights or events, each with an array of passengers
or attendees, respectively.
Content-Type:
One ofapplication/jsonAn 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.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.
Responses
200
A successful request returns an array of adaptive links. Each object in the array represents an individual passenger or attendee in the request payload. Passes in the response appear in same order as objects in in the
flightsoreventsarray.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- links array
An array of adaptive links.
List passes for an Adaptive Link for an external project
GET /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes
Example request
GET /v1/links/adaptive/project/id/exid_7294/id/my_ext_flight_111924_2/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/links/adaptive/project/id/exid_7294/id/my_ext_flight_111924_2/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [
{
"id": 1474695,
"templateId": 5383,
"url": "https://wallet-staging-gcp.urbanairship.com/v1/pass/1474695/download",
"serialNumber": "a1c69eaf-754c-4eed-8124-6c0090c66b31",
"createdAt": "2024-11-19T17:42:52.000Z",
"updatedAt": "2024-11-19T17:46:24.000Z",
"status": "installed",
"headers": {
},
"fields": {
},
"installedAt": "2024-11-19T17:43:10.000Z",
"platform": "ios"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 10
}
}
List passes for an adaptive link for an external project.
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.unknown— passes that have an unknown status.
Possible values:
installed,uninstalled,been_installed,not_been_installed,unknown
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectExternalId stringREQUIREDThe external ID of the project containing an adaptive link.
- adaptiveLinkExternalId stringREQUIREDThe adaptive link external ID used for pass creation.
Responses
200
A successful request returns a paged list of passes for a particular adaptive link.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The total number of passes associated with an adaptive link.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes array[object]
The metadata for passes associated with the adaptive link. Each object in the array represents a pass.
404
The project ID or adaptive link external ID does not exist.
List passes for an Adaptive Link for a project
GET /links/adaptive/project/{projectId}/id/{adaptiveLinkExternalId}/passes
Example request
GET /v1/links/adaptive/project/6884/id/my_ext_121924_2/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/links/adaptive/project/6884/id/my_ext_121924_2/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [
{
"id": 1574695,
"templateId": 5483,
"url": "https://wallet-staging-gcp.urbanairship.com/v1/pass/1474695/download",
"serialNumber": "a1c69eaf-754c-4eed-8124-6c0090c66b31",
"createdAt": "2024-11-19T17:42:52.000Z",
"updatedAt": "2024-11-19T17:46:24.000Z",
"status": "installed",
"headers": {
},
"fields": {
},
"installedAt": "2024-11-19T17:43:10.000Z",
"platform": "ios"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 10
}
}
List passes for an adaptive link for a project.
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.unknown— passes that have an unknown status.
Possible values:
installed,uninstalled,been_installed,not_been_installed,unknown
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project, generated by Airship, containing the adaptive link.
- adaptiveLinkExternalId stringREQUIREDThe adaptive link external ID used for pass creation.
Responses
200
A successful request returns a paged list of passes for a particular adaptive link.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The total number of passes associated with an adaptive link.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes array[object]
The metadata for passes associated with the adaptive link. Each object in the array represents a pass.
404
The project ID or adaptive link external ID does not exist.
List Adaptive Links for a project
GET /links/adaptive/projects/{projectId}
Example request
GET /v1/links/adaptive/projects/7331?pageSize=2 HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/links/adaptive/projects/7331?pageSize=2 HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"adaptiveLinkId": "7XRMaSpcEQk",
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/adaptive/7XRMaSpcEQk",
"isPersonalized": false,
"availablePasses": 998,
"iosTemplateId": 106178,
"projectId": 7331,
"createdAt": "2023-05-23T20:21:10.446Z",
"updatedAt": "2023-05-23T20:21:10.446Z",
"status": 200,
"isExpired": false,
"doesAllowUrlParameters": true,
"expiry": "2023-11-19",
"isAvailablePassesUnlimited": false
},
{
"adaptiveLinkId": "Y0E6EXuTx5i",
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/adaptive/Y0E6EXuTx5i",
"isPersonalized": false,
"availablePasses": 998,
"iosTemplateId": 106178,
"projectId": 7331,
"createdAt": "2023-05-23T20:20:39.808Z",
"updatedAt": "2023-05-23T20:20:39.808Z",
"status": 200,
"isExpired": false,
"doesAllowUrlParameters": true,
"expiry": "2023-11-19",
"isAvailablePassesUnlimited": false
}
],
"nextPageToken": "XGMuDpx2RDs.1684443368127"
}
Returns a list of adaptive links for a project.
Security:
Query parameters:
- pageSize integerThe maximum items to return per page. Defaults to 10.
Default:
10 - nextPageToken stringThe token for the next page of results.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
Responses
200
Returns a list of all adaptive links for a project.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- links array
List Adaptive Links for a template
GET /links/adaptive/projects/{projectId}/templates/{templateId}
Example request
GET /v1/links/adaptive/projects/7331/templates/106178 HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/links/adaptive/projects/7331/templates/106178 HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"adaptiveLinkId": "7XRMaSpcEQk",
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/adaptive/7XRMaSpcEQk",
"isPersonalized": false,
"availablePasses": 998,
"iosTemplateId": 106178,
"projectId": 7331,
"createdAt": "2023-05-23T20:21:10.446Z",
"updatedAt": "2023-05-23T20:21:10.446Z",
"status": 200,
"isExpired": false,
"doesAllowUrlParameters": true,
"expiry": "2023-11-19",
"isAvailablePassesUnlimited": false
}
],
"nextPageToken": "Y0E6EXuTx5i.1684873239808"
}
Returns a list of adaptive links for a template.
Security:
Query parameters:
- pageSize integerThe maximum items to return per page. Defaults to 10.
Default:
10 - nextPageToken stringThe token for the next page of results.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
- templateId stringREQUIREDThe ID of the template.
Responses
200
Returns a list of all adaptive links for a template.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- links array
Get Adaptive Link
GET /links/adaptive/{adaptiveLinkId}
Example request
GET /v1/links/adaptive/abchd345678 HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/links/adaptive/abchd345678 HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "abchd345678",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/android",
"landingPageUrl": "https://example.com/landing.html",
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 30
}
Returns information about a single adaptive link.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- adaptiveLinkId stringREQUIREDThe ID of the adaptive link.
Responses
200
Lists urls and available passes for an individual link.
Response body:
- Content-Type:
application/jsonAn adaptive link response includes URLs that users can access to detect and install a pass.
404
Could not find an entry with specified
adaptiveLinkId.
Update Adaptive Link
PUT /links/adaptive/{adaptiveLinkId}
Example request
PUT /v1/links/adaptive/as3shd345 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"landingPageUrl": "https://example.com/landing.html",
"payload": {"fields": {"tier": {"value": "gold"}}}
}
Response
PUT /v1/links/adaptive/as3shd345 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"landingPageUrl": "https://example.com/landing.html",
"payload": {"fields": {"tier": {"value": "gold"}}}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "as3shd345",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/as3shd345",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/as3shd345/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/as3shd345/android",
"landingPageUrl": "https://example.com/landing.html",
"isPersonalized": "true",
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 30
}
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- adaptiveLinkId stringREQUIREDThe ID of the adaptive link.
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 landing page.
Content-Type:
application/jsonAn adaptive link request contains identifiers for the templates you used to generate passes from the link and any fields you want to set when users create passes from the link. If you need to create a boarding pass adaptive link, go to the boarding pass object.
Responses
200
A successful request results in an adaptive link.
Response body:
- Content-Type:
application/jsonAn adaptive link response includes URLs that users can access to detect and install a pass.
404
Could not find templates or Dynamic Link object(s).
Delete Adaptive Link
DELETE /links/adaptive/{adaptiveLinkId}
Example request
DELETE /v1/links/adaptive/rthBWAWDaAA HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
DELETE /v1/links/adaptive/rthBWAWDaAA HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{}
Deletes an adaptive link.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- adaptiveLinkId stringREQUIREDThe ID of the adaptive link.
Responses
200
The adaptive link was successfully deleted. A successful operation returns no content.
404
Could not find an entry with specified
adaptiveLinkId.
List passes for an Adaptive Link
GET /links/adaptive/{adaptiveLinkId}/passes
Example request
GET /v1/links/adaptive/rthBWAWDaAA/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/links/adaptive/rthBWAWDaAA/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 616,
"templateId": 1000057,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/616/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da0b8",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "installed",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 610,
"templateId": 1000083,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/610/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e216",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
List passes for an adaptive link.
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.
Possible values:
installed,uninstalled,been_installed,not_been_installed - pageSize integerThe number of passes per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- adaptiveLinkId stringREQUIREDThe adaptive link ID used for pass creation.
Responses
200
A successful request returns a paged list of passes for a particular adaptive link.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The total number of passes associated with an adaptive link.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes array[object]
The metadata for passes associated with the adaptive link. Each object in the array represents a pass.
404
The adaptive link ID does not exist.
Generate multiple passes from a single Adaptive Link
GET /pass/adaptive
Example iOS request
GET /v1/pass/adaptive?ids=rthBWAWDaAA,Y0E6EXuTx5i&deviceType=ios HTTP/1.1
iOS response
GET /v1/pass/adaptive?ids=rthBWAWDaAA,Y0E6EXuTx5i&deviceType=ios HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/vnd.apple.pkpass
[.pkpass]
Example Android request
GET /v1/pass/adaptive?ids=rthBWAWDaAA,Y0E6EXuTx5i&deviceType=ios HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/vnd.apple.pkpass
[.pkpass]
GET /v1/pass/adaptive?ids=rthBWAWDaAA,Y0E6EXuTx5i&deviceType=android HTTP/1.1
Android response
GET /v1/pass/adaptive?ids=rthBWAWDaAA,Y0E6EXuTx5i&deviceType=ios HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/vnd.apple.pkpass
[.pkpass]
GET /v1/pass/adaptive?ids=rthBWAWDaAA,Y0E6EXuTx5i&deviceType=android HTTP/1.1
HTTP/1.1 301 Redirect
Generates a multi-pass bundle from an Adaptive Link.
Query parameters:
- ids stringREQUIREDComma-separated Adaptive Link IDs to bundle.
- deviceType stringREQUIREDThe device type the user needs to install. Only required when targeting a specific platform, otherwise, if a device type is not specified in the query, Airship detects the device type from the request headers. If the device type cannot be detected, Airship redirects the request to a landing page URL provided by the client as part of the Adaptive Link metadata. In your landing page, provide buttons that link to the explicit device-specific URLs for iOS and Android pass generation. For example,
/pass/adaptive?ids={comma_separated_adaptive_link_ids}&deviceType=ios.Possible values:
ios,android,web
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
Requests for iOS passes return a .pkpass file. Requests for Android passes redirect to a Google Pay URL containing the Google pass JSON Web Token (JWT). Requests for
webdevices or without a device type specified return the landing page URL that a user can access to manually select a device type and install the pass.Response body:
- Content-Type:
application/jsonType:
objectA publicUrl for Android users or the landing page URL if the device type was set to
webor was not specified. - Content-Type:
application/vnd.apple.pkpassType:
objectA .pkpass file for iOS users.
404
Could not find an entry with specified
adaptiveLinkId.
Generate pass from Adaptive Link
GET /pass/adaptive/{adaptiveLinkId}/{deviceType}
Example iOS request
GET /v1/pass/adaptive/rthBWAWDaAA/ios HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
iOS response
GET /v1/pass/adaptive/rthBWAWDaAA/ios HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/vnd.apple.pkpass
[.pkpass]
Example Android request
GET /v1/pass/adaptive/rthBWAWDaAA/ios HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/vnd.apple.pkpass
[.pkpass]
GET /v1/pass/adaptive/rthBWAWDaAA/android HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Android response
GET /v1/pass/adaptive/rthBWAWDaAA/ios HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/vnd.apple.pkpass
[.pkpass]
GET /v1/pass/adaptive/rthBWAWDaAA/android HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 301 Redirect
Generates a pass from an adaptive link.
When generating passes this way, you can append request parameters mapping to pass fields to the URL to add or update values to the pass at creation time. While this document lists reserved parameters, you can provide the fieldName=value for any field contained in the adaptive link.
If you configured your adaptive link object with the isPersonalized flag set to false (or the flag is absent), the first request will create a pass, and subsequent requests will create new instances of this same pass. If the isPersonalized flag is true, every request will create a new pass. If a request includes url-encoded parameters, the isPersonalized flag is considered true and Airship will always create a new pass for every request (instead of a pass instance).
Query parameters:
- barcode stringSets the barcode value for the new pass.
- barcodeAltText stringThe alternative text for the barcode on the pass. If unspecified, the barcode value is used as the barcodeAltText.
- tags stringTags you want to associate with the pass. Multiple tags may be separated by
~, e.g.,&tags=tag1~tag2~tag3. - exid stringThe external_id you want to set for this pass.
- lat stringThe latitude of the device installing the pass, used to calculate distance to locations specified in the adaptive link.
- long stringThe longitude of the device installing the pass, used to calculate distance to locations specified in the adaptive link.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- adaptiveLinkId stringREQUIREDThe identifier of the adaptive link you want to create a pass from.
- deviceType stringREQUIREDThe device type the user needs to install. Only required when targeting a specific platform, otherwise, if a device type is not specified in the path, Airship detects the device type from the request headers. If the device type cannot be detected, Airship redirects the request to a landing page URL provided by the client as part of the adaptive link metadata. In this landing page, provide buttons that link to the explicit device-specific URLs for iOS and Android pass generation. For example,
/pass/adaptive/{adaptiveLinkId}/{ios}.Possible values:
ios,android,web
Responses
200
Requests for iOS passes return a .pkpass file. Requests for Android passes redirect to a Google Pay URL containing the Google pass JSON Web Token (JWT). Requests for
webdevices or without a device type specified return the landing page URL that a user can access to manually select a device type and install the pass.Response body:
- Content-Type:
application/jsonType:
objectA publicUrl for Android users or the landing page URL if the device type was set to
webor was not specified. - Content-Type:
application/vnd.apple.pkpassType:
objectA .pkpass file for iOS users.
404
Could not find an entry with specified
adaptiveLinkId.
Adaptive Links with external IDs
Adaptive Link endpoints with external IDs — either for the link itself or for passes generated from adaptive links. An adaptive link is a link that detects the platform of a recipient and installs the correct pass. You can send adaptive links to both Apple and Google platform users; When a user on either platform taps the link, Airship detects the user’s device platform and returns the correct pass.
To send an adaptive link to both Google and Apple platforms, you must have configured templates for both platforms. You can send an adaptive link to an individual platform, and define the behavior for the unsupported platform.
Get Adaptive Link from project
GET /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}
Example request
GET /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "1KVMz6NlFb",
"adaptiveLinkExternalId": "coolNewAdaptiveLink",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
"landingPageUrl": "https://example.com/landing.html",
"isPersonalized": false,
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 730,
"iosTemplateId": 54321,
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateId": 54322,
"androidTemplateExternalId": "android123ExtId",
"projectId": 12345,
"projectExternalId": "myExternalProject",
"createdAt": "2019-05-28T23:55:00.000Z",
"updatedAt": "2019-05-31T00:59:42.000Z",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"status": 200
}
Get an adaptive link with an external ID from a project that also has an external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectExternalId stringREQUIREDThe external ID of the project containing an adaptive link.
- adaptiveLinkExternalId stringREQUIREDThe custom identifier for an adaptive link.
Responses
200
Lists urls and available passes for an individual link.
Response body:
- Content-Type:
application/jsonAn adaptive link response includes URLs that users can access to detect and install a pass.
404
The project or adaptive link does not exist.
Create Adaptive Link in project
POST /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}
Example request
POST /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateExternalId": "android123ExtId",
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"payload": {}
}
Response
POST /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateExternalId": "android123ExtId",
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"payload": {}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "1KVMz6NlFb",
"adaptiveLinkExternalId": "coolNewAdaptiveLink",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
"landingPageUrl": "https://example.com/landing.html",
"isPersonalized": false,
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 730,
"iosTemplateId": 54321,
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateId": 54322,
"androidTemplateExternalId": "android123ExtId",
"projectId": 12345,
"projectExternalId": "myExternalProject",
"createdAt": "2019-05-28T23:55:00.000Z",
"updatedAt": "2019-05-31T00:59:42.000Z",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"status": 200
}
Create an adaptive link in a project that also has an external ID. The adaptiveLinkExternalID you use in the path becomes the ID for your new adaptive link.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectExternalId stringREQUIREDThe external ID of the project containing an adaptive link.
- adaptiveLinkExternalId stringREQUIREDThe custom identifier for an adaptive link.
Request body:
Content-Type:
application/jsonAn adaptive link request contains identifiers for the templates you used to generate passes from the link and any fields you want to set when users create passes from the link. If you need to create a boarding pass adaptive link, go to the boarding pass object.
Responses
200
A successful request results in an adaptive link.
Response body:
- Content-Type:
application/jsonAn adaptive link response includes URLs that users can access to detect and install a pass.
404
Could not find project, or could not find or create Dynamic Link object(s).
Get pass from Adaptive Link
GET /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes/id/{passExternalId}
Example request
GET /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [
{
"id": 39,
"templateId": 6,
"serialNumber": "6f019144-2285-4bb9-b28a-f863af887e53",
"createdAt": "2019-03-06T17:48:28.000Z",
"updatedAt": "2019-03-06T17:48:29.000Z",
"externalId": "ext14"
},
{
"id": 38,
"templateId": 5,
"serialNumber": "7f57d625-cf7c-455b-b3d9-c70adef7d889",
"createdAt": "2019-03-06T17:39:00.000Z",
"updatedAt": "2019-03-06T17:39:01.000Z",
"externalId": "ext14"
}
]
}
Get a pass with an external ID that was created from an adaptive link with an external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectExternalId stringREQUIREDThe external ID of the project containing the adaptive link.
- adaptiveLinkExternalId stringREQUIREDThe adaptive link passes were created from.
- passExternalId stringREQUIREDThe external ID of the pass you want to get.
Responses
200
Returns an array up to two passes created from the adaptive link — one for each template supported by the adaptive link.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- passes array[object]
The metadata for passes associated with the adaptive link. Each object in the array represents a pass.
404
The project, adaptive link, or pass ID does not exist.
Update passes from Adaptive Link
PUT /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes/id/{passExternalId}
Example request
PUT /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields": {
"Details": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons": [
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 1,
"minor": 777
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
]
}
Response
PUT /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields": {
"Details": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons": [
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 1,
"minor": 777
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"tickets": [
{
"id": 15
},
{
"id": 16
}
]
}
Update a pass with an external ID that was created from an adaptive link with an external ID. You need only provide the fields and headers you want to update for the pass; all other information will remain unchanged.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectExternalId stringREQUIREDThe external ID of the project containing the adaptive link.
- adaptiveLinkExternalId stringREQUIREDThe adaptive link passes were created from.
- passExternalId stringREQUIREDThe external ID of the pass you want to update.
Request body:
Provide only the fields or headers that you want to update for the specified pass.
Locations operate as a set operation. The array of pass locations is replaced by the locations you provide in an update; if you want to add to the locations on the pass, you must provide both the current locations and the locations you want to add in the payload.
Content-Type:
application/jsonUpdate Wallet PassOBJECT PROPERTIES- beacons arrayAPPLE ONLY
An array of beacon objects you want to update for this pass.
- fields object
The fields you want to update on the pass.
- headers object
The headers you want to update for this pass.
- locations array
The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
- semantics object<Boarding pass semantics>
An object that defines structured metadata for an Apple Wallet pass using key-value pairs. These semantic tags provide contextual information to the system to enhance the user experience.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within
fields. - universalLinks object<Universal links>
An object containing key-value pairs of universal links where each key-value pair defines a universal link.
A list of key-value pairs that represents partner URLs.
Responses
200
Returns a ticket IDs corresponding to the templates the adaptive link generated passes from. For example, if the pass was installed on both Android and iOS devices, the response will include two tickets — one to update passes supported by each template.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- tickets array[object]
404
The project, adaptive link, or pass ID does not exist.
Get Adaptive Link
GET /links/adaptive/project/{projectId}/id/{adaptiveLinkExternalId}
Example request
GET /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "1KVMz6NlFb",
"adaptiveLinkExternalId": "coolNewAdaptiveLink",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
"landingPageUrl": "https://example.com/landing.html",
"isPersonalized": false,
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 730,
"iosTemplateId": 54321,
"androidTemplateId": 54322,
"projectId": 12345,
"createdAt": "2019-05-28T23:55:00.000Z",
"updatedAt": "2019-05-31T00:59:42.000Z",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"status": 200
}
Get an adaptive link with an external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project, generated by Airship, containing the adaptive link.
- adaptiveLinkExternalId stringREQUIREDThe custom identifier for the adaptive link.
Responses
200
Lists urls and available passes for an individual link.
Response body:
- Content-Type:
application/jsonAn adaptive link response includes URLs that users can access to detect and install a pass.
404
The project or adaptive link does not exist.
Create Adaptive Link
POST /links/adaptive/project/{projectId}/id/{adaptiveLinkExternalId}
Example request
POST /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 54321,
"androidTemplateId": 54322,
"isPersonalized": false,
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"payload": {}
}
Response
POST /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 54321,
"androidTemplateId": 54322,
"isPersonalized": false,
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://example.com/landing.html",
"availablePasses": 100000,
"payload": {}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "1KVMz6NlFb",
"adaptiveLinkExternalId": "coolNewAdaptiveLink",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
"landingPageUrl": "https://example.com/landing.html",
"isPersonalized": false,
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 730,
"iosTemplateId": 54321,
"androidTemplateId": 54322,
"projectId": 12345,
"createdAt": "2019-05-28T23:55:00.000Z",
"updatedAt": "2019-05-31T00:59:42.000Z",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"status": 200
}
Create an adaptive link with an external ID. The adaptiveLinkExternalID you use in the path becomes the ID for your new adaptive link.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project, generated by Airship, containing the adaptive link.
- adaptiveLinkExternalId stringREQUIREDThe custom identifier for the adaptive link.
Request body:
Content-Type:
application/jsonAn adaptive link request contains identifiers for the templates you used to generate passes from the link and any fields you want to set when users create passes from the link. If you need to create a boarding pass adaptive link, go to the boarding pass object.
Responses
200
A successful request results in an adaptive link.
Response body:
- Content-Type:
application/jsonAn adaptive link response includes URLs that users can access to detect and install a pass.
404
Could not find or create Dynamic Link object(s).
Get passes from Adaptive Link
GET /links/adaptive/{adaptiveLinkId}/passes/id/{passExternalId}
Example request
GET /v1/links/adaptive/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Response
GET /v1/links/adaptive/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [
{
"id": 39,
"templateId": 6,
"serialNumber": "6f019144-2285-4bb9-b28a-f863af887e53",
"createdAt": "2019-03-06T17:48:28.000Z",
"updatedAt": "2019-03-06T17:48:29.000Z",
"externalId": "ext14"
},
{
"id": 38,
"templateId": 5,
"serialNumber": "7f57d625-cf7c-455b-b3d9-c70adef7d889",
"createdAt": "2019-03-06T17:39:00.000Z",
"updatedAt": "2019-03-06T17:39:01.000Z",
"externalId": "ext14"
}
]
}
Get passes with an external IDs that were created from an adaptive link.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- adaptiveLinkId stringREQUIREDThe adaptive link passes were created from.
- passExternalId stringREQUIREDThe external ID of the pass you want to get.
Responses
200
Returns an array up to two passes created from the adaptive link — one for each template supported by the adaptive link.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- passes array[object]
The metadata for passes associated with the adaptive link. Each object in the array represents a pass.
404
The adaptive link or pass ID does not exist.
Update passes from Adaptive Link
PUT /links/adaptive/{adaptiveLinkId}/passes/id/{passExternalId}
Example request
PUT /v1/links/adaptive/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields": {
"Details": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons": [
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 1,
"minor": 777
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
]
}
Response
PUT /v1/links/adaptive/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields": {
"Details": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons": [
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 1,
"minor": 777
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
]
}
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"tickets": [
{
"id": 15
},
{
"id": 16
}
]
}
Update a pass with an external ID that was created from an adaptive link. You need only provide the fields and headers you want to update for the pass; all other information will remain unchanged.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- adaptiveLinkId stringREQUIREDThe adaptive link passes were created from.
- passExternalId stringREQUIREDThe external ID of the pass you want to update.
Request body:
Provide only the fields or headers that you want to update for the specified pass.
Locations operate as a set operation. The array of pass locations is replaced by the locations you provide in an update; if you want to add to the locations on the pass, you must provide both the current locations and the locations you want to add in the payload.
Content-Type:
application/jsonUpdate Wallet PassOBJECT PROPERTIES- beacons arrayAPPLE ONLY
An array of beacon objects you want to update for this pass.
- fields object
The fields you want to update on the pass.
- headers object
The headers you want to update for this pass.
- locations array
The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
- semantics object<Boarding pass semantics>
An object that defines structured metadata for an Apple Wallet pass using key-value pairs. These semantic tags provide contextual information to the system to enhance the user experience.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within
fields. - universalLinks object<Universal links>
An object containing key-value pairs of universal links where each key-value pair defines a universal link.
A list of key-value pairs that represents partner URLs.
Responses
200
Returns a ticket IDs corresponding to the templates the adaptive link generated passes from. For example, if the pass was installed on both Android and iOS devices, the response will include two tickets — one to update passes supported by each template.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- tickets array[object]
404
The adaptive link or pass ID does not exist.
Passes
A pass is essentially a populated, personalized template intended for a single platform — Apple Wallet or Google Wallet. Passes manifest as links; you distribute the pass link to users, and they tap or click the link to install the pass.
If you want to distribute passes to both Apple and Google users, you may want to use Adaptive links instead. While a pass is intended for a single platform, so you have to distribute separate pass links to independent Apple and Google audiences, an adaptive link is a single pass link that detects the user’s platform and installs the correct pass. Adaptive links can save you the trouble of maintaining separate passes and distribution lists for your customers.
List passes for an Adaptive Link
GET /links/adaptive/{adaptiveLinkId}/passes
Example request
GET /v1/links/adaptive/rthBWAWDaAA/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/links/adaptive/rthBWAWDaAA/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 616,
"templateId": 1000057,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/616/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da0b8",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "installed",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 610,
"templateId": 1000083,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/610/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e216",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
List passes for an adaptive link.
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.
Possible values:
installed,uninstalled,been_installed,not_been_installed - pageSize integerThe number of passes per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- adaptiveLinkId stringREQUIREDThe adaptive link ID used for pass creation.
Responses
200
A successful request returns a paged list of passes for a particular adaptive link.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The total number of passes associated with an adaptive link.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes array[object]
The metadata for passes associated with the adaptive link. Each object in the array represents a pass.
404
The adaptive link ID does not exist.
List passes
GET /pass
Example request
GET /v1/pass?templateId=12345&status=uninstalled HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/pass?templateId=12345&status=uninstalled HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 61,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "uninstalled",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 60,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/60/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e201",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
List passes that your user account is responsible for. You can provide an optional template parameter, returning passes created from a particular template.
Security:
Query parameters:
- templateId stringThe
idof the template you want to look up. - status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.
Possible values:
installed,uninstalled,been_installed,not_been_installed - pageSize integerThe number of passes per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
A successful request returns a paged list of passes created from a particular template.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The total number of passes associated with the template.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes array[object]
The metadata for passes associated with the template. Each object in the array represents a pass.
Get pass
GET /pass/{id}
Example request
GET /v1/pass/1234 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/pass/1234 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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",
"installedAt": "2013-06-19T01:06:17.000Z",
"url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/1249\/download",
"status": "installed",
"fields": {
"Merchant Website": {
"formatType": "URL",
"changeMessage": "Get event details at %@",
"order": 2,
"fieldType": "back",
"value": "http:\/\/www.example.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. This endpoint will return the external ID of a pass, but only if there is one associated with it.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe
idof the pass you want to look up.
Responses
200
Returns a complete pass, including headers and fields on the pass and metadata about the pass.
Response body:
- Content-Type:One of
application/jsonA pass response includes both identifiers and the content of all fields on a pass.
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Create pass
POST /pass/{id}
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.example.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"
}
}
Response
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.example.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"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"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 external ID to the pass or generate the pass from templates with external IDs. See the appropriate endpoints to assign or use external IDs.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe
idof the template you want to create your pass from.
Request body:
Create a pass; pass composition varies by vendor.
Content-Type:
One ofapplication/jsonA pass for Apple Wallet.
A pass for Google Wallet. Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Responses
200
A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.
Response body:
- Content-Type:One of
application/jsonA pass response includes both identifiers and the content of all fields on a pass.
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Update pass
PUT /pass/{id}
Update expiration date example request
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2024-08-20T9:41-08:00"
}
},
"fields": {
"Seat": {
"value": "26E"
}
}
}
Render pass void example request
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2024-08-20T9:41-08:00"
}
},
"fields": {
"Seat": {
"value": "26E"
}
}
}
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"label": "voided"
}
}
}
Example request
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2024-08-20T9:41-08:00"
}
},
"fields": {
"Seat": {
"value": "26E"
}
}
}
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"label": "voided"
}
}
}
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.example.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"
}
]
}
Response
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2024-08-20T9:41-08:00"
}
},
"fields": {
"Seat": {
"value": "26E"
}
}
}
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"label": "voided"
}
}
}
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.example.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"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id 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.
Content-Type:
application/jsonUpdate Wallet PassOBJECT PROPERTIES- beacons arrayAPPLE ONLY
An array of beacon objects you want to update for this pass.
- fields object
The fields you want to update on the pass.
- headers object
The headers you want to update for this pass.
- locations array
The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
- semantics object<Boarding pass semantics>
An object that defines structured metadata for an Apple Wallet pass using key-value pairs. These semantic tags provide contextual information to the system to enhance the user experience.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within
fields. - universalLinks object<Universal links>
An object containing key-value pairs of universal links where each key-value pair defines a universal link.
A list of key-value pairs that represents partner URLs.
Responses
200
A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.
Response body:
- Content-Type:One of
application/jsonA pass response includes both identifiers and the content of all fields on a pass.
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Delete pass
DELETE /pass/{id}
Example request
DELETE /v1/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
DELETE /v1/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"status": "deleted",
"passId": "123"
}
Delete the specified pass.
The Delete function does not remove passes from the end-user’s device, but removes from our system. Deleted passes no longer count towards billing. See Editing Wallet Pass Expiration to deactivate the pass on the end-user’s device.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe
idof the pass you want to delete.
Responses
200
The pass was successfully deleted.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- passId integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
- status string
Indicates that the pass was deleted.
Possible values:
deleted
Generates a pass
POST /pass/{id}/dynamic
Example request
POST /v1/pass/12345/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.example.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"
}
Response
POST /v1/pass/12345/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.example.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"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"url": "https://wallet-api.urbanairship.com/v1/pass/dynamic/44e128a5-ac7a-4c9a-be4c-224b6bf81b20"
}
Generates a pass with an optional expiration date and serial number. You can also assign an external ID to passes generated from this endpoint.
Security:
Query parameters:
- expiry stringThe expiration date for the pass.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe
templateIdof the template you want to create the pass from.
Request body:
Create a pass; pass composition varies by vendor.
Content-Type:
One ofapplication/jsonA pass for Apple Wallet.
A pass for Google Wallet. Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Responses
200
A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.
Response body:
- Content-Type:One of
application/jsonA pass response includes both identifiers and the content of all fields on a pass.
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Delete locations from pass
DELETE /pass/{passId}/location/{passLocationId}
Example request
DELETE /v1/pass/123/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Delete the specified location from the specified pass.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- passId stringREQUIREDThe
idof the pass you want to remove locations from. - passLocationId stringREQUIREDThe location you want to remove from the pass.
Responses
200
Success.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- locations array
Add locations to pass
POST /pass/{passId}/locations
Example request
POST /v1/pass/123/locations HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"locations": [
{
"longitude": "-122.374",
"latitude": "37.618",
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
},
{ "...": "..." }
]
}
Response
POST /v1/pass/123/locations HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"locations": [
{
"longitude": "-122.374",
"latitude": "37.618",
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
},
{ "...": "..." }
]
}
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- passId stringREQUIREDThe pass you want to add locations to.
Request body:
Set locations for the pass.
Content-Type:
application/jsonType: object
Responses
200
Returns
passLocationIdfor each location on the pass. Use this value to identify locations in other location-based operations.Response body:
- Content-Type:
application/jsonType:
array
List passes for a tag
GET /tag/{tag}/passes
Example request
GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
Response
GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 61,
"templateId": 1000057,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
"createdAt": "2023-04-19T06:15:01.000Z",
"updatedAt": "2023-04-19T06:15:01.000Z",
"status": "installed",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 51,
"templateId": 1000081,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/51/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e223",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "ios"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
List the passes associated with the specified tag.
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.
Possible values:
installed,uninstalled,been_installed,not_been_installed - pageSize integerThe number of passes per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want tags returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- tag stringREQUIREDA tag
idorname. The request returns a paginated list of passes associated with the specified tag.
Responses
200
A successful response returns a paginated array of passes.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The total number of results.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes object
Meta information about passes.
OBJECT PROPERTIES- createdAt string
The date and time when the item was last updated.
- id integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
- installedAt string
The date and time when pass was first installed on the device.
- platform string
Wallet platform.
Possible values:
iOS,Android - serialNumber string
The serial number of the pass.
- status string
Recent on-device pass status.
Possible values:
installed,uninstalled,not_been_installed - templateId integer
The identifier for the template. You can recall the template by ID in other operations.
- uninstalledAt string
The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled.
- updatedAt string
The date and time when the item was created.
- url string
Pass download URL.
Passes with external IDs
These endpoints support passes incorporating external IDs for the template, the pass, or both. A pass is essentially a populated, personalized template intended for a single platform — Apple Wallet or Google Wallet. Passes manifest as links; you distribute the pass link to users, and they tap or click the link to install the pass.
If you want to distribute passes to both Apple and Google users, you may want to use adaptive links instead. While a pass is intended for a single platform, so you have to distribute separate pass links to independent Apple and Google audiences, an adaptive link is a single pass link that detects the user’s platform and installs the correct pass. Adaptive links can save you the trouble of maintaining separate passes and distribution lists for your customers.
Update pass
PUT /pass/id/{externalId}
Example request
PUT /v1/pass/id/myExternalPassId HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"templates": ["5350", "5359"],
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.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"
}
]
}
Response
PUT /v1/pass/id/myExternalPassId HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"templates": ["5350", "5359"],
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.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"
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- externalId stringREQUIREDThe external ID of the pass you want to modify.
Request body:
Provide only the fields you want to update.
Locations operate as a set operation. The array of pass locations is replaced by the locations you provide in an update; if you want to add to the locations on the pass, you must provide both the current locations and the locations you want to add in the payload.
Content-Type:
One ofapplication/jsonobject
- Update Wallet Pass objectOBJECT PROPERTIES
- beacons arrayAPPLE ONLY
An array of beacon objects you want to update for this pass.
- fields object
The fields you want to update on the pass.
- headers object
The headers you want to update for this pass.
- locations array
The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
- semantics object<Boarding pass semantics>
An object that defines structured metadata for an Apple Wallet pass using key-value pairs. These semantic tags provide contextual information to the system to enhance the user experience.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within
fields. - universalLinks object<Universal links>
An object containing key-value pairs of universal links where each key-value pair defines a universal link.
A list of key-value pairs that represents partner URLs.
Responses
200
A response returns one or more
ticketIdvalues, each referencing the pass update operation. If your request does not include thetemplatesarray, the response includes a singleticketId. If your request includes thetemplatesarray, the response is an array of of ticket objects, corresponding to the order of templates in the array.Response body:
- Content-Type:One of
application/json- OBJECT PROPERTIES
- ticketId integer
A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.
- OBJECT PROPERTIES
Create pass from a template
POST /pass/id/{templateExternalId}/id/{passExternalId}
Example request
POST /v1/pass/id/myExternalTemplate/id/myNewPass HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2014-08-20T09:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.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"
}
}
Response
POST /v1/pass/id/myExternalTemplate/id/myNewPass HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2014-08-20T09:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.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"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"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 operations against the pass in addition to the standard, unique id given by Wallet.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateExternalId stringREQUIREDThe external ID of the template you want to create your pass from.
- passExternalId stringREQUIREDThe external ID that you want to give your pass.
Request body:
Create a pass; pass composition varies by vendor.
Content-Type:
One ofapplication/jsonA pass for Apple Wallet.
A pass for Google Wallet. Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Responses
200
A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.
Response body:
- Content-Type:One of
application/jsonA pass response includes both identifiers and the content of all fields on a pass.
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Get pass
GET /pass/template/{templateId}/id/{passExternalId}
Example request
GET /v1/pass/template/123/id/mypass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/pass/template/123/id/mypass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"tags":[
],
"headers": {
"barcodeAltText": {
"formatType": "String",
"changeMessage": null,
"fieldType": "barcode",
"value": "123456789",
"label": "",
"required": false,
"hideEmpty": false
},
"logo_color": {
"formatType": "String",
"changeMessage": null,
"fieldType": "topLevel",
"value": "rgb(24,86,148)",
"label": "",
"required": false,
"hideEmpty": false
},
"icon_image": {
"formatType": "String",
"changeMessage": null,
"fieldType": "topLevel",
"value": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
"label": "",
"required": false,
"hideEmpty": false
},
"barcode_value": {
"formatType": "String",
"changeMessage": null,
"fieldType": "barcode",
"value": "123456789",
"label": "",
"required": false,
"hideEmpty": false
},
"logo_text": {
"formatType": "String",
"changeMessage": "%@",
"fieldType": "topLevel",
"value": "Logo",
"label": "",
"required": false,
"hideEmpty": false
},
"barcode_encoding": {
"formatType": "String",
"changeMessage": null,
"fieldType": "barcode",
"value": "iso-8859-1",
"label": "",
"required": false,
"hideEmpty": false
},
"suppress_strip_shine": {
"formatType": "String",
"changeMessage": null,
"fieldType": "topLevel",
"value": "true",
"label": "",
"required": false,
"hideEmpty": false
},
"barcode_label": {
"formatType": "String",
"changeMessage": "%@",
"fieldType": "barcode",
"value": "Member ID",
"label": "",
"required": false,
"hideEmpty": false
},
"barcode_type": {
"formatType": "String",
"changeMessage": null,
"fieldType": "barcode",
"value": "PKBarcodeFormatPDF417",
"label": "",
"required": false,
"hideEmpty": false
},
"foreground_color": {
"formatType": "String",
"changeMessage": null,
"fieldType": "topLevel",
"value": "rgb(255,255,255)",
"label": "",
"required": false,
"hideEmpty": false
},
"background_color": {
"formatType": "String",
"changeMessage": null,
"fieldType": "topLevel",
"value": "rgb(0,147,201)",
"label": "",
"required": false,
"hideEmpty": false
},
"relevantDate": {
"changeMessage": "The new date is %@",
"label": "relevantDate",
"hideEmpty": false,
"formatType": "String",
"value": "2015-12-31T23:00:00-08:00",
"fieldType": "topLevel",
"required": false
}
},
"id": "1234",
"templateId": "12345",
"externalId": "mypass",
"updatedAt": "2013-06-19T01:06:23.000Z",
"createdAt": "2013-06-19T01:06:17.000Z",
"serialNumber": "14f94898-2f5e-46f5-925c-7e29fa9a0508",
"installedAt": "2013-06-19T01:06:17.000Z",
"url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/1249\/download",
"status": "installed",
"fields": {
"Merchant Website": {
"formatType": "URL",
"changeMessage": "Get event details at %@",
"order": 2,
"fieldType": "back",
"value": "http:\/\/www.example.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 with an external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe ID of the template the pass will be or was created from.
- passExternalId stringREQUIREDThe custom ID assigned to the pass.
Responses
200
A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.
Response body:
- Content-Type:One of
application/jsonA pass response includes both identifiers and the content of all fields on a pass.
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
404
The pass or template ID does not exist.
Create pass
POST /pass/template/{templateId}/id/{passExternalId}
Example request
POST /v1/pass/template/123/id/mypass HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2014-08-20T09:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.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"
}
}
Response
POST /v1/pass/template/123/id/mypass HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2014-08-20T09:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.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"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"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 operations against the pass like you would use the standard, unique id given by Wallet.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe ID of the template the pass will be or was created from.
- passExternalId stringREQUIREDThe external ID you want to assign to the new pass.
Request body:
Create a pass; pass composition varies by vendor.
Content-Type:
One ofapplication/jsonA pass for Apple Wallet.
A pass for Google Wallet. Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Responses
200
A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.
Response body:
- Content-Type:One of
application/jsonA pass response includes both identifiers and the content of all fields on a pass.
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
404
The pass or template ID does not exist.
Update pass for a template
PUT /pass/template/{templateId}/id/{passExternalId}
Example request
PUT /v1/pass/template/123/id/mypass HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.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"
}
]
}
Response
PUT /v1/pass/template/123/id/mypass HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.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"
}
]
}
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"ticketId": 1234
}
Update a pass with an external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe ID of the template the pass will be or was created from.
- passExternalId stringREQUIREDThe external ID of the pass you want to modify.
Request body:
Update a pass. You can provide any of the fields or headers used when creating a pass to update the pass.
Content-Type:
One ofapplication/jsonA pass for Apple Wallet.
A pass for Google Wallet. Unlike templates, in which the
fieldsModelcontains fields nested insidemoduleobjects, 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 Wallet passes are very similar to Apple Wallet passes.
Responses
200
The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
400
The request was malformed.
404
The pass or template ID does not exist.
Delete pass
DELETE /pass/template/{templateId}/id/{passExternalId}
Example request
DELETE /v1/pass/template/123/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
DELETE /v1/pass/template/123/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"status": "deleted",
"passId": "33"
}
Delete a pass with an external ID.
The Delete function does not remove passes from the end-user’s device, but removes from our system. Deleted passes no longer count towards billing. See Editing Wallet Pass Expiration to deactivate the pass on the end-user’s device.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe ID of the template the pass will be or was created from.
- passExternalId stringREQUIREDThe external ID of the pass you want to delete.
Responses
200
The pass was successfully deleted.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- passId integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
- status string
Indicates that the pass was deleted.
Possible values:
deleted
404
The pass or template ID does not exist.
Delete locations from pass
DELETE /pass/template/{templateId}/id/{passExternalId}/location/{locationId}
Example request
DELETE /v1/pass/template/123/id/mypass/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Delete the specified location from a pass using an external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template of the pass that you want to delete locations from.
- passExternalId stringREQUIREDThe external ID of the pass you want to delete locations from.
- locationId stringREQUIREDThe location you want to remove from the pass.
Responses
200
Success.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- locations array
404
The pass, template ID, or location does not exist.
Add locations to pass
POST /pass/template/{templateId}/id/{passExternalId}/locations
Example request
POST /v1/pass/template/123/id/mypass/locations HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"locations": [
{
"longitude": "-122.374",
"latitude": "37.618",
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
},
{ "...": "..." }
]
}
Response
POST /v1/pass/template/123/id/mypass/locations HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"locations": [
{
"longitude": "-122.374",
"latitude": "37.618",
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
},
{ "...": "..." }
]
}
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template of the pass that you want to add locations to.
- passExternalId stringREQUIREDThe external ID of the pass you want to add locations to.
Request body:
Set locations for the pass.
Content-Type:
application/jsonType: object
Responses
200
Returns
passLocationIdfor each location on the pass. Use this value to identify locations in other location-based operations.Response body:
- Content-Type:
application/jsonType:
array
404
The pass or template ID does not exist.
Tags
Tags are plain-text identifiers for passes. Use tags to identify passes for segmentation purposes, or to target an audience of passes for updates.
Tags are limited to 15 per pass.
List tags for pass with external ID
GET /pass/template/{templateId}/id/{passExternalId}/tags
Example request
GET /v1/pass/template/123/id/mypass/tags HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
Response
GET /v1/pass/template/123/id/mypass/tags HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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. See also List tags for pass.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template of the pass that you want to get tags for.
- passExternalId stringREQUIREDThe external ID of the pass you want to list tags for.
Responses
200
An array of tags belonging to the pass.
Response body:
- Content-Type:OBJECT PROPERTIES
application/jsonAn array of tags associated with the pass.
Update tags for pass with external ID
PUT /pass/template/{templateId}/id/{passExternalId}/tags
Example request
PUT /v1/pass/template/123/id/mypass/tags HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"tags": ["tag-name"]
}
Response
PUT /v1/pass/template/123/id/mypass/tags HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"tags": ["tag-name"]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"newTags": ["tag-name"],
"mappings": 1
}
Assign or update tags on a pass with an external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template of the pass that you want to apply tags to.
- passExternalId stringREQUIREDThe external ID of the pass you want to apply tags to.
Request body:
An array of tags that you want to associate with the pass.
Content-Type:
application/jsonAdd Tags to PassRequestAn array of tags that you want to add to a pass.
OBJECT PROPERTIESAn array of strings, each string representing a tag.
Responses
200
Lists the tags added to the pass.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- mappings integer
The number of tags added.
- newTags array[string]
A list of tags successfully added to the pass.
404
The pass or template ID does not exist.
List tags for pass
GET /pass/{passId}/tags
Example request
GET /v1/pass/123/tags HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
Response
GET /v1/pass/123/tags HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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. See also List tags for pass with external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- passId stringREQUIREDThe ID of the pass you want to list tags for.
Responses
200
An array of tags belonging to the pass.
Response body:
- Content-Type:OBJECT PROPERTIES
application/jsonAn array of tags associated with the pass.
Add tags to pass
PUT /pass/{passId}/tags
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 request with external ID
PUT /v1/pass/123/tags HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"tags": ["tag-name"]
}
PUT /v1/pass/id/mypass/tags HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"tags": ["tag-name"]
}
Response
PUT /v1/pass/123/tags HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"tags": ["tag-name"]
}
PUT /v1/pass/id/mypass/tags HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"tags": ["tag-name"]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"newTags": ["tag-name"],
"mappings": 1
}
Add tags to a pass, limited to 15 tags per pass.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- passId stringREQUIREDThe ID of the pass you want to add tags to. For External IDs, format the
{passId}asid/{externalId}.
Request body:
An array of tags that you want to associate with the pass.
Content-Type:
application/jsonAdd Tags to PassRequestAn array of tags that you want to add to a pass.
OBJECT PROPERTIESAn array of strings, each string representing a tag.
Responses
200
Lists the tags added to the pass.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- mappings integer
The number of tags added.
- newTags array[string]
A list of tags successfully added to the pass.
List all tags
GET /tag
Example request
GET /v1/tag HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
Response
GET /v1/tag HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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:
Query parameters:
- pageSize integerThe number of tags per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want tags returned in, defaulting to
id.Possible values:
id,createdAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
A paginated array of tags.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- Pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- count integer
The number of items returned.
Delete tag
DELETE /tag/{tag}
Example request
DELETE /v1/tag/tag-name HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
DELETE /v1/tag/tag-name HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "success",
"tagId": 5,
"count": 93
}
Delete the specified tag and remove it from all passes.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- tag stringREQUIREDThe tag you want to delete.
Responses
200
A successful operation returns a count of affected passes.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The number of passes the tag was removed from.
- status string
The operation was successful.
Possible values:
success - tagId integer
The ID of the deleted tag.
Remove tag from a pass
DELETE /tag/{tag}/pass/{pass}
Example request
DELETE /v1/tag/tag-name/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external ID
DELETE /v1/tag/tag-name/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
DELETE /v1/tag/tag-name/pass/id/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
DELETE /v1/tag/tag-name/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
DELETE /v1/tag/tag-name/pass/id/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"passId": 123,
"status": "success",
"tagId": 70
}
Remove a tag from the specified pass.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- tag stringREQUIREDThe tag you want to remove from the pass.
- pass stringREQUIRED
Responses
200
A successful response includes the ID of the removed tag and the ID of the pass it was removed from.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- passId integer
The ID of the pass that the tag was removed from.
- status string
The operation was successful.
Possible values:
success - tagId integer
The ID of the removed tag.
List passes for a tag
GET /tag/{tag}/passes
Example request
GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
Response
GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 61,
"templateId": 1000057,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
"createdAt": "2023-04-19T06:15:01.000Z",
"updatedAt": "2023-04-19T06:15:01.000Z",
"status": "installed",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 51,
"templateId": 1000081,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/51/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e223",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "ios"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
List the passes associated with the specified tag.
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.
Possible values:
installed,uninstalled,been_installed,not_been_installed - pageSize integerThe number of passes per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want tags returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- tag stringREQUIREDA tag
idorname. The request returns a paginated list of passes associated with the specified tag.
Responses
200
A successful response returns a paginated array of passes.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The total number of results.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes object
Meta information about passes.
OBJECT PROPERTIES- createdAt string
The date and time when the item was last updated.
- id integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
- installedAt string
The date and time when pass was first installed on the device.
- platform string
Wallet platform.
Possible values:
iOS,Android - serialNumber string
The serial number of the pass.
- status string
Recent on-device pass status.
Possible values:
installed,uninstalled,not_been_installed - templateId integer
The identifier for the template. You can recall the template by ID in other operations.
- uninstalledAt string
The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled.
- updatedAt string
The date and time when the item was created.
- url string
Pass download URL.
Update passes by tag
PUT /tag/{tag}/passes
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"
}
}
}
Response
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"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 123
}
Update all of the passes that have a given tag.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- tag stringREQUIREDThe tag associated with the passes you want to update.
Request body:
Provide only the fields you want to update.
Content-Type:
OBJECT PROPERTIESapplication/json- fields object
Responses
200
A successful request returns a
ticketId.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
Remove tag from all passes
DELETE /tag/{tag}/passes
Example request
DELETE /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
DELETE /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"count": 38,
"status": "success",
"tagId": 2
}
Remove a tag from all of its passes.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- tag stringREQUIREDThe tag you want to remove.
Responses
200
A successful response returns a count of the affected passes.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The number of passes the tag was removed from.
- status string
The operation was successful.
Possible values:
success - tagId integer
The ID of the deleted tag.
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
GET /segments/{projectId}
Example request
GET /v1/segments/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/segments/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"segments": [
{
"creation_date": "2017-03-17T05:45:21Z",
"display_name": "timezone",
"id": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
"modification_date": "2017-03-17T05:45:21Z"
},
{
"creation_date": "2017-03-17T23:29:06Z",
"display_name": "my testing segment",
"id": "5eae7f52-3dc7-4a67-8a89-9b357815e7f7",
"modification_date": "2017-03-17T23:29:06Z"
}
]
}
List meta information for all segments for a project.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
Responses
200
A response returns a list of segments for a project.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- segments array[object]
Create segment
POST /segments/{projectId}
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"
}
Response
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"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ok": true,
"segmentId": "b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
"operationId": "dd2f1d32-aca9-4463-91c2-a3420bbcd489"
}
Create a segment for a project.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
Request body:
Contains and, or, or not operators for tags that identify your segment.
Content-Type:
OBJECT PROPERTIESapplication/json- criteria object<Segment selector>
Boolean tag selectors specifying a group of passes. You can nest
ANDandORselectors. - display_name string
The name of the segment.
Responses
200
A response returns a segment ID that you can use to reference the segment in future operations.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ok boolean
If true, the operation completed successfully.
- operationId string
An identifier for the operation. Use this value to reference the operation for troubleshooting purposes.
- segmentId string
An identifier for the segment. Use this value to reference the segment in other operations.
Look up segment
GET /segments/{projectId}/{segmentId}
Example request
GET /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"criteria": {
"and": [
{
"tag": "TZ_PST"
},
{
"not": {
"tag": "TZ_ET"
}
}
]
},
"display_name": "timezone"
}
Returns the selector criteria for a segment.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
- segmentId stringREQUIREDThe ID of the segment.
Responses
200
A successful request returns the selection criteria for the segment.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- criteria object<Segment selector>
Boolean tag selectors specifying a group of passes. You can nest
ANDandORselectors. - display_name string
The name of the segment.
Update segment
PUT /segments/{projectId}/{segmentId}
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"
}
Response
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"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ok": true,
"segmentId": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a",
"operationId": "f573b3c5-b0ee-4461-a179-2e78aab20400"
}
Update selection criteria or the display name for a segment.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
- segmentId stringREQUIREDThe ID of the segment.
Request body:
Content-Type:
OBJECT PROPERTIESapplication/json- criteria object<Segment selector>
Boolean tag selectors specifying a group of passes. You can nest
ANDandORselectors. - display_name string
The name of the segment.
Responses
200
A response returns a segment ID that you can use to reference the segment in future operations.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ok boolean
If true, the operation completed successfully.
- operationId string
An identifier for the operation. Use this ID to reference the operation for troubleshooting purposes.
- segmentId string
An identifier for the segment that you can use to reference the segment in other operations.
Delete segment
DELETE /segments/{projectId}/{segmentId}
Example request
DELETE /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
DELETE /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 204 No Content
Delete a segment by ID. This operation just deletes the segment criteria. The passes previously selected by this criteria are unchanged.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
- segmentId stringREQUIREDThe ID of the segment.
Responses
204
A successful delete request returns no content.
Update passes by segment
PUT /segments/{projectId}/{segmentId}/passes
Example request
PUT /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a/passes?templateId=6789 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"fields":{
"secondary1":{
"value":"Mega Offer"
},
"primary1":{
"value":"$20 Off"
}
}
}
Response
PUT /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a/passes?templateId=6789 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"fields":{
"secondary1":{
"value":"Mega Offer"
},
"primary1":{
"value":"$20 Off"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ticketId": 123
}
Update passes by segment ID and template ID.
Query parameters:
- templateId string
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
- segmentId stringREQUIREDThe ID of the segment.
Request body:
Provide only the fields you want to update.
Content-Type:
OBJECT PROPERTIESapplication/json- fields object
Responses
200
A response returns one or more
ticketIdvalues, each referencing the pass update operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.
Flights
Create and store flight information for use with boarding passes. When creating boarding passes, you can reference a flight, automatically populating flight information on the pass. By storing and referencing flight information independently of your passes, you can update a single flight, automatically pushing an update to all passes referencing that flight.
Update flights with external ID in a pass group
PUT /flights/project/id/{projectExternalId}/id/passGroups/{passGroup}
Example request
PUT /v1/flights/project/id/project123ExtId/id/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields": {
"departureTime": {
"value": "2018-08-30T10:00:00"
}
}
}
Response
PUT /v1/flights/project/id/project123ExtId/id/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields": {
"departureTime": {
"value": "2018-08-30T10:00:00"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"groupName" : "sfo-pdx-20180730",
"flights" : [
{
"flightId" : 123
},
{
"flightId" : 456
}
]
}
Update fields common to a group of flights. Provide only the keys that you want to update from fields object of an flight Request; any fields that you omit from the payload remain unchanged.
See also Update flights in a pass group.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectExternalId stringREQUIREDThe project that the flight belongs to.
- passGroup stringREQUIREDThe pass group that you want to modify.
Request body:
Provide only the field(s) you want to update for all of the flights in the group.
Content-Type:
OBJECT PROPERTIESapplication/json- fields object
Provide only the keys that you want to update from
fieldsobject of an flight Request; any fields that you omit from the payload remain unchanged.
Responses
200
The update was successful.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- flights array[object]
Lists the flights updated as a part of this pass group.
- groupName string
The pass group that you updated in this request.
400
The request was malformed.
404
The project ID or pass group was not found.
Create flight with external ID
POST /flights/project/id/{projectExternalId}/id/{flightExternalId}
Example request
POST /v1/flights/project/id/project123ExtId/id/flight123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": { "value": "815" },
"airlineCode": { "value": "WN" },
"airlineName": { "value": "Southwest Airlines" },
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "25"
},
"boardingTime": { "value": "2018-07-30T08:35:00" },
"departureTime": { "value": "2018-07-30T09:00:00" },
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalTime": { "value": "2018-07-30T11:00:00" },
"flightStatus": { "value": "scheduled" }
}
}
Response
POST /v1/flights/project/id/project123ExtId/id/flight123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": { "value": "815" },
"airlineCode": { "value": "WN" },
"airlineName": { "value": "Southwest Airlines" },
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "25"
},
"boardingTime": { "value": "2018-07-30T08:35:00" },
"departureTime": { "value": "2018-07-30T09:00:00" },
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalTime": { "value": "2018-07-30T11:00:00" },
"flightStatus": { "value": "scheduled" }
}
}
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"flightExternalId": "flight123ExtId",
"projectId": 12345,
"projectExternalId": "project123ExtId",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "25"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2018-07-30T08:35:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2018-07-30T09:00:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2018-07-30T11:00:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
}
}
}
Create flights with external ID. See also Create flight.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectExternalId stringREQUIREDThe project you want to create the flight in.
- flightExternalId stringREQUIREDThe external identifier you want to give to the flight.
Request body:
Content-Type:
application/jsonA complete flight request object.
The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.
Responses
200
A successful request returns the
flightIdandflightExternalId(if applicable) values, so you can reference the flight in later operations.Response body:
- Content-Type:
application/jsonA complete flight response, including identifiers to reference the flight and the fields defined within the flight.
Create flight
POST /flights/project/{projectId}
Example request
POST /v1/flights/project/12345 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20250319"],
"fields": {
"flightNumber": { "value": "815" },
"airlineCode": { "value": "WN" },
"airlineName": { "value": "Southwest Airlines" },
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "25"
},
"boardingTime": { "value": "2025-03-19T20:30:00" },
"departureTime": { "value": "2025-03-19T20:59" },
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalTime": { "value": "2025-03-20T09:30:00" },
"flightStatus": { "value": "scheduled" },
"semantics" :{
"airlineCode": "WN",
"flightNumber": 2214,
"originalBoardingDate": "2025-03-19T20:30:00-08:00",
"originalDepartureDate": "2025-03-20T02:00:00-05:00",
"originalArrivalDate": "2025-03-20T02:00:00-05:00",
"currentBoardingDate": "2025-03-19T20:59:00-08:00",
"currentDepartureDate": "2025-03-19T20:59:00-08:00",
"currentArrivalDate": "2025-03-20T09:30:00-08:00",
"departureAirportCode": "SFO",
"departureCityName": "San Francisco",
"departureLocationTimeZone": "America/Los_Angeles",
"departureAirportLocation": {
"latitude": 37.6191,
"longitude": 122.3816
},
"departureGate": "25",
"departureTerminal": "2",
"destinationAirportCode": "PDX",
"destinationCityName": "Portland",
"destinationLocationTimeZone": "America/Los_Angeles",
"destinationAirportLocation": {
"latitude": 40.6446,
"longitude": 73.7797
},
"destinationGate": "6",
"destinationTerminal": "1"
}
}
}
Response
POST /v1/flights/project/12345 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20250319"],
"fields": {
"flightNumber": { "value": "815" },
"airlineCode": { "value": "WN" },
"airlineName": { "value": "Southwest Airlines" },
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "25"
},
"boardingTime": { "value": "2025-03-19T20:30:00" },
"departureTime": { "value": "2025-03-19T20:59" },
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalTime": { "value": "2025-03-20T09:30:00" },
"flightStatus": { "value": "scheduled" },
"semantics" :{
"airlineCode": "WN",
"flightNumber": 2214,
"originalBoardingDate": "2025-03-19T20:30:00-08:00",
"originalDepartureDate": "2025-03-20T02:00:00-05:00",
"originalArrivalDate": "2025-03-20T02:00:00-05:00",
"currentBoardingDate": "2025-03-19T20:59:00-08:00",
"currentDepartureDate": "2025-03-19T20:59:00-08:00",
"currentArrivalDate": "2025-03-20T09:30:00-08:00",
"departureAirportCode": "SFO",
"departureCityName": "San Francisco",
"departureLocationTimeZone": "America/Los_Angeles",
"departureAirportLocation": {
"latitude": 37.6191,
"longitude": 122.3816
},
"departureGate": "25",
"departureTerminal": "2",
"destinationAirportCode": "PDX",
"destinationCityName": "Portland",
"destinationLocationTimeZone": "America/Los_Angeles",
"destinationAirportLocation": {
"latitude": 40.6446,
"longitude": 73.7797
},
"destinationGate": "6",
"destinationTerminal": "1"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"projectId": 12345,
"createdAt": "2025-03-05T09:12:32Z",
"updatedAt": "2025-03-05T09:12:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "25"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2025-03-19T20:30:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2025-03-19T20:59:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2025-03-20T09:30:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
},
"semantics" :{
"airlineCode": "WN",
"flightNumber": 2214,
"originalBoardingDate": "2025-03-19T20:30:00-08:00",
"originalDepartureDate": "2025-03-20T02:00:00-05:00",
"originalArrivalDate": "2025-03-20T02:00:00-05:00",
"currentBoardingDate": "2025-03-19T20:59:00-08:00",
"currentDepartureDate": "2025-03-19T20:59:00-08:00",
"currentArrivalDate": "2025-03-20T09:30:00-08:00",
"departureAirportCode": "SFO",
"departureCityName": "San Francisco",
"departureLocationTimeZone": "America/Los_Angeles",
"departureAirportLocation": {
"latitude": 37.6191,
"longitude": 122.3816
},
"departureGate": "25",
"departureTerminal": "2",
"destinationAirportCode": "PDX",
"destinationCityName": "Portland",
"destinationLocationTimeZone": "America/Los_Angeles",
"destinationAirportLocation": {
"latitude": 40.6446,
"longitude": 73.7797
},
"destinationGate": "6",
"destinationTerminal": "1"
}
}
}
Create flights. See also Create flight with external ID.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project you want to create the flight in.
Request body:
Content-Type:
application/jsonA complete flight request object.
The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.
Responses
200
A successful request returns the
flightIdandflightExternalId(if applicable) values, so you can reference the flight in later operations.Response body:
- Content-Type:
application/jsonA complete flight response, including identifiers to reference the flight and the fields defined within the flight.
Update flights in a pass group
PUT /flights/project/{projectId}/passGroups/{passGroup}
Example request
PUT /v1/flights/project/12345/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields": {
"departureTime": {
"value": "2018-08-30T10:00:00"
}
}
}
Response
PUT /v1/flights/project/12345/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"fields": {
"departureTime": {
"value": "2018-08-30T10:00:00"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"groupName" : "sfo-pdx-20180730",
"flights" : [
{
"flightId" : 123
},
{
"flightId" : 456
}
]
}
Update all of the flights in a pass group. See also Update flights with external ID in a pass group.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the flight belongs to. Use either the Airship-generated project ID or the external ID.
- passGroup integerREQUIREDThe pass group that you want to modify.
Request body:
Update fields common to a group of flights.
Content-Type:
OBJECT PROPERTIESapplication/json- fields object
Provide only the keys that you want to update from
fieldsobject of an flight Request; any fields that you omit from the payload remain unchanged.
Responses
200
The update was successful.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- flights array[object]
Lists the flights updated as a part of this pass group.
- groupName string
The pass group that you updated in this request.
400
The request was malformed.
404
The project ID or pass group was not found.
Get flight
GET /flights/project/{projectId}/{flightId}
Example request
GET /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"projectId": 12345,
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "21"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2025-03-19T20:30:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2025-03-20T02:00:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2025-03-20T02:00:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
},
"semantics" :{
"airlineCode": "WN",
"flightNumber": 2214,
"originalBoardingDate": "2025-03-19T20:30:00-08:00",
"originalDepartureDate": "2025-03-20T02:00:00-05:00",
"originalArrivalDate": "2025-03-20T02:00:00-05:00",
"currentBoardingDate": "2025-03-19T20:59:00-08:00",
"currentDepartureDate": "2025-03-19T20:59:00-08:00",
"currentArrivalDate": "2025-03-20T09:30:00-08:00",
"departureAirportCode": "SFO",
"departureCityName": "San Francisco",
"departureLocationTimeZone": "America/Los_Angeles",
"departureAirportLocation": {
"latitude": 37.6191,
"longitude": 122.3816
},
"departureGate": "25",
"departureTerminal": "2",
"destinationAirportCode": "PDX",
"destinationCityName": "Portland",
"destinationLocationTimeZone": "America/Los_Angeles",
"destinationAirportLocation": {
"latitude": 40.6446,
"longitude": 73.7797
},
"destinationGate": "6",
"destinationTerminal": "1"
}
}
}
Example request with external ID
GET /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"projectId": 12345,
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "21"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2025-03-19T20:30:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2025-03-20T02:00:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2025-03-20T02:00:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
},
"semantics" :{
"airlineCode": "WN",
"flightNumber": 2214,
"originalBoardingDate": "2025-03-19T20:30:00-08:00",
"originalDepartureDate": "2025-03-20T02:00:00-05:00",
"originalArrivalDate": "2025-03-20T02:00:00-05:00",
"currentBoardingDate": "2025-03-19T20:59:00-08:00",
"currentDepartureDate": "2025-03-19T20:59:00-08:00",
"currentArrivalDate": "2025-03-20T09:30:00-08:00",
"departureAirportCode": "SFO",
"departureCityName": "San Francisco",
"departureLocationTimeZone": "America/Los_Angeles",
"departureAirportLocation": {
"latitude": 37.6191,
"longitude": 122.3816
},
"departureGate": "25",
"departureTerminal": "2",
"destinationAirportCode": "PDX",
"destinationCityName": "Portland",
"destinationLocationTimeZone": "America/Los_Angeles",
"destinationAirportLocation": {
"latitude": 40.6446,
"longitude": 73.7797
},
"destinationGate": "6",
"destinationTerminal": "1"
}
}
}
GET /v1/flights/project/id/project123ExtId/id/flight123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Response with external ID
GET /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"projectId": 12345,
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "21"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2025-03-19T20:30:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2025-03-20T02:00:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2025-03-20T02:00:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
},
"semantics" :{
"airlineCode": "WN",
"flightNumber": 2214,
"originalBoardingDate": "2025-03-19T20:30:00-08:00",
"originalDepartureDate": "2025-03-20T02:00:00-05:00",
"originalArrivalDate": "2025-03-20T02:00:00-05:00",
"currentBoardingDate": "2025-03-19T20:59:00-08:00",
"currentDepartureDate": "2025-03-19T20:59:00-08:00",
"currentArrivalDate": "2025-03-20T09:30:00-08:00",
"departureAirportCode": "SFO",
"departureCityName": "San Francisco",
"departureLocationTimeZone": "America/Los_Angeles",
"departureAirportLocation": {
"latitude": 37.6191,
"longitude": 122.3816
},
"departureGate": "25",
"departureTerminal": "2",
"destinationAirportCode": "PDX",
"destinationCityName": "Portland",
"destinationLocationTimeZone": "America/Los_Angeles",
"destinationAirportLocation": {
"latitude": 40.6446,
"longitude": 73.7797
},
"destinationGate": "6",
"destinationTerminal": "1"
}
}
}
GET /v1/flights/project/id/project123ExtId/id/flight123ExtId HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"flightExternalId": "flight123ExtId",
"projectId": 12345,
"projectExternalId": "project123ExtId",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "21"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2018-07-30T09:20:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2018-07-30T09:45:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2018-07-30T11:45:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
}
}
}
Returns information for a single flight.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the flight belongs to. For External IDs, format the
{projectId}asid/{projectExternalId}. - flightId integerREQUIREDThe flight you want to get, update, or delete. For External IDs, format the
{flightId}asid/{flightExternalId}.
Responses
200
A successful request returns the
flightIdandflightExternalId(if applicable) values, so you can reference the flight in later operations.Response body:
- Content-Type:
application/jsonA complete flight response, including identifiers to reference the flight and the fields defined within the flight.
Update flight
PUT /flights/project/{projectId}/{flightId}
Example request
PUT /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"departureGate": { "value": "21" },
"boardingTime": { "value": "2018-07-30T09:20:00" },
"departureTime": { "value": "2018-07-30T09:45:00" },
"arrivalTime": { "value": "2018-07-30T11:45:00" }
}
}
Response
PUT /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"departureGate": { "value": "21" },
"boardingTime": { "value": "2018-07-30T09:20:00" },
"departureTime": { "value": "2018-07-30T09:45:00" },
"arrivalTime": { "value": "2018-07-30T11:45:00" }
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"projectId": 12345,
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:15:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "21"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2018-07-30T09:20:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2018-07-30T09:45:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2018-07-30T11:45:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
}
}
}
Example request with external ID
PUT /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"departureGate": { "value": "21" },
"boardingTime": { "value": "2018-07-30T09:20:00" },
"departureTime": { "value": "2018-07-30T09:45:00" },
"arrivalTime": { "value": "2018-07-30T11:45:00" }
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"projectId": 12345,
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:15:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "21"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2018-07-30T09:20:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2018-07-30T09:45:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2018-07-30T11:45:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
}
}
}
PUT /v1/flights/project/id/project123ExtId/id/flight123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"departureGate": { "value": "21" },
"boardingTime": { "value": "2018-07-30T09:20:00" },
"departureTime": { "value": "2018-07-30T09:45:00" },
"arrivalTime": { "value": "2018-07-30T11:45:00" }
}
}
Response with external ID
PUT /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"departureGate": { "value": "21" },
"boardingTime": { "value": "2018-07-30T09:20:00" },
"departureTime": { "value": "2018-07-30T09:45:00" },
"arrivalTime": { "value": "2018-07-30T11:45:00" }
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"projectId": 12345,
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:15:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "21"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2018-07-30T09:20:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2018-07-30T09:45:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2018-07-30T11:45:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
}
}
}
PUT /v1/flights/project/id/project123ExtId/id/flight123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"departureGate": { "value": "21" },
"boardingTime": { "value": "2018-07-30T09:20:00" },
"departureTime": { "value": "2018-07-30T09:45:00" },
"arrivalTime": { "value": "2018-07-30T11:45:00" }
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId": 1234,
"flightExternalId": "flight123ExtId",
"projectId": 12345,
"projectExternalId": "project123ExtId",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:15:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "21"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2018-07-30T09:20:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2018-07-30T09:45:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2018-07-30T11:45:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
}
}
}
Update any of the keys provided in the fields object of a Flight Request. Provide only the fields you want to update; any fields that you omit from the payload remain unchanged.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the flight belongs to. For External IDs, format the
{projectId}asid/{projectExternalId}. - flightId integerREQUIREDThe flight you want to get, update, or delete. For External IDs, format the
{flightId}asid/{flightExternalId}.
Request body:
Content-Type:
application/jsonA complete flight request object.
The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.
Responses
200
A successful request returns the complete, updated flight object and the
flightIdandflightExternalId(if applicable) values, so you can reference the updated flight in later operations.Response body:
- Content-Type:
application/jsonA complete flight response, including identifiers to reference the flight and the fields defined within the flight.
Delete flight
DELETE /flights/project/{projectId}/{flightId}
Example request
DELETE /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external ID
DELETE /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
DELETE /v1/flights/project/id/project123ExtId/id/flight123ExtId HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
DELETE /v1/flights/project/12345/1234 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
DELETE /v1/flights/project/id/project123ExtId/id/flight123ExtId HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Deletes the specified flight.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the flight belongs to. For External IDs, format the
{projectId}asid/{projectExternalId}. - flightId integerREQUIREDThe flight you want to get, update, or delete. For External IDs, format the
{flightId}asid/{flightExternalId}.
Responses
200
The flight was deleted.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ok boolean
If true, the operation completed successfully.
List pass groups for a flight
GET /flights/project/{projectId}/{flightId}/passGroups
Example request
GET /v1/flights/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/flights/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId" : 1234,
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
Example request with external ID
GET /v1/flights/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId" : 1234,
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
GET /v1/flights/project/id/67890/id/4567/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Response with external ID
GET /v1/flights/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId" : 1234,
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
GET /v1/flights/project/id/67890/id/4567/passGroups HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightExternalId" : 4567,
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
Returns a list of pass groups associated with a flight.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the flight belongs to. For External IDs, format the
{projectId}asid/{projectExternalId}. - flightId integerREQUIREDThe flight you want modify groups for. For External IDs, format the
{flightId}asid/{flightExternalId}.
Responses
200
Returns a list of pass groups that a flight is associated with.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- flightId integer
The ID of the flight in the request.
- passGroups array[string]
An array of the pass groups that the flight belongs to.
400
Missing fields or malformed input.
404
The flight or project cannot be found.
Add flight to a pass group
POST /flights/project/{projectId}/{flightId}/passGroups
Example request
POST /v1/flights/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
Response
POST /v1/flights/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId" : 1234,
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
Example request with external ID
POST /v1/flights/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId" : 1234,
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
POST /v1/flights/project/id/67890/id/4567/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
Response with external ID
POST /v1/flights/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightId" : 1234,
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
POST /v1/flights/project/id/67890/id/4567/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"flightExternalId" : "4567",
"passGroups" :["sfo-pdx-20180730", "pdx-yvr-20180730"]
}
Add a flight to a pass group. You can target the group to make changes to multiple flights.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the flight belongs to. For External IDs, format the
{projectId}asid/{projectExternalId}. - flightId integerREQUIREDThe flight you want modify groups for. For External IDs, format the
{flightId}asid/{flightExternalId}.
Request body:
Content-Type:
OBJECT PROPERTIESapplication/json- passGroups array[string]
An array of pass groups that you want to create and add a flight to. If a pass group (string) in the array already exists, it is ignored.
Responses
200
At least one pass group in the
passGroupsarray was created.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- flightId integer
The Airship flight ID for the flight added to the pass group.
- passGroups array[string]
An array of pass groups that the flight was added to.
400
Missing or malformed input.
404
The flight or project cannot be found.
Remove flight from pass group
DELETE /flights/project/{projectId}/{flightId}/passGroups/{passGroup}
Example request
DELETE /v1/flights/project/12345/1234/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Example request with external ID
DELETE /v1/flights/project/12345/1234/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
DELETE /v1/flights/project/id/67890/id/4567/passGroups/sfo-pdx-20180730 HTTP/1.1
Authorization: Basic <authorization string>
Removes a flight from a pass group. The group specified in the path will no longer appear in the flight’s passGroups array, nor will you be able to make changes to the flight by targeting the pass group.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the flight belongs to. Use either the Airship-generated project ID or the external ID. For External IDs, format the
{projectId}asid/{projectExternalId}. - flightId integerREQUIREDThe flight you want modify groups for. Use either the Airship-generated flight ID or the external ID for the flight. For External IDs, format the
{flightId}asid/{flightExternalId}. - passGroup stringREQUIREDThe pass group you want to remove the flight from.
Responses
200
The flight was successfully removed from the pass group.
400
The project, flight, or pass group was not found.
Events
Create and store event information for use with event tickets. When creating event tickets, you can reference an event, automatically populating event information on the pass. By storing and referencing event information independently of your passes, you can update a single event, automatically pushing an update to all passes referencing it.
Create event with external ID
POST /events/project/id/{projectExternalId}/id/{eventExternalId}
Example request
POST /v1/events/project/id/project123ExtId/id/event123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"label": "Event",
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"label": "Venue",
"value": "AT&T Park"
},
"venueAddress": {
"label": "Address",
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T08:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T09:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T11:00:00"
}
}
}
Create an event with 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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectExternalId stringREQUIREDThe external ID of the project you want to create the event in or of the project the existing event belongs to.
- eventExternalId stringREQUIREDA custom identifier for an event. This is the event you want to create, get, modify, or delete.
Request body:
Content-Type:
application/jsonRepresents an event scheduled at a specific time and venue.
Responses
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:
- Content-Type:
application/jsonAn event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.
Create event
POST /events/project/{projectId}
Example request
POST /v1/events/project/12345 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": { "value": "LA Dodgers at SF Giants" },
"venueTitle": { "value": "AT&T Park" },
"venueAddress": { "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107" },
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T08:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T09:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T11:00:00"
}
}
}
Response
POST /v1/events/project/12345 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": { "value": "LA Dodgers at SF Giants" },
"venueTitle": { "value": "AT&T Park" },
"venueAddress": { "value": "24 Willie Mays Plaza\nSan Francisco, CA 94107" },
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T08:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T09:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T11:00:00"
}
}
}
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"passGroups": ["giants_2019-09-25"],
"eventId": 1234,
"projectId": 12345,
"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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project you want to create the event in.
Request body:
Content-Type:
application/jsonRepresents an event scheduled at a specific time and venue.
Responses
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:
- Content-Type:
application/jsonAn event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.
Update events in a pass group
PUT /events/project/{projectId}/passGroups/{passGroup}
Example request
PUT /v1/events/project/myFavProject/passGroups/giants_2019-09-25 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"venueTitle": {
"value": "Oracle Park"
}
}
}
Example request with external ID
PUT /v1/events/project/myFavProject/passGroups/giants_2019-09-25 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"venueTitle": {
"value": "Oracle Park"
}
}
}
PUT /v1/events/project/id/myFavProject/passGroups/giants_2019-09-25 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"venueTitle": {
"value": "Oracle Park"
}
}
}
Response
PUT /v1/events/project/myFavProject/passGroups/giants_2019-09-25 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"venueTitle": {
"value": "Oracle Park"
}
}
}
PUT /v1/events/project/id/myFavProject/passGroups/giants_2019-09-25 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"venueTitle": {
"value": "Oracle Park"
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"groupName" : "giants_2019-09-25",
"events" : [
{
"eventTicketId" : 123
},
{
"eventTicketId" : 456
}
]
}
Update all of the events in a pass group.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the event belongs to. For External IDs, format the
{projectId}asid/{projectExternalId}. - passGroup integerREQUIREDThe pass group that you want to modify.
Request body:
Update fields common to multiple events.
Content-Type:
OBJECT PROPERTIESapplication/json- fields object
Provide only the keys that you want to update from
fieldsobject of an Event Request; any fields that you omit from the payload remain unchanged.
Responses
200
The update was successful.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- events array[object]
Lists the events updated as a part of this pass group.
- groupName string
The pass group that you updated in this request.
400
The request was malformed.
404
The project ID or pass group was not found.
Get event
GET /events/project/{projectId}/{eventId}
Example request
GET /v1/events/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/events/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"projectId": 12345,
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:12:32Z",
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"label": "Event",
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"label": "Venue",
"value": "AT&T Park"
},
"venueAddress": {
"label": "Address",
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T09:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T10:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T12:00:00"
}
}
}
Example request with external ID
GET /v1/events/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"projectId": 12345,
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:12:32Z",
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"label": "Event",
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"label": "Venue",
"value": "AT&T Park"
},
"venueAddress": {
"label": "Address",
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T09:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T10:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T12:00:00"
}
}
}
GET /v1/events/project/id/project123ExtId/id/event123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response with external ID
GET /v1/events/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"projectId": 12345,
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:12:32Z",
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"label": "Event",
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"label": "Venue",
"value": "AT&T Park"
},
"venueAddress": {
"label": "Address",
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T09:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T10:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T12:00:00"
}
}
}
GET /v1/events/project/id/project123ExtId/id/event123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"eventExternalId": "event123ExtId",
"projectId": 12345,
"projectExternalId": "project123ExtId",
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:12:32Z",
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"label": "Event",
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"label": "Venue",
"value": "AT&T Park"
},
"venueAddress": {
"label": "Address",
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T09:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T10:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T12:00:00"
}
}
}
Returns information about a single event.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the event belongs to. For External IDs, format the
{projectId}asid/{projectExternalId}. - eventId integerREQUIREDThe event you want to get, update, or delete. For External IDs, format the
{eventId}asid/{eventExternalId}.
Responses
200
A successful request returns the
eventIdandeventExternalId(if applicable) values, so you can reference the event in later operations.Response body:
- Content-Type:
application/jsonAn event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.
Update event
PUT /events/project/{projectId}/{eventId}
Example request
PUT /v1/events/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"doorsOpen": { "value": "2019-09-25T09:35:00" },
"startTime": { "value": "2019-09-25T10:00:00" },
"endTime": { "value": "2019-09-25T12:00:00" }
}
}
Response
PUT /v1/events/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"doorsOpen": { "value": "2019-09-25T09:35:00" },
"startTime": { "value": "2019-09-25T10:00:00" },
"endTime": { "value": "2019-09-25T12:00:00" }
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"projectId": 12345,
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:12:32Z",
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"value": "AT&T Park"
},
"venueAddress": {
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T09:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T10:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T12:00:00"
}
}
}
Example request with external ID
PUT /v1/events/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"doorsOpen": { "value": "2019-09-25T09:35:00" },
"startTime": { "value": "2019-09-25T10:00:00" },
"endTime": { "value": "2019-09-25T12:00:00" }
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"projectId": 12345,
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:12:32Z",
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"value": "AT&T Park"
},
"venueAddress": {
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T09:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T10:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T12:00:00"
}
}
}
PUT /v1/events/project/id/project123ExtId/id/event123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"doorsOpen": { "value": "2019-09-25T09:35:00" },
"startTime": { "value": "2019-09-25T10:00:00" },
"endTime": { "value": "2019-09-25T12:00:00" }
}
}
Response with external ID
PUT /v1/events/project/12345/1234 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"doorsOpen": { "value": "2019-09-25T09:35:00" },
"startTime": { "value": "2019-09-25T10:00:00" },
"endTime": { "value": "2019-09-25T12:00:00" }
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"projectId": 12345,
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:12:32Z",
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"value": "AT&T Park"
},
"venueAddress": {
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T09:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T10:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T12:00:00"
}
}
}
PUT /v1/events/project/id/project123ExtId/id/event123ExtId HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"fields": {
"doorsOpen": { "value": "2019-09-25T09:35:00" },
"startTime": { "value": "2019-09-25T10:00:00" },
"endTime": { "value": "2019-09-25T12:00:00" }
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"eventExternalId": "event123ExtId",
"projectId": 12345,
"projectExternalId": "project123ExtId",
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:12:32Z",
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"value": "AT&T Park"
},
"venueAddress": {
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T09:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T10:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T12:00:00"
}
}
}
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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the event belongs to. For External IDs, format the
{projectId}asid/{projectExternalId}. - eventId integerREQUIREDThe event you want to get, update, or delete. For External IDs, format the
{eventId}asid/{eventExternalId}.
Request body:
Content-Type:
OBJECT PROPERTIESapplication/json- fields object
Responses
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:
- Content-Type:
application/jsonAn event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.
Delete event
DELETE /events/project/{projectId}/{eventId}
Example request
DELETE /v1/events/project/12345/1 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Example request with external ID
DELETE /v1/events/project/12345/1 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
DELETE /v1/events/project/id/67890/id/4567 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
DELETE /v1/events/project/12345/1 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
DELETE /v1/events/project/id/67890/id/4567 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{}
Deletes the specified event.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the event belongs to. For External IDs, format the
{projectId}asid/{projectExternalId}. - eventId integerREQUIREDThe event you want to get, update, or delete. For External IDs, format the
{eventId}asid/{eventExternalId}.
Responses
200
The event was deleted.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ok boolean
If true, the operation completed successfully.
List pass groups for event
GET /events/project/{projectId}/{eventId}/passGroups
Example request
GET /v1/events/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Example request with external ID
GET /v1/events/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
GET /v1/events/project/id/project123ExtId/id/event123ExtId/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/events/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
GET /v1/events/project/id/project123ExtId/id/event123ExtId/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventTicketId": 1234,
"passGroups": [
"EVENT_100_LUNCH",
"FLIGHT_100_DINNER"
]
}
Returns a list of pass groups associated with an event.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the event belongs to. Use the Airship-generated project ID or project’s external ID. For External IDs, format the
{projectId}asid/{projectExternalId}. - eventId integerREQUIREDThe event you want modify groups for. For External IDs, format the
{eventId}asid/{eventExternalId}.
Responses
200
Returns a list of pass groups that an event is associated with.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- eventId integer
The Airship-generated ID of the event in the request.
- passGroups array[string]
An array of the pass groups that the event belongs to.
400
Missing fields or malformed input.
404
The event or project cannot be found.
Add event to pass group
POST /events/project/{projectId}/{eventId}/passGroups
Example request
POST /v1/events/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"passGroups": [
"EVENT_100_LUNCH",
"EVENT_100_DINNER"
]
}
Response
POST /v1/events/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"passGroups": [
"EVENT_100_LUNCH",
"EVENT_100_DINNER"
]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"passGroups": [
"EVENT_100_LUNCH",
"EVENT_100_DINNER"
]
}
Example request with external ID
POST /v1/events/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"passGroups": [
"EVENT_100_LUNCH",
"EVENT_100_DINNER"
]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"passGroups": [
"EVENT_100_LUNCH",
"EVENT_100_DINNER"
]
}
POST /v1/events/project/id/67890/id/4567/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"passGroups": [
"EVENT_100_LUNCH",
"EVENT_100_DINNER"
]
}
Response with external ID
POST /v1/events/project/12345/1234/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"passGroups": [
"EVENT_100_LUNCH",
"EVENT_100_DINNER"
]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventId": 1234,
"passGroups": [
"EVENT_100_LUNCH",
"EVENT_100_DINNER"
]
}
POST /v1/events/project/id/67890/id/4567/passGroups HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"passGroups": [
"EVENT_100_LUNCH",
"EVENT_100_DINNER"
]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"eventExternalId" : "4567",
"passGroups" :["EVENT_100_LUNCH","EVENT_100_DINNER"]
}
Add an event to a pass group. You can target the group to make changes to multiple events.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the event belongs to. Use the Airship-generated project ID or project’s external ID. For External IDs, format the
{projectId}asid/{projectExternalId}. - eventId integerREQUIREDThe event you want modify groups for. For External IDs, format the
{eventId}asid/{eventExternalId}.
Request body:
Content-Type:
OBJECT PROPERTIESapplication/json- passGroups array[string]
An array of pass groups that you want to create and add an event to. If an event already belongs to a pass group (string) in the array, it is ignored.
Responses
200
The event was successfully added to one or more
passGroups.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- eventId integer
The event added to the pass group.
- passGroups array[string]
An array of pass groups that the event was added to.
400
Missing or malformed input.
404
The event or project cannot be found.
Remove event from pass group
DELETE /events/project/{projectId}/{eventId}/passGroups/{passGroup}
Example request
DELETE /v1/events/project/12345/1234/passGroups/EVENT_100_LUNCH HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Example request with external ID
DELETE /v1/events/project/12345/1234/passGroups/EVENT_100_LUNCH HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
DELETE /v1/events/project/id/project123ExtId/id/event123ExtId/passGroups/EVENT_100_LUNCH HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
DELETE /v1/events/project/12345/1234/passGroups/EVENT_100_LUNCH HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
DELETE /v1/events/project/id/project123ExtId/id/event123ExtId/passGroups/EVENT_100_LUNCH HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{}
Removes an event from a pass group. The group specified in the path will no longer appear in the event’s passGroups array, nor will you be able to make changes to the event by targeting the pass group.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the event belongs to. Use either the Airship-generated project ID or the external ID. For External IDs, format the
{projectId}asid/{projectExternalId}. - eventId integerREQUIREDThe event you want modify groups for. Use either the Airship-generated event ID or the external ID for the event. For External IDs, format the
{eventId}asid/{eventExternalId}. - passGroup stringREQUIREDThe pass group you want to remove the event from.
Responses
200
The event was removed from the pass group.
400
The project, event, or pass group was not found.
Callbacks
Wallet callbacks provide a pass event notification, e.g., pass install or uninstall, using webhooks.
Get callback specification
GET /project/{projectId}/settings/callback
Example request
GET /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Response
GET /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
HTTP/1.1 200 OK
Content-Type: application/json
{
"baseUrl": "https://www.remotehost.example.com/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
Return the callback specification for a project.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
Responses
200
A successful call returns the callback specification.
Response body:
- Content-Type:
application/jsonUsed for both requests and responses to
OBJECT PROPERTIES/callbackendpoints.- baseUrl string
The URL of your webhook/callback server.
- headers object
Contains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Airship appends
content-type: application/jsonand sends a JSON payload.
Create callback specification
POST /project/{projectId}/settings/callback
Example request
POST /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
{
"baseUrl": "https://www.remotehost.example.com/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
Response
POST /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
{
"baseUrl": "https://www.remotehost.example.com/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"baseUrl": "https://www.remotehost.example.com/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
Register a callback specification, which includes the remote URL and any HTTP headers required by the remote URL.
Your callback server should expect to receive callbacks at up to three endpoints:
{baseUrl}/v1/pass/install— Receives a callback when your audience installs passes.{baseUrl}/v1/pass/uninstall— Receives a callback when your audience uninstalls passes.{baseUrl}/v1/pass/{passId}/personalize— Receives a callback with a personalization object when your audience personalizes a Loyalty pass. You must add personalization requirements to Apple templates before users can personalize passes created from them.
See Wallet callbacks for more information.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
Request body:
Content-Type:
application/jsonCallback SpecificationUsed for both requests and responses to
OBJECT PROPERTIES/callbackendpoints.- baseUrl string
The URL of your webhook/callback server.
- headers object
Contains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Airship appends
content-type: application/jsonand sends a JSON payload.
Responses
200
A successful call returns the callback specification.
Response body:
- Content-Type:
application/jsonUsed for both requests and responses to
OBJECT PROPERTIES/callbackendpoints.- baseUrl string
The URL of your webhook/callback server.
- headers object
Contains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Airship appends
content-type: application/jsonand sends a JSON payload.
Update callback specification
PUT /project/{projectId}/settings/callback
Example request
PUT /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
{
"baseUrl": "https://www.remotehost.example.com/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
Response
PUT /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
{
"baseUrl": "https://www.remotehost.example.com/callbacks",
"headers": {
"Authorization": "Basic dGVzdEB0ZXN0LmNvbTp0ZXN0",
"Content-Type": "application/json"
}
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"baseUrl": "https://www.remotehost.example.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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
Request body:
Content-Type:
application/jsonCallback SpecificationUsed for both requests and responses to
OBJECT PROPERTIES/callbackendpoints.- baseUrl string
The URL of your webhook/callback server.
- headers object
Contains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Airship appends
content-type: application/jsonand sends a JSON payload.
Responses
200
A successful call returns the callback specification.
Response body:
- Content-Type:
application/jsonUsed for both requests and responses to
OBJECT PROPERTIES/callbackendpoints.- baseUrl string
The URL of your webhook/callback server.
- headers object
Contains headers required by your webhook/callback server, including authorization, content-type, etc.
By default, Airship appends
content-type: application/jsonand sends a JSON payload.
Delete callback specification
DELETE /project/{projectId}/settings/callback
Example request
DELETE /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
Response
DELETE /v1/project/12345/settings/callback HTTP/1.1
Authorization: Basic <Base64 key>
HTTP/1.1 204 No Content
Delete a registered callback specification. Because a project only uses a single callback specification, you specify the projectId only.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe ID of the project.
Responses
204
A successful request returns no content.
Tickets
Return status information about tickets or the server itself. For operations
that cannot complete immediately, the system returns a ticketId. You can look
up this ticketId to determine the true status of the operation.
Check system status
GET /system/status
Example request
GET /v1/system/status HTTP/1.1
Response
GET /v1/system/status HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"Hello": "World"
}
Ensure that you can make a connection to the Wallet API.
Responses
200
You have successfully established a connection with the server.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- Hello string
A “Hello World” response tells you that everything is Ok.
Possible values:
World
Get ticket status
GET /ticket/{ticketId}
Example request
GET /v1/ticket/123 HTTP/1.1
Authorization: Basic <Base64 key>
Response
GET /v1/ticket/123 HTTP/1.1
Authorization: Basic <Base64 key>
HTTP/1.1 200 OK
Content-Type: application/json
{
"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:
Path parameters:
- ticketId stringREQUIREDThe ticket you want to know the status of.
Responses
200
Returns the status of a ticket.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ID integer
The identifier of the ticket.
- children object
- createdAt string
The date and time when the item was created.
- status string
The status of the ticket.
Statistics
Get pass creation, installation, and uninstallation counts for projects and templates.
Endpoints for /activity report net total activities, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, a response will show two passes installed and one pass removed. Endpoints for /stats will not count repeated actions from the same user.
Pass statistics with external ID
GET /pass/id/{externalId}/stats
Example request
GET /v1/pass/id/my_pass/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/pass/id/my_pass/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"total": 1,
"installed": 1,
"uninstalled": 0,
"templates": [
{
"id": 5350,
"installed": 1,
"uninstalled": 0
}
]
}
Returns statistics for a pass with an external ID, including the total number of installs and uninstalls. The response payload lists the internal Wallet ID for the template rather than the external ID.
This endpoint does not count repeated actions by the same user.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- externalId integerREQUIREDThe external ID of the pass you want to return statistics for.
Responses
200
Returns a summary of statistics for the pass.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- installed integer
The number of installed passes with this external ID.
- templates array[object]
The individual pass statistics for each template used to create passes with this external ID. Each object in the array represents a template.
- total integer
A count of the total number of passes with this external ID.
- uninstalled integer
The number of uninstalled passes with this external ID.
Project activity
GET /project/{projectId}/activity
Example request
GET /v1/project/12345/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external ID
GET /v1/project/12345/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/project/id/myExternalProject/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/project/12345/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/project/id/myExternalProject/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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 daily pass activity for a given project ID. You can also add start and end date parameters in the path to return activity between two dates, in the format /template/{templateId}/activity/2018-08-10/2018-10-01.
If your request did not specify a date range, the response includes all activity, organized by day, since the template’s createdAt date.
This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe ID of the project you want to return activity for. For External IDs, format the
{projectId}asid/{externalId}.
Responses
200
Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the projects’s
createdAtdate.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- details array[object]
Each object in this array represents pass activity for a single day. Each object represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the object shows two passes installed and one pass removed.
- endDate string
The end date for a statistics report.
- id integer
The ID of the project specified in the path.
- startDate string
The start date for a statistics report.
- summary object
Represents activity for a template or project.
OBJECT PROPERTIES- created integer
The number of passes created.
- installed integer
The number of passes that were installed.
- uninstalled integer
The number of passes that were uninstalled.
Project statistics
GET /project/{projectId}/stats
Example request
GET /v1/project/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external ID
GET /v1/project/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/project/id/ext_54321/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/project/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/project/id/ext_54321/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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 project ID. This endpoint does not count repeated actions by the same user. For External IDs, the response payload lists the internal Wallet ID for the template rather than the external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe ID of the project you want to return statistics for. For External IDs, format the
{projectId}asid/{externalId}.
Responses
200
Returns a summary of pass statistics for every template in the project.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- id integer
The identifier for the project.
- installed integer
The total number of passes from this project that are installed.
- lastUpdated string
The date and time when the item was last updated.
- templates array[object]
Contains statistics for each template belonging to the project.
- total integer
The total number of passes created in the project.
- uninstalled integer
The total number of passes created from this project that are uninstalled.
Tag statistics
GET /tag/{tag}/stats
Example request
GET /v1/tag/my_tag/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/tag/my_tag/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"total": 21,
"installed": 11,
"uninstalled": 0,
"not_been_installed": 0,
"lastUpdated": "2023-06-14T12:45:37.000Z"
}
Returns statistics for a given tag. Tags are typically used for segmentation but can also be useful for reporting. This endpoint does not count repeated actions by the same user.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- tag stringREQUIREDThe tag you want to return statistics for.
Responses
200
Returns an object containing usage information about a tag.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- installed integer
The number of installed passes with the tag.
- lastUpdated string
The date and time when the statistics were generated.
- not_been_installed integer
The number of passes created but not installed.
- total integer
A count of the total number of passes created with the tag.
- uninstalled integer
The number of uninstalled passes with the tag.
Template activity
GET /template/{templateId}/activity
Example request
GET /v1/template/1234/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external ID
GET /v1/template/1234/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/template/id/myExternalId/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/template/1234/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/template/id/myExternalId/activity/2015-08-19/2015-08-20 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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 daily activity of passes created, installed, and uninstalled for a template, specified by template ID. You can also add start and end date parameters in the path to return activity between two dates, in the format /template/id/{externalId}/activity/2018-08-10/2018-10-01.
If your request did not specify a date range, the response includes all activity, organized by day, since the template’s createdAt date.
This endpoint represents net activity, including repeated actions by the same user. For example, if the same user installs, removes, and then adds the same pass again, the report shows two passes installed and one pass removed.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId integerREQUIREDThe ID of the template you want to return activity for. For External IDs, format the
{templateId}asid/{externalId}.
Responses
200
Returns a per-day activity for all days in the time range. If your request did not specify a date range, the response includes all activity, organized by day, since the template’s
createdAtdate.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- details array[object]
Each object in this array represents pass activity for a single day.
- endDate string
The end date for a statistics report.
- id integer
The ID of the template specified in the path.
- startDate string
The start date for a statistics report.
- summary object
Represents activity for a template or project.
OBJECT PROPERTIES- created integer
The number of passes created.
- installed integer
The number of passes that were installed.
- uninstalled integer
The number of passes that were uninstalled.
- vendor string
The device vendor the template is designed for.
Possible values:
Apple,Google
Template statistics
GET /template/{templateId}/stats
Example request
GET /v1/template/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external ID
GET /v1/template/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/template/id/ext_54321/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/template/12345/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/template/id/ext_54321/stats HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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. For External IDs, 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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId integerREQUIREDThe ID of the template you want to return statistics for. For External IDs, format the
{templateId}asid/{externalId}.
Responses
200
Returns an object containing usage information about a template.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- id integer
The template specified in the request.
- installed integer
The number of installed passes based on this template.
- lastUpdated string
The date and time when the template was last updated.
- total integer
A count of the total number of passes created from the template.
- uninstalled integer
The number of uninstalled passes based on this template.
- vendor string
The device vendor the template is designed for.
Possible values:
Apple,Google
Push Notifications
Send a push notification to end users who have iOS or Android passes installed, letting them know information has changed. By notifying users, they will receive an alert as well as an update to the back of the pass showing the most recent notification.
Send notification by pass with external ID
POST /pass/template/{templateId}/id/{passExternalId}/notify
Example request
POST /v1/pass/template/12345/id/my_custom_pass_id/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
Response
POST /v1/pass/template/12345/id/my_custom_pass_id/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 1234
}
Send a notification to a pass. Delivers lock screen notification through the wallet app and presents notification field and message on the back of the pass.
Security:
Path parameters:
- templateId stringREQUIREDThe template ID for the pass you want to send or delete notification for.
- passExternalId stringREQUIREDThe custom identifier of the pass you want to send or delete notification for.
Request body:
Send notification to a pass.
Content-Type:
application/jsonPass Notification RequestAn object for sending a custom pass notification message.
OBJECT PROPERTIES- label string
Optional header for the message.
- value stringREQUIRED
The body of the notification message.
Responses
200
Notification is being sent. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The pass does not exist.
Delete notification by pass with external ID
DELETE /pass/template/{templateId}/id/{passExternalId}/notify
Example request
DELETE /v1/pass/template/12345/id/my_custom_pass_id/notify HTTP/1.1
Authorization: Basic <Base64 key>
Response
DELETE /v1/pass/template/12345/id/my_custom_pass_id/notify HTTP/1.1
Authorization: Basic <Base64 key>
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 12345
}
Removes notification field and message from the back of the pass.
Security:
Path parameters:
- templateId stringREQUIREDThe template ID for the pass you want to send or delete notification for.
- passExternalId stringREQUIREDThe custom identifier of the pass you want to send or delete notification for.
Responses
200
Notification is being deleted. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The pass does not exist.
Send notification by pass
POST /pass/{passId}/notify
Example request
POST /v1/pass/123/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
Response
POST /v1/pass/123/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 1234
}
Send a notification to a pass. Delivers lock screen notification through the wallet app and presents notification field and message on the back of the pass.
Security:
Path parameters:
- passId stringREQUIREDThe
idof the pass you want send notification to.
Request body:
Send notification to a pass.
Content-Type:
application/jsonPass Notification RequestAn object for sending a custom pass notification message.
OBJECT PROPERTIES- label string
Optional header for the message.
- value stringREQUIRED
The body of the notification message.
Responses
200
Notification is being sent. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The pass does not exist.
Delete notification by pass
DELETE /pass/{passId}/notify
Example request
DELETE /v1/pass/123/notify HTTP/1.1
Authorization: Basic <Base64 key>
Response
DELETE /v1/pass/123/notify HTTP/1.1
Authorization: Basic <Base64 key>
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 12345
}
Removes notification field and message from the back of the pass.
Security:
Path parameters:
- passId stringREQUIREDThe
idof the pass you want send notification to.
Responses
200
Notification is being deleted. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The pass does not exist.
Send notification by segment
POST /segments/{projectId}/{segmentId}/notify
Example request
POST /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a/notify?templateId=6789 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
Response
POST /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a/notify?templateId=6789 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 1234
}
Send a notification to all passes for a segment.
Security:
Query parameters:
- templateId stringREQUIRED
Path parameters:
- projectId stringREQUIREDThe ID of the project you want to send the notification to.
- segmentId stringREQUIREDThe ID of the segment you want to send the notification to.
Request body:
Send notification to segment passes.
Content-Type:
application/jsonPass Notification RequestAn object for sending a custom pass notification message.
OBJECT PROPERTIES- label string
Optional header for the message.
- value stringREQUIRED
The body of the notification message.
Responses
200
Notification is being sent. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The segment does not exist.
Delete notification by segment
DELETE /segments/{projectId}/{segmentId}/notify
Example request
DELETE /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a/notify?templateId=6789 HTTP/1.1
Authorization: Basic <Base64 key>
Response
DELETE /v1/segments/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a/notify?templateId=6789 HTTP/1.1
Authorization: Basic <Base64 key>
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 12345
}
Delete pass notification for specified segment.
Security:
Query parameters:
- templateId string
Path parameters:
- projectId stringREQUIREDThe ID of the project you want to delete the notification for.
- segmentId stringREQUIREDThe ID of the segment you want to delete the notification for.
Responses
200
Notification is being deleted. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The segment does not exist.
Send notification by tag
POST /tag/{tag}/notify
Example request
POST /v1/tag/campaign123/notify?templateId=12345 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
Response
POST /v1/tag/campaign123/notify?templateId=12345 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 1234
}
Send notification to all passes associated with the specified tag.
Security:
Query parameters:
- templateId stringREQUIREDThe template ID associated with the passes you want to send or delete notification for.
Path parameters:
- tag stringREQUIREDThe tag associated with the passes you want to send or delete notification for.
Request body:
Send notification to tagged passes.
Content-Type:
application/jsonPass Notification RequestAn object for sending a custom pass notification message.
OBJECT PROPERTIES- label string
Optional header for the message.
- value stringREQUIRED
The body of the notification message.
Responses
200
Notification is being sent. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The tag does not exist.
Delete notification by tag
DELETE /tag/{tag}/notify
Example request
DELETE /v1/tag/campaign123/notify?templateId=12345 HTTP/1.1
Authorization: Basic <Base64 key>
Response
DELETE /v1/tag/campaign123/notify?templateId=12345 HTTP/1.1
Authorization: Basic <Base64 key>
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 12345
}
Delete notification for passes associated with the specified tag.
Security:
Query parameters:
- templateId stringREQUIREDThe template ID associated with the passes you want to send or delete notification for.
Path parameters:
- tag stringREQUIREDThe tag associated with the passes you want to send or delete notification for.
Responses
200
Notification is being deleted. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The tag does not exist.
Send notification by template
POST /template/{templateId}/notify
Example request
POST /v1/template/123/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
Example request with external ID
POST /v1/template/123/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
POST /v1/template/id/12345/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
Response
POST /v1/template/123/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
POST /v1/template/id/12345/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
{
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 1234
}
Send a notification to all passes belonging to the template.
Security:
Path parameters:
- templateId stringREQUIREDThe
idof the template you want to send or delete notification for. For External IDs, format the{templateId}asid/{templateExternalId}.
Request body:
Send notification to template passes.
Content-Type:
application/jsonPass Notification RequestAn object for sending a custom pass notification message.
OBJECT PROPERTIES- label string
Optional header for the message.
- value stringREQUIRED
The body of the notification message.
Responses
200
Notification is being sent. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The pass does not exist.
Delete notification by template
DELETE /template/{templateId}/notify
Example request
DELETE /v1/template/123/notify HTTP/1.1
Authorization: Basic <Base64 key>
Example request with external ID
DELETE /v1/template/123/notify HTTP/1.1
Authorization: Basic <Base64 key>
DELETE /v1/template/id/12345/notify HTTP/1.1
Authorization: Basic <Base64 key>
Response
DELETE /v1/template/123/notify HTTP/1.1
Authorization: Basic <Base64 key>
DELETE /v1/template/id/12345/notify HTTP/1.1
Authorization: Basic <Base64 key>
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 12345
}
Delete pass notification for specified template passes.
Security:
Path parameters:
- templateId stringREQUIREDThe
idof the template you want to send or delete notification for. For External IDs, format the{templateId}asid/{templateExternalId}.
Responses
200
Notification is being deleted. The response contains a
ticketIdthat you can use to look up the operation.Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
An identifier for this operation.
404
The template does not exist.
Certificates
These endpoints supports Apple certificates only. Google certificates can be managed via the UI.
List certificates
GET /certificates
Example request
GET /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"certificates": [
{
"id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
"vendor": "Apple",
"baseName": "pass.com.company.sample.alpha",
"teamIdentifier": "PGJV57GD94",
"nfcSupport": true,
"enabled": true,
"default": false,
"createdAt": "2022-04-05T03:22:47.000Z",
"updatedAt": "2022-04-05T03:22:47.000Z",
"validityEnd": "2022-12-03T04:45:52.000Z",
"validityStart": "2021-11-03T03:45:53.000Z",
"expired": true
}
]
}
Response
GET /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"certificates": [
{
"id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
"vendor": "Apple",
"baseName": "pass.com.company.sample.alpha",
"teamIdentifier": "PGJV57GD94",
"nfcSupport": true,
"enabled": true,
"default": false,
"createdAt": "2022-04-05T03:22:47.000Z",
"updatedAt": "2022-04-05T03:22:47.000Z",
"validityEnd": "2022-12-03T04:45:52.000Z",
"validityStart": "2021-11-03T03:45:53.000Z",
"expired": true
}
]
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"nextPage": "https://wallet.urbanairship.com/v1/certificates/list/?page=11&pageSize=10",
"count": 2,
"pagination": {
"order": "name",
"page": 1,
"start": 0,
"direction": "DESC",
"pageSize": 10
},
"certificates":[
{
"id": "40adce15-5c52-479d-8620-54c21cd851a6",
"vendor": "Apple",
"baseName": "pass.com.myName.test",
"name": "editable name",
"comment": "something about this cert",
"teamIdentifier": "9M8MY376H5",
"nfcSupport": false,
"enabled": false,
"createdAt": "2018-05-26T23:23:21Z",
"updatedAt": "2019-05-26T22:23:21Z",
"expired": false,
"validityStart": "2018-05-26T23:45:00Z",
"validityEnd": "2019-05-26T23:45:00Z",
"templates": [
{"id": 123,"name": "templateName1"},
{"id": 221,"name": "templateName2"}
]
},
{
"id": "12adce15-5c52-479d-8620-54c21cd851aa",
"vendor": "Apple",
"baseName", "pass.wallet.myName.anotherTest",
"name": "editable name1",
"comment": "a plain text description of this cert",
"teamIdentifier": "OGKV57GD95",
"nfcSupport": true,
"enabled": false,
"default": false,
"createdAt": "2018-04-26T23:23:21Z",
"updatedAt": "2019-04-27T17:22:00Z",
"expired": false,
"validityStart": "2018-05-26T23:45:00Z",
"validityEnd": "2019-05-26T23:45:00Z",
"templates": [
{"id": 123, "name": "templateName1"},
{"id": 221, "name": "templateName2"}
]
}
]
}
Returns a list of certificates, including an array of templates that use the certificate.
Query parameters:
- vendor stringThe vendor of certificate you want to return.
Possible values:
Apple - enabled booleanIndicates whether or not the certificate is enabled.
- order stringIndicates the field to order results by.
- page integerIndicates the page of results to return.
- pageSize integerIndicates the number of results per page.
- direction stringIndicates the direction in which to return results.
Possible values:
ASC,DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2 - Content-Type stringREQUIRED
Possible values:
application/json; charset=utf-8
Responses
200
Returns an array of certificates.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- certificates array
- count integer
The number of results on the current page.
- nextPage string
The url for the next page of results.
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
Add new certificate
POST /certificates
Example request
POST /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"vendor": "Apple",
"name": "editable name",
"certificate": "NTUtNDc2Ni1hMzI4LWEwOGU3YWI2ZDk3Mg==",
"comment": "something about this cert",
"enabled": true,
"default": false,
"password": "secret"
}
Response
POST /v1/certificates HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"vendor": "Apple",
"name": "editable name",
"certificate": "NTUtNDc2Ni1hMzI4LWEwOGU3YWI2ZDk3Mg==",
"comment": "something about this cert",
"enabled": true,
"default": false,
"password": "secret"
}
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.pemcat 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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Request body:
Content-Type:
application/json
Responses
201
Returns the created certificate and new read only fields.
Response body:
- Content-Type:
application/json
Get certificate
GET /certificates/{id}
Example request
GET /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
GET /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
"vendor": "Apple",
"baseName": "pass.com.company.sample.alpha",
"teamIdentifier": "PGJV57GD94",
"nfcSupport": true,
"enabled": true,
"default": false,
"createdAt": "2022-04-05T03:22:47.000Z",
"updatedAt": "2022-04-05T03:22:47.000Z",
"validityStart": "2021-11-03T03:45:53.000Z",
"validityEnd": "2022-12-03T04:45:52.000Z",
"expired": true
}
Returns information about a certificate, including an array of templates that use the certificate.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe ID of the certificate you want to perform operations against.
Responses
200
Returns information about the certificate specified in the request
Response body:
- Content-Type:
application/json
Update certificate
PUT /certificates/{id}
Example request
PUT /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"certificate": "<Certificate PEM BASE94 content goes here>"
}
Response
PUT /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"certificate": "<Certificate PEM BASE94 content goes here>"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9",
"vendor": "Apple",
"baseName": "pass.com.urbanairship.sample.alpha",
"teamIdentifier": "PGJV57GD94",
"nfcSupport": true,
"enabled": true,
"createdAt": "2022-04-05T03:22:47.000Z",
"updatedAt": "2024-02-06T19:01:37.415Z",
"validityStart": "2022-12-02T22:39:50.000Z",
"validityEnd": "2024-01-01T22:39:49.000Z",
"expired": true
}
Updates a certificate. Note the following behaviors:
- The following fields can be updated directly:
enabled,default,comment, andname. - 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
updatedAtwill change with each update. - The field
createdAtcannot 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 headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe ID of the certificate you want to perform operations against.
Request body:
Content-Type:
application/json
Responses
200
Returns the created certificate and new read only fields.
Response body:
- Content-Type:
application/json
Remove certificate
DELETE /certificates/{id}
Example request
DELETE /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
Response
DELETE /v1/certificates/9d9d28f2-4f63-44fc-82d2-ba101d2c4fd9 HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2
HTTP/1.1 204 No Content
Removes a certificate from the system.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- id stringREQUIREDThe ID of the certificate you want to perform operations against.
Responses
204
A successful request returns no content.
Event Passes
List event passes
GET /events/project/{projectId}/{eventId}/passes
Example request
GET /v1/events/project/12345/1234/passes HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/events/project/12345/1234/passes HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 616,
"templateId": 1000057,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/616/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da0b8",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "installed",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 610,
"templateId": 1000083,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/610/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e216",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
List passes for an event.
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.
Possible values:
installed,uninstalled,been_installed,not_been_installed - pageSize integerThe number of passes per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the event belongs to.
- eventId integerREQUIREDThe event you want to get passes for.
Responses
200
A successful request returns a paged list of passes for a particular event.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The total number of passes associated with a event
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes array[object]
The metadata for passes associated with the event. Each object in the array represents a pass.
404
The event ID does not exist.
Flight Passes
List flight passes
GET /flights/project/{projectId}/{flightId}/passes
Example request
GET /v1/flights/project/12345/1234/passes HTTP/1.1
Authorization: Basic <authorization string>
Response
GET /v1/flights/project/12345/1234/passes HTTP/1.1
Authorization: Basic <authorization string>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 600,
"templateId": 100005,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/600/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da023",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "installed",
"installedAt": "2023-04-19T06:19:02.000Z",
"platform": "android"
},
{
"id": 601,
"templateId": 100008,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/601/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e212",
"createdAt": "2023-05-05T17:55:23.000Z",
"updatedAt": "2023-05-06T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T19:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}
List passes for Flight.
Security:
Query parameters:
- status string
Find only passes matching the installation status.
installed— passes currently installed.uninstalled— passes that have been uninstalled.been_installed— passes that have been either installed or uninstalled.not_been_installed— passes that have never been installed.
Possible values:
installed,uninstalled,been_installed,not_been_installed - pageSize integerThe number of passes per page. Defaults to 10.
Default:
10 - page integerThe page of results you want to retrieve, starting at 1.
Default:
1 - order stringThe order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtDefault:
id - direction stringDetermines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESCDefault:
DESC
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId integerREQUIREDThe project that the flight belongs to.
- flightId integerREQUIREDThe flight you want to get passes for.
Responses
200
A successful request returns a paged list of passes for a particular flight.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The total number of passes associated with a flight
- pagination object<Pagination object>
Contains information about pagination, according to your query parameters.
- passes array[object]
The metadata for passes associated with the flight. Each object in the array represents a pass.
404
The flight ID does not exist.
Apple Passes Only
Download multiple Apple Wallet Passes in a single .pkpass file
GET /pass/download
Example request
GET /v1/pass/download?passIds=123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Download Apple Wallet passes in a single .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes. See also Download multiple Apple Wallet Passes in a single .pkpass file with external ID.
See Apple’s developer documentation for information about .pkpass files and contents.
Query parameters:
- passIds stringREQUIREDOne or more pass IDs (comma separated) that should be included in the download.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
Returns the .pkpass file as a .zip extension.
View Apple Wallet JSON with external ID
GET /pass/id/{passExternalId}/viewJSONPass
Example request
GET /v1/pass/id/123/viewJSONPass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/pass/id/123/viewJSONPass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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.example.com"
},
{
"key": "back0",
"label": "Built with Airship Reach",
"value": "Find out more and create your own passes at https://wallet.urbanairship.com\n\nAirship, Inc.,1417 NW Everett St., Portland, OR 97209 800.720.2098 support@urbanairship.com"
}
],
"primaryFields":[
{
"key": "Program Name",
"label": "Airship",
"value": "Program Name",
"textAlignment": "PKTextAlignmentNatural"
}
],
"headerFields":[
{
"key": "Points",
"label": "Points",
"value": 1234.0,
"textAlignment": "PKTextAlignmentNatural",
"numberStyle": "PKNumberStyleDecimal"
}
],
"secondaryFields":[
{
"key": "Tier",
"label": "Tier",
"value": 2.0,
"textAlignment": "PKTextAlignmentNatural",
"numberStyle": "PKNumberStyleDecimal"
},
{
"key": "Tier Name",
"label": "Tier Name",
"value": "Silver",
"textAlignment": "PKTextAlignmentNatural"
},
{
"key": "Member Name",
"label": "Member Name",
"value": "First Last",
"textAlignment": "PKTextAlignmentNatural"
}
]
},
"organizationName": "Airship",
"backgroundColor": "rgb(0,147,201)",
"labelColor": "rgb(24,86,148)",
"authenticationToken": "df897c90-5a9b-48dd-a4b4-8020486811b7",
"serialNumber": "bcc7cdae-e491-4e36-a95e-9758e31549aa",
"barcode": {
"message": "123456789",
"messageEncoding": "iso-8859-1",
"format": "PKBarcodeFormatPDF417",
"altText": "123456789"
},
"teamIdentifier": "MN52833CEX",
"formatVersion": 1,
"webServiceURL": "https:\/\/wallet-api.urbanairship.com\/apple",
"description": "Template 1",
"foregroundColor": "rgb(255,255,255)"
}
View the JSON of an Apple Wallet Pass. The Airship request payload is different from the JSON payload contained in an Apple Wallet pass. You can use this endpoint to view the JSON payload as passed to Apple Wallet.
See Apple’s developer documentation for information about Apple Wallet payloads.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- passExternalId stringREQUIREDThe custom identifier of the pass you want to return Apple Wallet JSON for.
Responses
200
Returns JSON as passed to Apple Wallet.
Response body:
- Content-Type:
application/jsonType:
object
Download multiple Apple Wallet Passes with external IDs in a single .pkpass file
GET /pass/template/{templateId}/download
Example request
GET /v1/pass/template/123/download?exids=mypass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Example request with external template ID
GET /v1/pass/template/123/download?exids=mypass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
GET /v1/pass/template/id/1234/download?exids=mypass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Download Apple Wallet passes with external IDs in a single .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes. See also Download multiple Apple Wallet Passes in a single .pkpass file.
See Apple’s developer documentation for information about .pkpass files and contents.
Query parameters:
- exids stringREQUIREDThe external IDs (comma separated) of the passes that you want in the download.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe ID of the template the pass will be or was created from. For External IDs, format the
{templateId}asid/{templateExternalId}.
Responses
200
Returns the .pkpass file as a .zip extension.
404
The pass or template ID does not exist.
List beacons on Apple Wallet pass
GET /pass/template/{templateId}/id/{passExternalId}/beacons
Example request
GET /v1/pass/template/123/id/mypass/beacons HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/pass/template/123/id/mypass/beacons HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
]
}
Lists location beacons assigned to the specified Apple Wallet pass.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template of the Apple Wallet pass that you want to get beacons from.
- passExternalId stringREQUIREDThe external ID of the Apple Wallet pass you want to get beacons for.
Responses
200
An array of beacons belonging to the pass.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- beacons array
An array of objects, each representing a beacon associated with the Apple Wallet pass.
404
The pass or template ID does not exist.
Add or update beacons for Apple Wallet pass
PUT /pass/template/{templateId}/id/{passExternalId}/beacons
Example request
PUT /v1/pass/template/123/id/mypass/beacons HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
]
}
Response
PUT /v1/pass/template/123/id/mypass/beacons HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
]
}
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"ticketId": 7
}
Add or replace beacons on the specified Apple Wallet pass with an external ID.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template of the Apple Wallet pass that you want to apply beacons to.
- passExternalId stringREQUIREDThe external ID of the Apple Wallet pass you want to apply beacons to.
Request body:
An array of beacons that you want to associate with the pass.
Content-Type:
OBJECT PROPERTIESapplication/json- beacons array
An array of objects, each representing a beacon you want to add to an Apple Wallet pass.
Responses
201
A successful call results in a ticket to apply beacons to the pass.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ticketId integer
A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.
404
The pass or template ID does not exist.
Download Apple Wallet .pkpass with external ID
GET /pass/template/{templateId}/id/{passExternalId}/download
Example request
GET /v1/pass/template/123/id/mypass/download HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Download the contents of an Apple Wallet .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes.
See Apple’s developer documentation for information about .pkpass files and contents.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template used to create the pass.
- passExternalId stringREQUIREDThe external ID of the pass you want to download.
Responses
200
Returns the .pkpass file as a .zip extension.
404
The pass or template ID does not exist.
Download Apple Wallet .pkpass
GET /pass/{passId}/download
Example request
GET /v1/pass/123/download HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Download the contents of an Apple Wallet .pkpass file. Direct the output to a file with a .zip extension. This is a utility API to help you debug passes.
See Apple’s developer documentation for information about .pkpass files and contents.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- passId stringREQUIREDThe
idof the pass you want to download.
Responses
200
Returns the .pkpass file as a .zip extension.
View Apple Wallet JSON
GET /pass/{passId}/viewJSONPass
Example request
GET /v1/pass/123/viewJSONPass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/pass/123/viewJSONPass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json
{
"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.example.com"
},
{
"key": "back0",
"label": "Built with Airship Reach",
"value": "Find out more and create your own passes at https://wallet.urbanairship.com\n\nAirship, Inc.,1417 NW Everett St., Portland, OR 97209 800.720.2098 support@urbanairship.com"
}
],
"primaryFields":[
{
"key": "Program Name",
"label": "Airship",
"value": "Program Name",
"textAlignment": "PKTextAlignmentNatural"
}
],
"headerFields":[
{
"key": "Points",
"label": "Points",
"value": 1234.0,
"textAlignment": "PKTextAlignmentNatural",
"numberStyle": "PKNumberStyleDecimal"
}
],
"secondaryFields":[
{
"key": "Tier",
"label": "Tier",
"value": 2.0,
"textAlignment": "PKTextAlignmentNatural",
"numberStyle": "PKNumberStyleDecimal"
},
{
"key": "Tier Name",
"label": "Tier Name",
"value": "Silver",
"textAlignment": "PKTextAlignmentNatural"
},
{
"key": "Member Name",
"label": "Member Name",
"value": "First Last",
"textAlignment": "PKTextAlignmentNatural"
}
]
},
"organizationName": "Airship",
"backgroundColor": "rgb(0,147,201)",
"labelColor": "rgb(24,86,148)",
"authenticationToken": "df897c90-5a9b-48dd-a4b4-8020486811b7",
"serialNumber": "bcc7cdae-e491-4e36-a95e-9758e31549aa",
"barcode": {
"message": "123456789",
"messageEncoding": "iso-8859-1",
"format": "PKBarcodeFormatPDF417",
"altText": "123456789"
},
"teamIdentifier": "MN52833CEX",
"formatVersion": 1,
"webServiceURL": "https:\/\/wallet-api.urbanairship.com\/apple",
"description": "Template 1",
"foregroundColor": "rgb(255,255,255)"
}
Returns the JSON of an Apple Wallet pass. The Airship request payload is translated when sent to Apple. You can use this endpoint to view the JSON payload as passed to Apple Wallet for debugging purposes.
See Apple’s developer documentation for information about Apple Wallet payloads.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- passId stringREQUIREDThe
idof the pass you want to return Apple Wallet JSON for.
Responses
200
A successful request returns Apple JSON
Response body:
- Content-Type:
application/jsonType:
object
Google Passes Only
Get messages for Google Pass with external ID
GET /pass/template/{templateId}/id/{passExternalId}/message
Example request
GET /v1/pass/template/123/id/mypass/message HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/pass/template/123/id/mypass/message HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"messages": [
{
"header": "expires",
"body": "wallet object expiring soon",
"createdAt": "2019-03-05T23:11:29.000Z",
"updatedAt": "2019-03-05T23:11:29.000Z",
"messageType": "expirationNotification"
}
]
}
Returns an array of messages associated with the specified pass.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template of the Google Pass that you want to get messages from.
- passExternalId stringREQUIREDThe external ID of the Google Pass you want to get messages for.
Responses
200
A successful response returns details for the added messages.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- messages array[object]
An array of messages associated with the pass.
404
The pass or template ID does not exist.
Add message to Google Pass with external ID
POST /pass/template/{templateId}/id/{passExternalId}/message
Example request
POST /v1/pass/template/123/id/mypass/message HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"body":"wallet object expires soon",
"header":"expires",
"startTime": "2018-06-03T21:10:00.000Z",
"endTime": "2018-06-05T21:50:00.000Z",
"messageType":"expirationNotification"
}
Response
POST /v1/pass/template/123/id/mypass/message HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"body":"wallet object expires soon",
"header":"expires",
"startTime": "2018-06-03T21:10:00.000Z",
"endTime": "2018-06-05T21:50:00.000Z",
"messageType":"expirationNotification"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"header": "expires",
"body": "wallet object expires soon",
"startTime": "2018-06-03T21:10:00.000Z",
"endTime": "2018-06-05T21:50:00.000Z",
"createdAt": "2021-08-18T23:25:05.075Z",
"updatedAt": "2021-08-18T23:25:05.075Z",
"messageType": "expirationNotification"
}
Add messages to Google Wallet passes.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe template of the Google Pass that you want to apply messages to.
- passExternalId stringREQUIREDThe external ID of the Google Pass you want to apply messages to.
Request body:
A valid request contains one message for the pass.
Content-Type:
OBJECT PROPERTIESapplication/json- body string
The message body text.
- endTime object
The date-time when the notification will end. If you do not set an end time, the notification displays indefinitely.
OBJECT PROPERTIES- date string
- header string
The header text for the message
- messageType string
Use
expirationNotificationto warn users of expiring messages, andtextfor all other notifications.expirationNotificationis based on thestartvalue in thedisplayInterval; the maximum display interval is 30 days from now. If the expiration start date is more than 30 days from now, the message will not appear until the 30-day mark.Possible values:
expirationNotification,text - startTime object
The date-time when the notification will begin appearing to users.
OBJECT PROPERTIES- date string
Responses
200
A successful response returns details for the added message.
Response body:
- Content-Type:
application/jsonInformation about messages associated with specified Google Wallet passes.
OBJECT PROPERTIES- body string
The body of the message.
- createdAt string
The date and time when the item was created.
- header string
The header for the message.
- messageType string
The type of message.
Possible values:
expirationNotification,text - updatedAt string
The date and time when the item was last updated.
404
The pass or template ID does not exist.
Get messages for Google Pass
GET /pass/{passId}/message
Example request
GET /v1/pass/mypass/message HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/pass/mypass/message HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"messages": [
{
"header": "expires",
"body": "wallet object expiring soon",
"createdAt": "2019-03-05T23:11:29.000Z",
"updatedAt": "2019-03-05T23:11:29.000Z",
"messageType": "expirationNotification"
}
]
}
Returns an array of messages associated with the specified pass.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- passId stringREQUIREDThe
Idof the Google Pass you want to get messages from.
Responses
200
A successful response returns details for the added messages.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- messages array[object]
An array of messages associated with the pass.
404
The pass ID does not exist.
Add message to Google Pass
POST /pass/{passId}/message
Example request
POST /v1/pass/mypass/message HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"body":"wallet object expires soon",
"header":"expires",
"startTime": "2018-06-03T21:10:00.000Z",
"endTime": "2018-06-05T21:50:00.000Z",
"messageType":"expirationNotification"
}
Response
POST /v1/pass/mypass/message HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"body":"wallet object expires soon",
"header":"expires",
"startTime": "2018-06-03T21:10:00.000Z",
"endTime": "2018-06-05T21:50:00.000Z",
"messageType":"expirationNotification"
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"header": "expires",
"body": "wallet object expires soon",
"startTime": "2018-06-03T21:10:00.000Z",
"endTime": "2018-06-05T21:50:00.000Z",
"createdAt": "2021-08-18T23:25:05.075Z",
"updatedAt": "2021-08-18T23:25:05.075Z",
"messageType": "expirationNotification"
}
Add messages to Google Wallet passes.
Security:
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- passId stringREQUIREDThe
Idof the Google Pass you want to apply messages to.
Request body:
A valid request contains one message for the pass.
Content-Type:
OBJECT PROPERTIESapplication/json- body string
The message body text.
- endTime object
The date-time when the notification will end. If you do not set an end time, the notification displays indefinitely.
OBJECT PROPERTIES- date string
- header string
The header text for the message
- messageType string
Use
expirationNotificationto warn users of expiring messages, andtextfor all other notifications.expirationNotificationis based on thestartvalue in thedisplayInterval; the maximum display interval is 30 days from now. If the expiration start date is more than 30 days from now, the message will not appear until the 30-day mark.Possible values:
expirationNotification,text - startTime object
The date-time when the notification will begin appearing to users.
OBJECT PROPERTIES- date string
Responses
200
A successful response returns details for the added message.
Response body:
- Content-Type:
application/jsonInformation about messages associated with specified Google Wallet passes.
OBJECT PROPERTIES- body string
The body of the message.
- createdAt string
The date and time when the item was created.
- header string
The header for the message.
- messageType string
The type of message.
Possible values:
expirationNotification,text - updatedAt string
The date and time when the item was last updated.
404
The pass ID does not exist.
Save to Google Wallet
POST /pass/{templateId}/saveToWallet
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()"
}
Response
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()"
}
<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 Wallet” button. Clicking or tapping this button installs the pass.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- templateId stringREQUIREDThe
idof the template you want to generate a “Save to Google Wallet” button for.
Request body:
The request is much like creating a pass with the addition of functions to perform upon success or failure.
Content-Type:
OBJECT PROPERTIESapplication/json- externalId string
An external identifier for the pass that you might want to use to update the pass in the future.
- fields object
- onFail string
A javascript function that you want to be called when a user
- onSuccess string
A javascript function that you want to be called when a user successfully adds the pass to Google Wallet.
- tag string
A single tag you want to add to the pass.
Responses
200
A response includes the javascript for a “Save to Google Wallet” button.
Schedules
List schedules
GET /schedules/{projectId}
Example request
GET /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"count": 2,
"next_page": "https://wallet-api.urbanairship.com/v1/schedules/12345?start=5c69320c-3e91-5241-fad3-248269eed104&limit=2&order=asc",
"ok": true,
"schedules": [
{
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"primary1": {
"value": "$20 Off"
},
"secondary1": {
"value": "Mega Offer"
}
}
}
},
"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 occurred for the project.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project ID.
Responses
200
Returns a list of schedules, ordered scheduled_time closest to the present.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- count integer
The number of schedules on the page.
- next_page string
The URL of the next page in the result set.
- ok boolean
If true, the operation completed successfully.
- schedules array
The list of upcoming schedules.
- total_count integer
The total number of schedules.
Schedule an update or push notification
POST /schedules/{projectId}
Example request for update
POST /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"primary1": {
"value": "$20 Off"
},
"secondary1": {
"value": "Mega Offer"
}
}
}
}
}
Response for update
POST /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"primary1": {
"value": "$20 Off"
},
"secondary1": {
"value": "Mega Offer"
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ok": true,
"operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
"schedule_urls": [
"https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
],
"schedules": [
{
"url": "https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109",
"ticket": "https://wallet-api.urbanairship/v1/ticket/6789",
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"secondary1": {
"value": "Mega Offer"
},
"primary1": {
"value": "$20 Off"
}
}
}
}
}
]
}
Example request for notification
POST /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"primary1": {
"value": "$20 Off"
},
"secondary1": {
"value": "Mega Offer"
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ok": true,
"operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
"schedule_urls": [
"https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
],
"schedules": [
{
"url": "https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109",
"ticket": "https://wallet-api.urbanairship/v1/ticket/6789",
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"secondary1": {
"value": "Mega Offer"
},
"primary1": {
"value": "$20 Off"
}
}
}
}
}
]
}
POST /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"notify": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"notification": {
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
}
}
}
Response for notification
POST /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"primary1": {
"value": "$20 Off"
},
"secondary1": {
"value": "Mega Offer"
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ok": true,
"operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
"schedule_urls": [
"https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
],
"schedules": [
{
"url": "https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109",
"ticket": "https://wallet-api.urbanairship/v1/ticket/6789",
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"secondary1": {
"value": "Mega Offer"
},
"primary1": {
"value": "$20 Off"
}
}
}
}
}
]
}
POST /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"notify": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"notification": {
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ok": true,
"operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
"schedule_urls": [
"https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
],
"schedules": [
{
"url": "https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109",
"ticket": "https://wallet-api.urbanairship/v1/ticket/6789",
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"notify": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"notification": {
"label": "Last Notification",
"value": "20% off any one regular priced item"
}
}
}
}
]
}
Schedule an update to a project or schedule a notification to a project.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project ID.
Request body:
The schedule update object to schedule an update or the schedule notification object to schedule a notification.
Content-Type:
One ofapplication/jsonSpecifies updates to passes or adaptive links at a particular date and time.
- Schedule Notification Object object
Specifies notifications to passes or adaptive links at a particular date and time.
OBJECT PROPERTIES- name string
A name for the schedule.
- notify object
The notification you want to send to an
OBJECT PROPERTIESaudienceorpass, generated from atemplatewithin the project. Cannot be used with the update object present as well.- audience object<Audience selector>
Determines the passes you want to target.
- pass objectOBJECT PROPERTIES
- notification object
An object for sending a custom pass notification message.
OBJECT PROPERTIES- label string
Optional header for the message.
- value stringREQUIRED
The body of the notification message.
- schedule objectOBJECT PROPERTIES
- scheduled_time string
The ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC.
- url string
A URL to get the schedule object.
Responses
200
Returns the schedule request along with identifiers for the operation and the schedule itself.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ok boolean
If true, the operation completed successfully.
- operation_id string
Identifies the operation for troubleshooting and logging.
- schedule_urls array[string]
URLs for the schedules created by the operation. Items in the array are ordered just as they were in the request.
- schedules array
Get schedule
GET /schedules/{projectId}/{scheduleId}
Example request
GET /v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
GET /v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"primary1": {
"value": "$20 Off"
},
"secondary1": {
"value": "Mega Offer"
}
}
}
}
}
Return a single project’s schedule.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project ID.
- scheduleId stringREQUIREDThe schedule ID. This is appended to the end of the
urlin the response for schedule operations.
Responses
200
Returns a single schedule object.
Response body:
- Content-Type:
application/jsonSpecifies updates to passes or adaptive links at a particular date and time.
Update schedule
PUT /schedules/{projectId}/{scheduleId}
Example request
PUT /v1/schedules/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-11T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"primary1": {
"value": "$20 Off"
},
"secondary1": {
"value": "Mega Offer"
}
}
}
}
}
Response
PUT /v1/schedules/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-11T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"primary1": {
"value": "$20 Off"
},
"secondary1": {
"value": "Mega Offer"
}
}
}
}
}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ok": true,
"operation_id": "efb18e92-9a60-6689-45c2-82fedab36490",
"schedule_urls": [
"https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109"
],
"schedules": [
{
"url": "https://wallet-api.urbanairship/v1/schedules/12345/2d69320c-3c91-5241-fac4-248269eed109",
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-11T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"secondary1": {
"value": "Mega Offer"
},
"primary1": {
"value": "$20 Off"
}
}
}
}
}
]
}
Update a schedule. The payload to update a schedule is identical to the request to create a schedule.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project ID.
- scheduleId stringREQUIREDThe schedule ID. This is appended to the end of the
urlin the response for schedule operations.
Request body:
Content-Type:
application/jsonSpecifies updates to passes or adaptive links at a particular date and time.
Responses
200
Returns the updated schedule object.
Response body:
- Content-Type:OBJECT PROPERTIES
application/json- ok boolean
If true, the operation completed successfully.
- operation_id string
Identifies the operation for troubleshooting and logging.
- schedule_urls array[string]
URL for the updated schedule.
- schedules array
Delete schedule
DELETE /schedules/{projectId}/{scheduleId}
Example request
DELETE /v1/schedules/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
Response
DELETE /v1/schedules/12345/3b13666df-e5b3-4e42-8919-f8d63bd7ce2a HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2
HTTP/1.1 204 No Content
Deletes the specified schedule.
Request headers:
- Api-Revision stringREQUIREDThe particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Path parameters:
- projectId stringREQUIREDThe project ID.
- scheduleId stringREQUIREDThe schedule ID. This is appended to the end of the
urlin the response for schedule operations.
Responses
204
A deleted schedule returns no content.
Data Formats
Adaptive Links
Adaptive links detect the user’s platform and install the correct pass for their device vendor. An adaptive link can specify an Apple and Google template.
Adaptive Link request
Example Adaptive Link
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"landingPageUrl": "https://example.com/landing.html",
"expirationDate": "2022-10-01",
"availablePasses": 100000,
"ttlInDays": 30,
"parameterEncoding": "base64",
"locationRadius": 10,
"maxResultLocations": 5,
"payload": {},
"locations": [
{
"latitude": 45.5898,
"longitude": -122.5951,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97218",
"relevantText": "Welcome to Portland... Voodoo Donuts is only 11 miles away",
"streetAddress1": "7000 NE Airport Way"
},
{
"latitude": 45.525492,
"longitude": -122.686092,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97209",
"relevantText": "Welcome to the Ship!",
"streetAddress1": "1417 NW Everett St #300",
"streetAddress2": ""
},
{
"latitude": 45.5205,
"longitude": -122.6788,
"relevantText": "See you at dinner tonight… or did you already hit voodoo donuts?"
}
]
}
An adaptive link request contains identifiers for the templates you used to generate passes from the link and any fields you want to set when users create passes from the link. If you need to create a boarding pass adaptive link, go to the boarding pass object.
All of- OBJECT PROPERTIES
- androidTemplateExternalId string
The custom identifier of the Google template for passes issued from this adaptive link.
- androidTemplateId integer
The Google template for passes issued from the adaptive link.
- availablePasses integer
The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.
- iosTemplateExternalId string
The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.
- iosTemplateId integer
The iOS template for passes issued from the adaptive link.
- isPersonalized boolean
If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters,
isPersonalizedis automatically set totrue.If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When
isPersonalizedisfalse, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link. - landingPageUrl string
The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason.
- parameterEncoding string
When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.
Possible values:
base64
- OBJECT PROPERTIES
- androidPassLinkId string
A dynamic link for Android passes.
- expirationDate string
When set, indicates the date this adaptive link expires. An expired adaptive link will return a JSON object with an error message instead of a pass.
- installLimit integer
The number of times a user can install the pass. When the pass reaches its limit, attempts to install the pass are met with errors.
This limit only affects the adaptive link itself, not actual Apple pass files. If you want to prevent users from installing shared passes on Apple devices, you should also set
sharingStatusto prohibit sharing. - installLimitPerPassExternalId integer
The number of times a user can install the pass that has an
externalId. When the pass reaches its limit, attempts to install the pass are met with errors.This limit only affects the adaptive link itself, not actual Apple pass files. If you want to prevent users from installing shared passes on Apple devices, you should also set
sharingStatusto prohibit sharing. - iosPassLinkId string
A dynamic link for iOS passes.
- locationRadius integer
Determines the range, in miles, that a pass holder can be from a location to associate their pass with a location. If absent, the default location radius is 10 miles.
- locations array
An array of up to 10,000 locations associated with the adaptive link. Apple Wallet supports up to 10 locations per pass. If you exceed this limit, Apple Wallet passes will use the 10 locations nearest to a user (located by IP address) when they install the pass.
You can also include a location radius and the maximum number of locations to be matched upon pass creation. Wallet sorts locations to be matched in order from closest to/furthest from the location provided by the device.
- maxResultLocations integer
The maximum number of locations the pass recipient can match. If the pass holder matches multiple locations, locations are returned in order from closest to farthest.
- payload objectREQUIRED
The field names and values you want to update for those pass fields. Changing a value will result in a change message notifying the user of the changed value.
While the payload object is required, it can be an empty object.
OBJECT PROPERTIES- sharingStatus object
A
fielddetermining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as otherfields, you only need to set thevaluewithin the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.On iOS devices,
oneUserOneDeviceprohibits sharing ("sharingProhibited": true); all other values allow sharing.You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.
OBJECT PROPERTIES- changeMessage string
The message that appears when you update this field.
- value stringREQUIRED
Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting:
oneUserOneDeviceprohibits sharing; all other values allow sharing.Possible values:
multipleHolders,oneUserAllDevices,oneUserOneDevice
Adaptive Link response
Example Adaptive Link response object
{
"adaptiveLinkId": "abchd345678",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/android",
"landingPageUrl": "https://example.com/landing.html",
"isPersonalized": "true",
"isExpired": true,
"expirationDate": "2020-10-01",
"availablePasses": 100000,
"ttlInDays": 730
}
An adaptive link response includes URLs that users can access to detect and install a pass.
All of- OBJECT PROPERTIES
- androidTemplateExternalId string
The custom identifier of the Google template for passes issued from this adaptive link.
- androidTemplateId integer
The Google template for passes issued from the adaptive link.
- availablePasses integer
The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.
- iosTemplateExternalId string
The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.
- iosTemplateId integer
The iOS template for passes issued from the adaptive link.
- isPersonalized boolean
If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters,
isPersonalizedis automatically set totrue.If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When
isPersonalizedisfalse, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link. - landingPageUrl string
The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason.
- parameterEncoding string
When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.
Possible values:
base64
- OBJECT PROPERTIES
- adaptiveLinkId integer
A unique identifier for the adaptive link. Use this value to reference the adaptive link in future operations.
- androidPassLinkId string
A dynamic link for Android passes. This field cannot be provided for
links/adaptive/multiplerequests, nor is it provided in those responses (e.g., boarding passes, event tickets, etc.). - androidUrl string
A pass URL specific to Android users.
- createdAt string
The date and time when the item was created.
- expirationDate string
The date this adaptive link expires. This property appears in the response only if it has been explicitly set with a previous API request. Cannot be set to a date more than 1,080 days in the future.
- iosPassLinkId string
A dynamic link for iOS passes. This field cannot be provided for
links/adaptive/multiplerequests, nor is it provided in those responses (e.g., boarding passes, event tickets, etc.). - iosUrl string
A pass URL specific to iOS users.
- isExpired boolean
If true, the adaptive link is expired. An expired adaptive link will return a JSON object with an error message instead of a pass.
- projectId integer
The ID of the project.
- ttlInDays integer
The number of days of inactivity before this adaptive link automatically expires.
- updatedAt string
The date and time when the item was last updated.
- url string
The adaptive link URL itself; using this URL on an Android or iOS device will detect device types and install the correct pass.
Audience selection
Select an audience of passes for scheduled updates or other operations.
Atomic selector
Example atomic selector tag
{
"audience": {
"tag": "TZ_PST"
}
}
Example atomic selector segment
{
"audience": {
"tag": "TZ_PST"
}
}
{
"audience": {
"segment": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a"
}
}
Example atomic selector template
{
"audience": {
"tag": "TZ_PST"
}
}
{
"audience": {
"segment": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a"
}
}
{
"audience": {
"templateId": 1234
}
}
Example atomic selector pass
{
"audience": {
"tag": "TZ_PST"
}
}
{
"audience": {
"segment": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a"
}
}
{
"audience": {
"templateId": 1234
}
}
{
"audience": {
"passId": 1234
}
}
Example atomic selector external ID
{
"audience": {
"tag": "TZ_PST"
}
}
{
"audience": {
"segment": "3b13666df-e5b3-4e42-8919-f8d63bd7ce2a"
}
}
{
"audience": {
"templateId": 1234
}
}
{
"audience": {
"passId": 1234
}
}
{
"audience": {
"and": [
{ "externalId": "test_ext_id" },
{ "templateId": "12345" }
]
}
}
Determines the property type you want to target. This can be tag, segment, template, pass or externalId.
OBJECT PROPERTIES- externalId string[string]
The pass external ID. Must also include a template.
- passId number[number]
The pass ID.
- segment array[string]
The segment ID.
- tag array[string]
A tag is arbitrary metadata string used to identify and target passes.
- templateId number[string]
The template ID.
Audience selector
Example pass objects tagged for baseball or basketball and in time zone PST
{
"audience": {
"AND": [
{
"OR": [
{
"tag": "baseball"
},
{
"tag": "basketball"
}
]
},
{
"tag": "TZ_PST"
}
]
}
}
Example pass objects tagged for time zone ET and not for time zone PST
{
"audience": {
"AND": [
{
"OR": [
{
"tag": "baseball"
},
{
"tag": "basketball"
}
]
},
{
"tag": "TZ_PST"
}
]
}
}
{
"audience": {
"AND": [
{
"tag": "TZ_ET"
},
{
"NOT": {
"tag": "TZ_PST"
}
}
]
}
}
Determines the passes you want to target.
One ofCompound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. The syntax can be either implicit, using an array of values associated with an atomic selector, or explicit, employing a boolean operator followed by an array of atomic expression objects.
Determines the property type you want to target. This can be tag, segment, template, pass or externalId.
- string
All passes.
Compound selector
Example implicit OR
{
"audience": {
"tag": [
"apples",
"oranges",
"bananas"
]
}
}
Example explicit OR
{
"audience": {
"tag": [
"apples",
"oranges",
"bananas"
]
}
}
{
"audience": {
"OR": [
{
"tag": "apples"
},
{
"tag": "oranges"
},
{
"tag": "bananas"
}
]
}
}
Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. The syntax can be either implicit, using an array of values associated with an atomic selector, or explicit, employing a boolean operator followed by an array of atomic expression objects.
One ofDetermines the property type you want to target. This can be tag, segment, template, pass or externalId.
AND selector
OBJECT PROPERTIES- AND array
OR selector
OBJECT PROPERTIES- OR array
NOT selector
OBJECT PROPERTIES- NOT array
Event tickets
Schemas for creating events and event ticket adaptive links. An event ticket includes both event information and an array of attendees.
Attendees
Array of attendees
{
"attendees": [
{
"adaptiveLinkExternalId": "abch3ExtId4",
"fields": {
"ticketHolderName": { "label": "Name", "value":"SMITH/SAM" },
"seat": { "value":"11" },
"ticketType": { "value":"VIP" },
"ticketNumber": { "value":"20595923485" },
"barcode_value": { "value": "1237" },
"barcodeAltText": { "value": "1237" },
"faceValue": { "value": "100" }
}
},
{
"adaptiveLinkExternalId": "abch3ExtId5",
"fields":{
"ticketHolderName": { "label": "Name", "value":"SMITH/MARY" },
"seat": { "value":"12" },
"ticketType": { "value":"VIP" },
"ticketNumber": { "value":"20595923486" },
"barcode_value": { "value": "1238" },
"barcodeAltText": { "value": "1238" },
"faceValue": { "value": "100" }
}
},
{
"fields": {
"ticketHolderName": { "label": "Name", "value":"SMITH/SARA" },
"seat":{ "value":"13" },
"ticketType":{ "value":"VIP" },
"ticketNumber":{ "value":"20595923487" },
"barcode_value": { "value": "1239" },
"barcodeAltText": { "value": "1239" },
"faceValue": { "value": "100" }
}
}
]
}
An array of attendees for an event. Each object in the array represents a single attendee.
Event request
Example event request object
{
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"label": "Event",
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"label": "Venue",
"value": "AT&T Park"
},
"venueAddress": {
"label": "Address",
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T08:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T09:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T11:00:00"
}
}
}
Represents an event scheduled at a specific time and venue.
OBJECT PROPERTIES- fields objectREQUIRED
Contains the objects representing an event.
OBJECT PROPERTIES- doorsOpen object
The date and time when ticket holders can begin to enter the venue.
OBJECT PROPERTIES- label string
The title for this event field as you want it to appear on a pass. Defaults to
Doors Open. - value string
- endTime object
The date and time when the event ends.
OBJECT PROPERTIES- label string
The title for this event field, as you want it to appear on a pass. Defaults to
End Time. - value string
- eventName objectREQUIRED
The value represents the event name.
OBJECT PROPERTIES- label string
The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.
- value string
- startTime object
The date and time when the event begins.
OBJECT PROPERTIES- label string
The title for this event field, as you want it to appear on a pass. Defaults to
Start Time. - value string
- venueAddress objectREQUIRED
The address of the venue.
OBJECT PROPERTIES- label string
The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.
- value string
- venueTitle objectREQUIRED
The name of the venue where the event will take place.
OBJECT PROPERTIES- label string
The label for this field, as you want it to appear on the pass. If you do not provide a label, the event will use a default based off the parent object name.
- value string
- passGroups array[string]
An array of eventId or eventExternalId values representing a group. You can reference the group to make changes to all associated events.
You can set pass groups when creating an event or when creating an event ticket adaptive link.
Event response
Response object
{
"eventId": 1234,
"eventExternalId": "event123ExtId",
"projectId": 12345,
"projectExternalId": "project123ExtId",
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:12:32Z",
"passGroups": ["giants_2019-09-25"],
"fields": {
"eventName": {
"label": "Event",
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"label": "Venue",
"value": "AT&T Park"
},
"venueAddress": {
"label": "Address",
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T08:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T09:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T11:00:00"
}
}
}
An event response returns identifiers that you can use to reference the event in other endpoints, along with the complete event request body.
All ofRepresents an event scheduled at a specific time and venue.
- OBJECT PROPERTIES
- createdAt string
The date and time when the item was created.
- eventExternalId string
An external identifier for an event. You can only assign an external identifier when creating an event. If you do assign an external identifier, requests for events or passes referencing the event will return the external ID in addition to the
eventIdcreated within Airship. - eventId integer
The Airship-created identifier for an event.
- projectExternalId string
Returned if you created the event using an external ID for the project.
- projectId integer
The ID of the Wallet project.
- updatedAt string
The date and time when the item was last updated.
Event ticket Adaptive Link request
Example event ticket request object
{
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateExternalId": "android123ExtId",
"payload": {
"events": [
{
"eventExternalId": "event123ExtId",
"passGroups": [
"giants_2019-09-25"
],
"fields": {
"eventName": {
"value": "LA Dodgers at SF Giants"
},
"venueTitle": {
"value": "AT&T Park"
},
"venueAddress": {
"label": "Address",
"value": "24 Willie Mays Plaza\nSan Francisco, CA 94107"
},
"doorsOpen": {
"label": "Doors Open",
"value": "2019-09-25T08:35:00"
},
"startTime": {
"label": "Start Time",
"value": "2019-09-25T09:00:00"
},
"endTime": {
"label": "End Time",
"value": "2019-09-25T11:00:00"
}
},
"attendees": [
{
"adaptiveLinkExternalId": "abch3ExtId1",
"fields": {
"ticketHolderName": {
"label": "Name",
"value": "SMITH/JOE"
},
"seat": {
"value": "33"
},
"ticketType": {
"value": "VIP"
},
"barcode_value": {
"value": "1234"
},
"barcodeAltText": {
"value": "1234"
},
"faceValue": {
"value": "50"
}
}
},
{
"adaptiveLinkExternalId": "abch3ExtId2",
"fields": {
"ticketHolderName": {
"label": "Name",
"value": "SMITH/SALLY"
},
"seat": {
"value": "34"
},
"ticketType": {
"value": "VIP"
},
"barcode_value": {
"value": "1235"
},
"barcodeAltText": {
"value": "1235"
},
"faceValue": {
"value": "50"
}
}
},
{
"adaptiveLinkExternalId": "abch3ExtId2",
"fields": {
"ticketHolderName": {
"label": "Name",
"value": "SMITH/JACK"
},
"seat": {
"value": "35"
},
"ticketType": {
"value": "VIP"
},
"barcode_value": {
"value": "1236"
},
"barcodeAltText": {
"value": "1236"
},
"faceValue": {
"value": "50"
}
}
}
]
}
]
}
}
An event ticket requires similar information to other adaptive link types, but does not support some of the same fields, and requires event and attendee information.
Like other adaptive links, you must provide the id or externalId of an iOS or Android template. You can create the event within this request or specify an event by eventId or eventExternalId. In either case, you must also provide an array of attendees for the event.
- OBJECT PROPERTIES
- androidTemplateExternalId string
The custom identifier of the Google template for passes issued from this adaptive link.
- androidTemplateId integer
The Google template for passes issued from the adaptive link.
- availablePasses integer
The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.
- iosTemplateExternalId string
The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.
- iosTemplateId integer
The iOS template for passes issued from the adaptive link.
- isPersonalized boolean
If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters,
isPersonalizedis automatically set totrue.If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When
isPersonalizedisfalse, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link. - landingPageUrl string
The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason.
- parameterEncoding string
When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.
Possible values:
base64
- OBJECT PROPERTIES
- payload objectOBJECT PROPERTIES
- events array
Each object in the array represents an event. Each event object must specify the
eventIdoreventExternalIdof an existing event, or contain thefieldsobject sufficient to create a new event.You can also provide the
eventExternalIdin conjunction with thefieldsobject to assign an eventExternalId to a new event.
Event ticket Adaptive Link response
Example event ticket response array
[
{
"adaptiveLinkId": "abchd345678",
"adaptiveLinkExternalId": "abch3ExtId1",
"iosTemplateId": 12345,
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateId": 154321,
"androidTemplateExternalId": "android123ExtId",
"eventId": 476,
"eventExternalId": "event123ExtId",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/android",
"createdAt": "2018-09-24T09:12:32Z",
"updatedAt": "2018-09-24T09:15:32Z",
"isPersonalized": "false",
"availablePasses": 1000000,
"iosPassLinkId": "a5711a29-7b38-41f2-8202-8f792df89b0b",
"androidPassLinkId": "c1f512e5-fda3-4ddf-82c6-066c5681161d",
"status": 200
},
{...},
{...}
]
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 ofAn adaptive link response includes URLs that users can access to detect and install a pass.
- OBJECT PROPERTIES
- eventExternalId string
An external identifier for an event. You can only assign an external identifier when creating an event. If you do assign an external identifier, requests for events or passes referencing the event will return the external ID in addition to the
eventIdcreated within Airship. - eventId integer
The Airship-created identifier for an event.
- status integer
The HTTP status code for the adaptive link operation.
Passes
Schemas used when creating passes (as opposed to adaptive links).
Beacon object
Example beacon object
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
Associates a pass with an iBeacon. Apple Wallet supports up to 10 beacons per pass. When the pass holder comes into proximity with an iBeacon bearing the same UUID, the pass becomes relevant (displayed on the lock screen).
OBJECT PROPERTIES- major integerREQUIRED
Major identifier of a beacon.
- minor integerREQUIRED
Minor identifier of a beacon.
- relevantText stringREQUIRED
Text displayed on the lock screen.
- uuid stringREQUIRED
Unique identifier of a beacon.
Google Wallet pass request
Example Google pass request
{
"headers": {
"expirationDate":{
"value":"2014-08-20T9:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
}
},
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
],
"publicUrl": {
"type": "single"
}
}
A pass for Google Wallet. Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module that the field belongs to.
Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.
OBJECT PROPERTIES- fields object
Fields for the pass. The template defines a field’s location on the pass and its default value(s). When creating a pass, you only need to populate the fields you want to update, and even then, you only need to provide the
valueyou want to change for the field and thechangeMessageif you want to notify pass holders of the change in the value. - headers object
Include objects from the template
OBJECT PROPERTIESheadersobject if you want to change thelabel,value, orchangeMessagefor fields in the pass header — like barcodes and titles.- expirationDate string
May contain
valueandlabelfields.valueindicates the expiration date of the pass.labelcan be set to eithervalidorvoided, wherevalidindicates a non-expired pass andvoidedindicates that the pass is no longer accepted.
- locations array
A list of locations associated with a pass.
- publicUrl objectREQUIRED
A public URL from which users can download a pass.
For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify
type: singlein the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.
OBJECT PROPERTIES- installs integer
The number of users who have installed the pass from the URL specified in the
pathfield. - path string
The URL for the pass.
- type stringREQUIRED
Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.
Possible values:
single,multiple - used boolean
If true, a user has accessed the
pathURL.
- templateId integer
The identifier for the template. You can recall the template by ID in other operations.
Google Wallet pass response
Example Google pass response
{
"createdAt": "2018-10-25T19:13:14Z",
"headers": {
"background_color": {
"ignoresTimeZone": null,
"changeMessage": null,
"label": "",
"hideEmpty": false,
"formatType": "String",
"value": "#006491",
"fieldType": "topLevel",
"required": false
},
"strip_image": {
"ignoresTimeZone": null,
"changeMessage": null,
"label": "",
"hideEmpty": false,
"formatType": "String",
"value": "https://s3.amazonaws.com/passtools_prod/1169167/images/587ac4e3d188b0fcd4f05038d8814fefd82ac834_iOS_Logo_320x100_WHITE.png",
"fieldType": "image",
"required": false
},
"expirationDate": {
"ignoresTimeZone": null,
"changeMessage": null,
"label": "",
"hideEmpty": false,
"formatType": "String",
"value": "2019-10-25T19:13:14Z",
"fieldType": "topLevel",
"required": false
}
},
"serialNumber": "06bad8bd-b399-4c86-83b6-06fcee2e52b6",
"uaEntityId": "9e3bf713-f6e6-4d6e-b2d4-c9ab6028892e",
"id": "47400533",
"templateId": "63621",
"fields": {
"image": {
"ignoresTimeZone": null,
"title.string": "https://s3.amazonaws.com/passtools_prod/1169167/images/9af688aea35f473e29ca187438c12083202f1eeb_Android_Logo_660x660.png",
"hideEmpty": false,
"formatType": "String",
"fieldType": "titleModule",
"description.string": "Logo Image"
},
"Details": {
"col": 0,
"ignoresTimeZone": null,
"header": "Coupon Details",
"hideEmpty": false,
"row": 0,
"formatType": "String",
"body": "25% off when you spend £20 or more online using code WNTRBLOG",
"fieldType": "textModulesData"
},
"FinePrint": {
"col": 0,
"ignoresTimeZone": null,
"header": "Terms & Conditions ",
"hideEmpty": false,
"row": 0,
"formatType": "String",
"body": "Please go to http://www.dominos.co.uk and click on “Boring Legal Stuff”",
"fieldType": "textModulesData"
},
"offerModule": {
"multiUserOffer": false,
"redemptionChannel": "both",
"provider": "Domino's Snap Offer",
"endTime": "2018-01-31T00:00:00.000Z"
},
"Merchant Website": {
"ignoresTimeZone": null,
"description": "Visit Us Online",
"hideEmpty": false,
"formatType": "URL",
"uri": "https://www.dominos.co.uk/?vc=WNTRBLOG",
"fieldType": "linksModuleData",
"order": 1
},
"imageModulesData": {
"image": "https://s3.amazonaws.com/passtools_prod/1169167/images/834420d3cbf287f56c8be46806e58e23e8296e94_Android_Hero_1032x336_Opt1.png",
"ignoresTimeZone": null,
"imageDescription": "Logo Image",
"hideEmpty": false,
"formatType": "String",
"fieldType": "imageModulesData"
},
"Coupon Title": {
"col": 0,
"ignoresTimeZone": null,
"title.string": "Coupon",
"hideEmpty": false,
"row": 0,
"formatType": "String",
"fieldType": "titleModule",
"description.string": "25% Off Online "
}
},
"url": "https://wallet-api.urbanairship.com/v1/pass/47400533/download",
"updatedAt": "2018-10-25T19:13:14Z",
"tags": [],
"status": "installed"
}
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the fieldsModel contains fields nested inside module objects, fields are collapsed in pass requests and responses. The fieldType corresponds to the template field module (an object) that the field belongs to.
Aside from differences in field composition, and a lack of beacons, Google Wallet passes are very similar to Apple Wallet passes.
OBJECT PROPERTIES- createdAt string
The date and time when the item was created.
- externalId string
The external ID for the pass, returned only if you created the pass using an external ID.
- fields object
Contains all populated fields from the template. The
fieldTypewithin each object indicates themoduleit belonged to.While all fields take a similar shape, the response may contain different keys to represent the
OBJECT PROPERTIESvalueorlabelfrom the originating template field. This has to do with the way that Google Wallet interprets templates and passes.- offerModule object
Specific to google coupons, this module contains information about redeeming the coupon.
OBJECT PROPERTIES- endTime string
The expiration date for the offer.
- multiUseOffer boolean
Indicates whether the coupon/offer is available for multiple users or just a single user.
- provider string
The offer provider name.
- redemptionChannel string
Indicates whether the user can redeem the offer at a physical location or online.
Possible values:
online,instore,both,temporaryPriceReduction
- headers object<Google headers>
Fields appearing in the
headersobject for a Google pass template. Header fields typically follow the same model as other fields for Google Wallet templates and passes, but often have specificvalue,fieldType, andformatTypevalues. - id integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
- publicUrl object
A public URL from which users can download a pass.
For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify
type: singlein the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.
OBJECT PROPERTIES- installs integer
The number of users who have installed the pass from the URL specified in the
pathfield. - path string
The URL for the pass.
- type stringREQUIRED
Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.
Possible values:
single,multiple - used boolean
If true, a user has accessed the
pathURL.
- serialNumber string
- status string
Indicates whether a pass has been installed or not.
Possible values:
installed,not_been_installed Tags associated with the pass.
- uaEntityId string
- updatedAt string
The date and time when the item was last updated.
- url string
The URL for the pass.
Apple Wallet pass request
Example pass for Apple Wallet
{
"headers": {
"expirationDate": {
"value": "2014-08-20T09:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.example.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
],
"publicUrl": {
"type": "single"
}
}
A pass for Apple Wallet.
OBJECT PROPERTIES- beacons array
Beacons for an Apple pass.
- fields object
Fields for an Apple Wallet pass. Provide only the field objects and values you want to differentiate or personalize from the template.
- headers object
Headers on an Apple Wallet pass. Provide only the header objects and values you want to differentiate or personalize from the template. See Apple Template Headers for information about available header objects for Apple Wallet templates and passes.
OBJECT PROPERTIES- expirationDate string
May contain
valueandlabelfields.valueindicates the expiration date of the pass.labelcan be set to eithervalidorvoided, wherevalidindicates a non-expired pass andvoidedindicates that the pass is no longer accepted. - sharingStatus object
A
fielddetermining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as otherfields, you only need to set thevaluewithin the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.On iOS devices,
oneUserOneDeviceprohibits sharing ("sharingProhibited": true); all other values allow sharing.You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.
OBJECT PROPERTIES- changeMessage string
The message that appears when you update this field.
- value stringREQUIRED
Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting:
oneUserOneDeviceprohibits sharing; all other values allow sharing.Possible values:
multipleHolders,oneUserAllDevices,oneUserOneDevice
- locations array
A list of locations associated with a pass.
- nfc object
If your Apple certificate is NFC-enabled, and your terminals use Apple’s Value Added Services protocol, you can include this object in Loyalty passes to identify pass holders and provide their credentials over NFC.
OBJECT PROPERTIES- encryptionPublicKey stringREQUIRED
The public encryption key for NFC communications. Use a Base64 encoded X.509
SubjectPublicKeyInfostructure containing a ECDH public key for group P256. - message stringREQUIRED
The payload for an Apple Pay terminal, 64 bytes or less. Messages longer than 64 bytes are truncated.
- publicUrl object
A public URL from which users can download a pass.
For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify
type: singlein the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.
OBJECT PROPERTIES- installs integer
The number of users who have installed the pass from the URL specified in the
pathfield. - path string
The URL for the pass.
- type stringREQUIRED
Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.
Possible values:
single,multiple - used boolean
If true, a user has accessed the
pathURL.
- semantics object<Boarding pass semantics>
Apple boarding pass only, top-level semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within
fields. An array of tags associated with the pass.
- templateId integer
The identifier for the template. You can recall the template by ID in other operations.
Apple Wallet pass response
Example Apple Wallet pass response
{
"id": 12345,
"templateId": 123,
"createdAt": "2012-11-01 12:37:07.0",
"url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/888\/download",
"publicUrl": {
"path": "https:\/\/wallet-api.urbanairship.com\/v1\/download\/pass\/9c9c9c7d-c6b6-9c9c-9d2b-9c9c9c54c89c",
"used": false,
"type": "Single",
"installs": 0
},
"passFields": {
"sale": {
"changeMessage": "Hey %@, check out our new sale!",
"fieldType": "HEADER",
"value": "20%",
"label": "Percent off",
"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
}
]
}
A pass response includes both identifiers and the content of all fields on a pass.
All ofA pass for Apple Wallet.
- OBJECT PROPERTIES
- createdAt string
The date and time when the item was created.
- externalId string
The external ID for the pass, returned only if you created the pass using an external ID.
- id integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
- publicUrl object
A public URL from which users can download a pass.
For Google Wallet, the public URL deep-links to the Google Wallet store with credentials to download a pass, facilitating pass installation without a browser window. When creating Google Wallet passes, this field is required and you must specify
type: singlein the request to create a pass. If the request does not contain a Public URL, the operation will not return a URL and users will not be able to access the resulting pass.For Apple Wallet, this URL points to a .pkpass file. We recommend using a Public URL when creating Apple Wallet passes. If you do not provide a public URL, users will not be able to install the pass without the API key.
OBJECT PROPERTIES- installs integer
The number of users who have installed the pass from the URL specified in the
pathfield. - path string
The URL for the pass.
- type stringREQUIRED
Determines whether a user can access the link to install a pass one time or multiple times. The response indicates the number of times the publicUrl has been used to install a pass.
Possible values:
single,multiple - used boolean
If true, a user has accessed the
pathURL.
- serialNumber string
- status string
Indicates whether a pass has been installed or not.
Possible values:
installed,not_been_installed Tags associated with the pass.
- uaEntityId string
- updatedAt string
The date and time when the item was last updated.
- url string
The URL for the pass.
Flights and boarding passes
Schemas for creating flights and boarding pass adaptive links. A Boarding pass includes both flight information and an array of passengers.
Boarding pass Adaptive Link request
Example boarding pass Adaptive Link
{
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateExternalId": "android123ExtId",
"payload": {
"isEventTicketUpdatePermitted": false,
"flights": [
{
"flightExternalId": "flight123ExtId",
"fields": {
"flightNumber": { "value": "815" },
"airlineCode": { "value": "WN" },
"airlineName": { "value": "Southwest Airlines" },
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "25"
},
"boardingTime": { "value": "2018-07-30T08:35:00" },
"departureTime": { "value": "2018-07-30T09:00:00" },
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalTime": { "value": "2018-07-30T11:00:00" },
"flightStatus": { "value": "scheduled" }
},
"passGroups": ["sfo-pdx-20180730"],
"passengers": [
{
"adaptiveLinkExternalId": "abch3ExtId1",
"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": "abch3ExtId2",
"fields": {
"seatNumber": { "value": "13B" },
"confirmationCode": { "value": "E4583B" },
"passengerName": { "value": "SMITH/SALLY" },
"barcode_value": { "value": "12346" },
"barcodeAltText": { "value": "12346" }
}
},
{
"adaptiveLinkExternalId": "abch3ExtId2",
"fields": {
"seatNumber": { "value": "13C" },
"confirmationCode": { "value": "E4583B" },
"passengerName": { "value": "SMITH/SAM" },
"barcode_value": { "value": "12347" },
"barcodeAltText": { "value": "12347" }
}
}
]
}
]
}
}
A boarding pass adaptive link requires similar information to other adaptive link types, but the payload includes flight information and an array of passengers for each flight.
Like other adaptive links, you must provide the id or externalId of an
iOS or Android template.
- OBJECT PROPERTIES
- androidTemplateExternalId string
The custom identifier of the Google template for passes issued from this adaptive link.
- androidTemplateId integer
The Google template for passes issued from the adaptive link.
- availablePasses integer
The total number of passes that can be created from this link. If absent, the link supports 1,000,000 passes.
- iosTemplateExternalId string
The custom identifier of the Apple template for passes issued from the adaptive link, if assigned.
- iosTemplateId integer
The iOS template for passes issued from the adaptive link.
- isPersonalized boolean
If true, each request (when a recipient uses an adaptive link) generates a new pass. You can update any of the individual passes generated from the adaptive link. If you generate the adaptive link using any request parameters,
isPersonalizedis automatically set totrue.If false, only the first request generates a pass; subsequent requests generate a new instance of the same pass. When
isPersonalizedisfalse, you cannot update passes generated from an adaptive link by updating the adaptive link itself. Rather, you must use the Bulk Update Passes endpoint to push updates to the pass instances generated from the adaptive link. - landingPageUrl string
The address users are redirected to if their device type cannot be detected or they cannot install the pass for another reason.
- parameterEncoding string
When set, allows url-encoded parameters to set or modify values when creating passes from the adaptive link.
Possible values:
base64
- OBJECT PROPERTIES
- payload object
A boarding pass adaptive link object takes both flight and passenger information.
You can provide the
OBJECT PROPERTIESflightIdorflightExternalIdof an existing flight. Or, you can define a new flight using theflightsobject. If defining a new flight, you can provide aflightExternalId.- flights array
Each object in the array represents an event. Each event object must specify the
flightIdorflightExternalIdof an existing event, or contain thefieldsobject sufficient to create a new event.You can also provide the
eventExternalIdin conjunction with thefieldsobject to assign an eventExternalId to a new event. - isEventTicketUpdatePermitted boolean
True by default. If false, event information for existing events will not be updated as part of the POST call to the Adaptive Link API; a new event will still be created if it does not yet exist.
- isFlightUpdatePermitted boolean
True by default. If false, flight information for existing flights will not be updated as part of the POST call to the Adaptive Link API; a new flight will still be created if it does not yet exist.
Boarding pass Adaptive Link response
Example boarding pass response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"links": [
{
"status": 201,
"adaptiveLinkId": "abchd345678",
"adaptiveLinkExternalId": "abch3ExtId1",
"iosTemplateId": 12345,
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateId": 154321,
"androidTemplateExternalId": "android123ExtId",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345678/android",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"isPersonalized": "false",
"availablePasses": 1000000,
"ttlInDays": 30,
"flightId": 465,
"flightExternalId": "flight123ExtId",
"iosPassLinkId": "eb94e8e0-4353-4e0b-bfe9-cfd21c52a540",
"androidPassLinkId": "41c1ea48-f469-4968-b610-a98629ea19bc"
},
{
"status": 201,
"adaptiveLinkId": "abchd345Id2",
"adaptiveLinkExternalId": "abch3ExtId2",
"iosTemplateId": 12345,
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateId": 154321,
"androidTemplateExternalId": "android123ExtId",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2/android",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"isPersonalized": "false",
"availablePasses": 1000000,
"ttlInDays": 30,
"flightId": 465,
"flightExternalId": "flight123ExtId",
"iosPassLinkId": "5d370e0d-0aa9-45c3-b7ab-eff0a3d4995b",
"androidPassLinkId": "c60bd6c0-8f1e-4419-abb0-9f6fcb8a6fab"
},
{
"status": 201,
"adaptiveLinkId": "abchd345Id2",
"adaptiveLinkExternalId": "abch3ExtId2",
"iosTemplateId": 12345,
"iosTemplateExternalId": "ios123ExtId",
"androidTemplateId": 154321,
"androidTemplateExternalId": "android123ExtId",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/abchd345Id2/android",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"isPersonalized": "false",
"availablePasses": 1000000,
"ttlInDays": 30,
"flightId": 465,
"flightExternalId": "flight123ExtId",
"iosPassLinkId": "5d370e0d-0aa9-45c3-b7ab-eff0a3d4995b",
"androidPassLinkId": "c60bd6c0-8f1e-4419-abb0-9f6fcb8a6fab"
}
]
}
The boarding pass operations return responses like other adaptive links, with the addition of the identifier of the event and an HTTP status for each individual adaptive link.
Like other adaptive links, you must provide the id or externalId of an
iOS or Android template.
An adaptive link response includes URLs that users can access to detect and install a pass.
- OBJECT PROPERTIES
- flightExternalId string
An external, custom identifier for a flight. You can reference flights by
flightExternalIdrather than the 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 integer
A unique, auto-generated identifier for a flight.
When creating boarding passes, if you specify a flight by ID, you do not need to define the flight in the
fieldsobject. - status integer
The HTTP status code for the adaptive link operation.
Boarding pass semantics
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within fields.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
passengerNameandseats, that enhances passes. You can nest this object withinfields.For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.
Flight object
Example flight request object
{
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": { "value": "815" },
"airlineCode": { "value": "WN" },
"airlineName": { "value": "Southwest Airlines" },
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "25"
},
"boardingTime": { "value": "2018-07-30T08:35:00" },
"departureTime": { "value": "2018-07-30T09:00:00" },
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalTime": { "value": "2018-07-30T11:00:00" },
"flightStatus": { "value": "scheduled" }
}
}
A complete flight request object.
The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.
OBJECT PROPERTIES- fields objectOBJECT PROPERTIES
- actualArrivalTime object
The date and time when the flight actually lands. This field is normally populated in updates to the flight, as real-time information becomes available for the benefit of ticket holders.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- actualDepartureTime object
The date and time when the flight actually departs. This field is normally populated in updates to the flight, as real-time information becomes available.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- airlineAllianceLogo object
A URL for the airline alliance logo, if the airline belongs to an alliance.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
- value string
- airlineCode objectREQUIRED
The airline code.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- airlineLogo object
A URL for the airline logo, shown on the front of the pass.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
- value string
- airlineName objectREQUIRED
The airline name.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- arrivalAirport objectREQUIRED
The airport the flight arrives at.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- arrivalGate object
The gate that the flight arrives at.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- arrivalTerminal object
The terminal that the flight arrives at.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- arrivalTime object
The date and time the flight is scheduled to arrive at the
OBJECT PROPERTIESarrivalAirport.- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- boardingPolicy object
The boarding policy for the airline and flight. If unset, Google will use
OBJECT PROPERTIESzoneBased.- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
Possible values:
boardingPolicyOther,groupBased,zoneBased
- boardingTime object
The date and time when the flight boards.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- departureAirport objectREQUIRED
The airport that the flight departs from.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- departureGate object
The airport gate the flight departs from.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- departureTerminal object
The airport terminal the flight departs from.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- departureTime object
The date and time when the flight is scheduled to depart.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- flightNumber objectREQUIRED
The flight number.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
- flightStatus object
The status of the flight.
OBJECT PROPERTIES- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
Possible values:
active,cancelled,landed,redirected,scheduled
- seatingPolicy object
The seating policy for the airline and flight. If unset, Google will use
OBJECT PROPERTIEScabinBased.- label string
A label representing the field on the pass.
Field-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- value string
Possible values:
cabinBased,classBased,seatClassPolicyOther,tierBased
Top-level flight semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as
flightNumberandoriginalDepartureTime, that enhances passes. You can nest this object withinfields.- universalLinks object<Universal links>
Special web links containing JSON key-value pairs used by Wallet to render buttons in the relevant sections of the pass.
A list of key-value pairs that represents partner URLs.
- passGroups array[string]
An array of eventId or eventExternalId values representing a group. You can reference the group to make changes to all associated events.
You can set pass groups when creating an event or when creating an event ticket adaptive link.
Flight response
Example flight response object
{
"flightId": 465,
"flightExternalId": "flight123ExtId",
"projectId": "12345",
"projectExternalId": "project123ExtId",
"createdAt": "2018-07-05T09:12:32Z",
"updatedAt": "2018-07-05T09:12:32Z",
"passGroups": ["sfo-pdx-20180730"],
"fields": {
"flightNumber": {
"label": "Flight Number",
"value": "815"
},
"airlineCode": {
"label": "Airline Code",
"value": "WN"
},
"airlineName": {
"label": "Airline Name",
"value": "Southwest Airlines"
},
"departureAirport": {
"label": "San Francisco",
"value": "SFO"
},
"departureGate": {
"label": "Gate #",
"value": "25"
},
"boardingTime": {
"label": "Boarding Time",
"value": "2018-07-30T08:35:00"
},
"departureTime": {
"label": "Departure Time",
"value": "2018-07-30T09:00:00"
},
"arrivalAirport": {
"label": "Portland",
"value": "PDX"
},
"arrivalGate": {
"label": "Arrival Gate",
"value": ""
},
"arrivalTime": {
"label": "Arrival Time",
"value": "2018-07-30T11:00:00"
},
"flightStatus": {
"label": "Flight Status",
"value": "scheduled"
}
}
}
A complete flight response, including identifiers to reference the flight and the fields defined within the flight.
All ofA complete flight request object.
The presence or absence of fields in the flight object may slightly affect the design of boarding passes. See Google Wallet Boarding Pass Design for more information on rendering logic for Google Wallet Boarding Passes.
- OBJECT PROPERTIES
- createdAt string
The date and time when the item was created.
- flightId integer
A unique, auto-generated identifier for the flight. Use this ID to reference the flight in future operations.
- projectExternalId string
The identifier for the external project that the flight is associated with. Presently only if the project uses an external identifier.
- projectId string
The project the flight is associated with.
- updatedAt string
The date and time when the item was last updated.
Flight semantics object
Example flight semantics object
{
"airlineCode": "AP",
"flightNumber": 2214,
"originalBoardingDate": "2025-03-19T20:30:00-08:00",
"currentBoardingDate": "2025-03-19T20:59:00-08:00",
"originalDepartureDate": "2025-03-19T09:00:00-08:00",
"currentDepartureDate": "2025-03-20T09:30:00-08:00",
"originalArrivalDate": "2025-03-20T02:00:00-05:00",
"currentArrivalDate": "2025-03-20T02:00:00-05:00",
"departureAirportCode": "SFO",
"departureCityName": "San Francisco",
"departureLocationTimeZone": "America/Los_Angeles",
"departureAirportLocation": {
"latitude": 37.6191,
"longitude": 122.3816
},
"departureLocationSecurityPrograms": [
"tsaPreCheck"
],
"departureGate": "17B",
"departureTerminal": "2",
"destinationAirportCode": "JFK",
"destinationCityName": "New York",
"destinationLocationTimeZone": "America/New_York",
"destinationAirportLocation": {
"latitude": 40.6446,
"longitude": 73.7797
},
"destinationGate": "6",
"destinationTerminal": "1"
}
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as flightNumber and originalDepartureTime, that enhances passes. You can nest this object within fields.
- airlineCode string
The two-character IATA airline code.
- currentArrivalDate string
The ISO 8601 date-time the flight is currently scheduled to arrive.
- currentBoardingDate string
The ISO 8601 date-time the flight is currently scheduled to begin boarding.
- currentDepartureDate string
The ISO 8601 date-time the flight is currently scheduled to depart.
- departureAirportCode stringREQUIRED
The three-letter IATA airport code the flight is departing from.
- departureCityName stringREQUIRED
The name of the departure city.
- departureGate string
The gate number or letters of the departure gate.
- departureLocation object
The geographic coordinates of the transit departure location.
- departureLocationSecurityPrograms object
A list of security programs that exist in the departure airport.
Any ofSecurity program names.
- departureLocationTimeZone stringREQUIRED
The time zone for the departure location, such as America/Los_Angeles.
- departureTerminal string
The name or letter of the departure terminal.
- destinationAirportCode stringREQUIRED
The three-letter IATA airport code the flight is going to.
- destinationCityName stringREQUIRED
The name of the destination city.
- destinationGate string
The gate number or letters of the arrival gate.
- destinationLocation object
The geographic coordinates of the transit destination location.
- destinationLocationSecurityPrograms object
A list of security programs that exist in the destination airport.
Any ofSecurity program names.
- destinationLocationTimeZone stringREQUIRED
The time zone for the destination location, such as America/Los_Angeles.
- destinationTerminal string
The name or letter of the arrival terminal.
- flightNumber number
The one- to four-digit IATA flight number.
- loungePlaceIDs array[string]
A list of place IDs that reference the lounge locations.
- originalArrivalDate stringREQUIRED
The ISO 8601 date-time the flight is originally scheduled to arrive.
- originalBoardingDate string
The ISO 8601 date-time the flight is originally scheduled to begin boarding.
- originalDepartureDate string
The ISO 8601 date-time the flight is originally scheduled to depart.
Passenger semantics object
Example passenger semantics object
{
"passengerName": {
"givenName": "Foo",
"familyName": "Bar"
},
"boardingGroup": "3",
"passengerCapabilities": [
"priorityBoarding",
"carryOn",
"personalItem"
],
"passengerEligibleSecurityPrograms": [
"tsaPreCheck",
"tsaPrecheckTouchlessId"
],
"seats": [
{
"seatType": "Comfort+",
"seatRow": "23",
"seatNumber": "A"
}
],
"passengerServiceSSRs": [
"wheelChair"
],
"membershipProgramName": "Fleet Rewards",
"membershipProgramNumber": "12345",
"membershipProgramStatus": "Gold",
"priorityStatus": "Fleet Priority"
}
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data, such as passengerName and seats, that enhances passes. You can nest this object within fields.
- boardingGroup string
A group number for boarding.
- boardingSequenceNumber string
A sequence number for boarding.
- boardingZone string
A zone number for boarding.
- internationalDocumentsAreVerified boolean
Denotes whether the ticket/passenger has met all the requirements for international travel.
- internationalDocumentsVerifiedDeclarationName string
The affirmation string that is displayed if the passenger meets the requirements for international travel.
- membershipProgramName string
The name of a frequent flyer or loyalty program.
- membershipProgramNumber string
The ticketed passenger’s frequent flyer or loyalty number.
- membershipProgramStatus string
The ticketed passenger’s frequent flyer or loyalty program status.
- passengerAirlineSSRs array
A list of airline-specific special service requests.
- passengerCapabilities object<Passenger capabilities>
List of passenger capabilities.
- passengerEligibleSecurityPrograms object<Transit security programs>
A list of security programs that the passenger is eligible for.
Security program names.
- passengerInformationSSRs object<Passenger information SSRs>
A list of Special Service Requests (SSRs) information for passengers; supports any valid four-letter IATA SSR code in addition to those listed.
- passengerServiceSSRs object<Passenger service SSRs>
A list of Special Service Requests (SSRs) for passengers; supports any valid four-letter IATA SSR code in addition to those listed.
- priorityStatus string
Additional priority status the ticketed passenger holds.
- seats array
- ticketFareClass string
A localizable string that denotes the ticket fare class. This value displays as a badge on the boarding pass.
Passengers
Example array of passengers
{
"passengers": [
{
"adaptiveLinkExternalId": "abch3ExtId1",
"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": "abch3ExtId2",
"fields": {
"seatNumber": { "value": "13B" },
"confirmationCode": { "value": "E4583B" },
"passengerName": { "value": "SMITH/SALLY" },
"barcode_value": { "value": "12346" },
"barcodeAltText": { "value": "12346" }
}
},
{
"adaptiveLinkExternalId": "abch3ExtId2",
"fields": {
"seatNumber": { "value": "13C" },
"confirmationCode": { "value": "E4583B" },
"passengerName": { "value": "SMITH/SAM" },
"barcode_value": { "value": "12347" },
"barcodeAltText": { "value": "12347" }
}
}
]
}
An array of objects, each object representing a passenger/seat on a flight. Passengers are a part of the payload for boarding pass adaptive links.
Template objects
Template objects vary based on the vendor they’re intended for and the types of passes you want to create.
Optional fields for Google headers
Example Google header object with optional keys
{
"background_color": {
"ignoresTimeZone": null,
"changeMessage": null,
"label": "",
"hideEmpty": false,
"formatType": "String",
"value": "#006491",
"fieldType": "topLevel",
"required": false
}
}
Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
OBJECT PROPERTIES- changeMessage string
The message that appears when you update this field.
- hideEmpty boolean
If true, the field is hidden if empty.
- ignoresTimeZone boolean
if true, the date-time value in a field on an Apple Wallet pass is not offset to account for the pass recipient’s time zone. This may be helpful for things like boarding passes or events, where your times are set local to an airport or venue and should not change based on a user’s device. When applied to a non-date-time field or a Google template, this setting is ignored.
- label string
In most cases, you should not set a label for a Google template header. In responses, the label is typically an empty string.
- required boolean
Indicates whether or not the field is required on passes created from this template.
- textAlignment string
The alignment of text on the pass.
Possible values:
textAlignmentLeft,textAlignmentCenter,textAlignmentRight,textAlignmentNatural
Google Wallet template request
Example Google template request
{
"infoModuleData": {
"hexFontColor": "#666666",
"hexBackgroundColor": "#0096e1",
"Program ID": {
"label": "Program ID",
"value": "12345678",
"row": 0,
"col": 0,
"formatType": "String"
},
"Tier Name": {
"label": "Tier Name",
"value": "Silver",
"row": 0,
"col": 1,
"formatType": "String"
},
"Last Updated": {
"label": "Last Updated",
"value": "Five days ago",
"row": 1,
"col": 0,
"formatType": "String"
}
},
"headers": {
"barcode_type": {
"fieldType": "barcode",
"value": "",
"notShared": true
},
"barcode_value": {
"fieldType": "barcode",
"value": "",
"notShared": true
},
"barcode_label": {
"fieldType": "barcode",
"value": "",
"notShared": true
},
"barcode_encoding": {
"fieldType": "barcode",
"value": "",
"notShared": true
},
"barcodeAltText": {
"fieldType": "barcode",
"value": "",
"notShared": true
}
},
"textModulesData": {
"Program Details": {
"header": "Program Details",
"body": "Some Basic Text",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"linksModuleData": {
"Merchant Website": {
"description": "Merchant Website",
"uri": "http:\/\/www.example.com",
"order": 1,
"formatType": "URL"
}
},
"messageModule": {
},
"imageModulesData": {
},
"pointsModule": {
"Tier": {
"label": "Tier",
"value": 2,
"row": 0,
"col": 1,
"formatType": "Number",
"numberStyle": "PKNumberStyleDecimal"
},
"Points": {
"label": "Points",
"value": 1234,
"row": 0,
"col": 0,
"formatType": "Number"
}
},
"notAssigned": {
},
"titleModule": {
"image": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
"imageDescription": "Logo Image",
"Program Name": {
"label": "Program Name",
"value": "UA",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"vendor": "Google",
"projectType": "memberCard",
"type": "Loyalty1",
"vendorId": 2,
"deleted": "False",
"description": "description",
"name": "Adding Google"
}
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
All ofMeta information about templates; this object appears on all templates and identifies templates associated with a project.
Fields on a Google pass are organized into modules. Modules define how fields on the pass are organized and appear. Fields within each module are objects with a string names.
Apple Wallet template request
Example Apple Wallet template request
{
"headers": {
"logo_color": {
"formatType": 1,
"fieldType": "topLevel",
"value": "rgb(24,86,148)"
},
"icon_image": {
"formatType": 1,
"fieldType": "image",
"value": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png"
},
"logo_text": {
"formatType": 1,
"fieldType": "topLevel",
"value": "Logo Text"
},
"barcode_encoding": {
"formatType": 1,
"fieldType": "barcode",
"value": "iso-8859-1"
},
"suppress_strip_shine": {
"formatType": 1,
"fieldType": "topLevel",
"value": "true"
},
"logo_image": {
"formatType": 1,
"fieldType": "image",
"value": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-logo.png"
},
"foreground_color": {
"formatType": 1,
"fieldType": "topLevel",
"value": "rgb(255,255,255)"
},
"background_color": {
"formatType": 1,
"fieldType": "topLevel",
"value": "rgb(49,159,196)"
}
},
"fields": {
"Coupon": {
"formatType": "String",
"changeMessage": "Enjoy %@ off your next order!",
"order": 1,
"fieldType": "primary",
"textAlignment": "textAlignmentRight",
"value": "20%",
"label": "coupon",
"required": false,
"hideEmpty": true
},
"SiteAddress": {
"formatType": "Number",
"changeMessage": "New stuff, just for you at %@",
"order": 2,
"textAlignment": "textAlignmentCenter",
"fieldType": "secondary",
"value": "https://www.example.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"description": "Description",
"name": "Loyalty Card",
"disabled": "False"
}
A complete iOS template includes template meta information, headers, and fields.
All ofMeta information about templates; this object appears on all templates and identifies templates associated with a project.
The iOS template
headersobject can contain the following objects. Each object has aformatType,fieldType, andvalue.formatTypeis always1, indicating that thevalueis a string.fieldTypeistopLevel— a text or color value on the top-front of the pass,image, orbarcode.valueis the default value for the header field.
Defines fields on iOS templates and subsequent passes generated from the template.
Apple Pass personalization requirements
Example Apple loyalty personalization requirements
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}
- description stringREQUIRED
A brief description of the rewards program that the recipient is signing up for. The description appears on the signup sheet, under the personalization logo.
- imageUrl string
The URL of the image you want to appear at the top of the signup form. This image must be a 150 x 40 point PNG image.
- requiredPersonalizationFields array[string]REQUIRED
An array of strings representing fields that a customer must provide to sign up for your rewards/loyalty program. Some keys populate multiple fields in the personalization callback or on passes.
- name - requires the user to enter their
fullName. This also populates thegivenNameandfamilyNamefields on passes and/or personalization callbacks. - postalCode - prompts the user for their postal code. This populates both
postalCodeandISOCountryCodeon passes and/or personalization callbacks. - emailAddress - requires the user’s email address.
- phoneNumber - requires the user’s phone number.
- name - requires the user to enter their
- termsAndConditions string
The terms and conditions for the reward program. If present, this information appears after the user enters their personal information and taps Next. The user then has the option to agree to the terms, or to cancel the signup process.
Project objects
Request and Response schemas for /project endpoints.
Project response
Example project response
{
"updatedAt": "2013-06-27T20:55:06.000Z",
"id": "12345",
"contextId":"myvWLcm8QN3Iq2K4fXT-Bv",
"templates": [
{
"vendor": "Apple",
"projectType": "loyalty",
"projectId": "12345",
"type": "Store Card",
"vendorId": "1",
"deleted": "False",
"id": "1234",
"updatedAt": "2013-06-27T20:58:05.000Z",
"description": "Template 1",
"createdAt": "2013-06-27T20:51:09.000Z",
"name": "Template 1",
"disabled": "False"
}
],
"description": "Aztec Barcode",
"createdAt": "2013-06-27T20:51:02.000Z",
"settings": {
"barcode_alt_text": "123456789",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_label": "Member ID",
"barcode_type_text": "Aztec",
"barcode_type": "aztec"
},
"name": "Aztec Barcode",
"projectType": "loyalty"
}
A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.
All ofA project request determines the type of passes you can create and the types of barcode your passes will use.
- OBJECT PROPERTIES
- contextId string
Append this value to
go.urbanairship.com/projects/to access your project. - createdAt string
The date and time when the item was created.
- externalId string
The custom, external identifier of the project. This key only appears if you assigned an external ID to the project.
- id integer
The identifier for the project, used to reference the project in other payloads.
- templates array
An array of templates belonging to the project. When creating a new project, this array is empty.
- updatedAt string
The date and time when the item was last updated.
Project request
Example project request
{
"name": "Aztec Barcode",
"projectType": "loyalty",
"description": "Aztec Barcode",
"settings": {
"barcode_alt_text": "123json=456789",
"barcode_label": "Member ID",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_type": "pdf417"
}
}
A project request determines the type of passes you can create and the types of barcode your passes will use.
OBJECT PROPERTIES- description stringREQUIRED
A description for the project.
- name stringREQUIRED
The name of your project.
- projectType stringREQUIRED
The type of pass the template supports; matches the
typesetting for the parent project.Possible values:
memberCard,coupon,boardingPass,eventTicket,generic,loyalty,giftCard - settings object
Contains barcode information for the project.
OBJECT PROPERTIES- barcode_alt_text string
Alternate text for the barcode. This text assists the user if they hover over the barcode or the barcode doesn’t render.
- barcode_default_value string
The default value for the barcode. If you do not set a new value when creating a pass, the pass will use this value.
- barcode_encoding string
Barcode encoding is set at the project level and inherited by templates and passes.
Possible values:
iso-8859-1 - barcode_label string
The title of the barcode; appears above the barcode in templates. You can change this value when creating or updating templates or passes.
- barcode_type string
The format of the barcode supported by the project and resulting passes.
Possible values:
pdf417,aztec,code128,qr,upc-a,ean-13,code-39
Callback object
Example callback object
{
"passId": 149440311,
"templateId": 158327,
"serialNumber": "3388000000005047792.158327_92a3e4d1-5110-3aca-a26e-fb21618aa5f2_149440311",
"createdAt": "2020-09-11T22:47:22.000Z",
"updatedAt": "2020-09-11T22:47:22.000Z",
"externalId": "coolexample",
"platform": "android"
}
- createdAt string
The date-time when the pass was created.
- externalId string
The external ID for the pass, if set.
- passId integer
The ID of the pass installed or uninstalled.
- platform string
The platform on which the pass is installed.
Possible values:
android,ios - serialNumber string
The serial number of the pass. This string is generated by the vendor — Apple or Google.
- templateId integer
The ID of the template the pass was created from.
- updatedAt string
The date-time when the pass was last updated.
Callback personalization object
Example callback with personalization object
{
"passId": "12345",
"templateId": "25035",
"serialNumber": "6779a823-7c8f-4145-a640-c688069a3465",
"createdAt": "2022-01-23T20:46:50Z",
"platform": "ios",
"personalizationInfo": {
"fullName": "John LastName",
"givenName": "John",
"familyName": "LastName",
"emailAddress": "test@example.com",
"postalCode": "95051",
"ISOCountryCode": "US",
"phoneNumber": "408-409-1234"
}
}
You must add personalization requirements to Apple templates before users can personalize passes created from them.
All of- OBJECT PROPERTIES
- personalizationInfo object
Certificate object
Example Apple certificate response
{
"id": "40adce15-5c52-479d-8620-54c21cd851a6",
"vendor": "Apple",
"baseName": "pass.com.myName.test",
"name": "editable name",
"comment": "something about this cert",
"teamIdentifier": "9M8MY376H5",
"nfcSupport": false,
"enabled": false,
"createdAt": "2018-05-26T23:23:21Z",
"updatedAt": "2019-05-26T22:23:21Z",
"expired": false,
"validityStart": "2018-05-26T23:45:00Z",
"validityEnd": "2019-05-26T23:45:00Z",
"templates": [
{"id": 123,"name": "templateName1"},
{"id": 221,"name": "templateName2"}
]
}
- baseName string
- certificate string
A base64-encoded string of the p12 certificate with the private key.
- comment string
A description for the certificate.
- createdAt string
The date and time when the item was created.
- default boolean
If true, the certificate is the default for new projects. If you have multiple certificates and set a new default to
true, the current default is set tofalse. - enabled boolean
Indicates whether or not the certificate is in use.
- expired boolean
If true, the certificate has expired and cannot be used to generate new passes.
- name string
A name for the certificate.
- nfcSupport boolean
If true, the certificate supports passes that can make use of NFC.
- password string
The password for the p12 file, if the certificate was exported with a password.
- teamIdentifier string
- updatedAt string
The date and time when the item was last updated.
- vendor string
The vendor of the certificate.
Possible values:
Apple
Pass field updates
Example update to a field called "Coupon"
{
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
}
}
When updating a field on a pass or an adaptive link, you need only provide the following items. You cannot update the position of the field or other information held by the template — only the field label, value, and the message the user receives when their pass is updated.
OBJECT PROPERTIES- changeMessage string
The message that appears when you change the value or label for a field. Use
%@to pass variables to the field. - label string
The field label, usually represented as a title on the pass. Only provide the label if you want to use a different label than is provided by the template.
Field-level semantics.
For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within
fields.- value stringREQUIRED
The default value for the field.
Google headers
Example Google headers
{
"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
}
}
}
Fields appearing in the headers object for a Google pass template. Header fields typically follow the same model as other fields for Google Wallet templates and passes, but often have specific value, fieldType, and formatType values.
- background_color object
Sets the background color for the pass.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Set to
topLevelforcolorandtextheaders.Possible values:
topLevel - value string
The
colorobjects take an rgb value in the formatrgb(255, 255, 255).
- background_image object
A background image for the pass.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
The URL for the header image.
- barcodeAltText object
Alternate text displayed below the barcode.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
The alternate text for the barcode on the template.
- barcode_encoding object
The encoding format for the barcode.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
Presently,
iso-8859-1is the only supported value.Possible values:
iso-8859-1
- barcode_type object
The type of barcode supported by the template. This value must be the same as the
All ofbarcode_typeset at the project level.Header objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
The format of the barcode supported by the project and resulting passes.
Possible values:
pdf417,aztec,code128,qr,upc-a,ean-13,code-39
- barcode_value object
The default value for the barcode used by the template.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
This value is a default for the barcode. You may set a new or personalized value when creating adaptive links or passes.
The footer image for a template.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
The URL for the header image.
- foreground_color object
Sets the foreground color for the template.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Set to
topLevelforcolorandtextheaders.Possible values:
topLevel - value string
The
colorobjects take an rgb value in the formatrgb(255, 255, 255).
- header object
Sets the generic pass header. Required for the generic pass type.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Set to
topLevelfortextheaders.Possible values:
topLevel - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
Header text field.
- icon_image object
The icon image for the template.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
The URL for the header image.
- logo_image object
Specifies the template logo image.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
The URL for the header image.
- logo_text object
Sets the text under the logo image.
OBJECT PROPERTIES- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
The alternate text for the
logo_image.
- sharingStatus object
A
fielddetermining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as otherfields, you only need to set thevaluewithin the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.On iOS devices,
oneUserOneDeviceprohibits sharing ("sharingProhibited": true); all other values allow sharing.You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.
OBJECT PROPERTIES- changeMessage string
The message that appears when you update this field.
- value stringREQUIRED
Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting:
oneUserOneDeviceprohibits sharing; all other values allow sharing.Possible values:
multipleHolders,oneUserAllDevices,oneUserOneDevice
- strip_image object
The image residing in the barcode strip.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
The URL for the header image.
- subheader object
Sets the optional generic pass subheader.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Set to
topLevelfortextheaders.Possible values:
topLevel - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
Header text field.
- suppress_strip_shine object
Determines whether or not to suppress the strip shine effect on barcodes.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value boolean
- thumbnail_image object
An object containing the URL for the thumbnail image.
All ofHeader objects for Google Wallet templates use many of the same keys as fields on the template/pass. Populate these keys as necessary. Template responses include these keys with their default values.
- OBJECT PROPERTIES
- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType string
Indicates that the field takes a string value. While the
formatTypefor non-header fields can be another data type, header fields always take string values.In general, you do not have to set this value. Airship can determine the
formatTypefrom thefieldType, and objects in theheadersarray are always String types.Possible values:
String - value string
The URL for the header image.
Google fields
Example Google fields
{
"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"
}
},
"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.example.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"
}
}
}
Fields on a Google pass are organized into modules. Modules define how fields on the pass are organized and appear. Fields within each module are objects with a string names.
OBJECT PROPERTIES- acctModule object
Information associated with an account or membership. These are typically items like the
accountIdLabelon Loyalty cards orbalanceitems on a gift card. - headers object<Google headers>
Google template headers define barcode and top-level information for passes.
Fields appearing in the
headersobject for a Google pass template. Header fields typically follow the same model as other fields for Google Wallet templates and passes, but often have specificvalue,fieldType, andformatTypevalues. - imageModulesData object
Contains an image on the pass outside the header.
- infoModuleData object
Info module
- linkModulesData object
Contains links including URLs, phone numbers, and email addresses, that you want to make available on the pass. This module typically appears at the bottom of the pass.
- offerModule object
Specific to google coupons, this module contains information about redeeming the coupon.
OBJECT PROPERTIES- endTime string
The expiration date for the offer.
- multiUseOffer boolean
Indicates whether the coupon/offer is available for multiple users or just a single user.
- provider string
The offer provider name.
- redemptionChannel string
Indicates whether the user can redeem the offer at a physical location or online.
Possible values:
online,instore,both,temporaryPriceReduction
- pointsModule object
Contains information related to
pointsthat pass users accrue or spend. This module is typically used on loyalty passes. - textModulesData object
Contains text information for a pass. The text module typically has information in a header-body format.
- titleModule object
Contains title and header information specific to each pass type (as opposed to common items held within
headers). These are items typically referenced byclassin Google pass designs.
iOS fields
Example iOS field
{
"fields": {
"Coupon": {
"formatType": "String",
"changeMessage": "Enjoy %@ off your next order!",
"order": 1,
"fieldType": "primary",
"textAlignment": "textAlignmentRight",
"value": "20%",
"label": "coupon",
"required": false,
"hideEmpty": true
}
}
}
Defines fields on iOS templates and subsequent passes generated from the template.
OBJECT PROPERTIES- fields object
All non-header fields on an iOS template sit inside this object.
iOS template headers
Example iOS headers
{
"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)"
}
}
}
The iOS template headers object can contain the following objects. Each object
has a formatType, fieldType, and value.
formatTypeis always1, indicating that thevalueis a string.fieldTypeistopLevel— a text or color value on the top-front of the pass,image, orbarcode.valueis the default value for the header field.
- background_color object
Sets the background color for the pass.
OBJECT PROPERTIES- fieldType string
Set to
topLevelforcolorandtextheaders.Possible values:
topLevel - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The
colorobjects take an rgb value in the formatrgb(255, 255, 255).
- background_image object
A background image for the pass.
OBJECT PROPERTIES- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The URL for the header image.
- barcodeAltText object
Alternate text displayed below the barcode.
OBJECT PROPERTIES- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The alternate text for the barcode on the template.
- barcode_encoding object
The encoding format for the barcode.
OBJECT PROPERTIES- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
Presently,
iso-8859-1is the only supported value.Possible values:
iso-8859-1
- barcode_type object
The type of barcode supported by the template. This value must be the same as the
OBJECT PROPERTIESbarcode_typeset at the project level.- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The format of the barcode supported by the project and resulting passes.
Possible values:
pdf417,aztec,code128,qr,upc-a,ean-13,code-39
- barcode_value object
The default value for the barcode used by the template.
OBJECT PROPERTIES- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
This value is a default for the barcode. You may set a new or personalized value when creating adaptive links or passes.
The footer image for a template.
OBJECT PROPERTIES- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The URL for the header image.
- foreground_color object
Sets the foreground color for the template.
OBJECT PROPERTIES- fieldType string
Set to
topLevelforcolorandtextheaders.Possible values:
topLevel - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The
colorobjects take an rgb value in the formatrgb(255, 255, 255).
- icon_image object
The icon image for the template.
OBJECT PROPERTIES- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The URL for the header image.
- logo_color object
Specifies the color of the logo on the template.
OBJECT PROPERTIES- fieldType string
Set to
topLevelforcolorandtextheaders.Possible values:
topLevel - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The
colorobjects take an rgb value in the formatrgb(255, 255, 255).
- logo_image object
Specifies the template logo image.
OBJECT PROPERTIES- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The URL for the header image.
- logo_text object
Sets the text under the logo image.
OBJECT PROPERTIES- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The alternate text for the
logo_image.
- sharingStatus object
A
fielddetermining whether passes can be shared across users, devices, or not at all. By default, there are no restrictions with regard to users or devices (multipleHolders). While this setting uses the same format as otherfields, you only need to set thevaluewithin the object. Most other keys are irrelevant this setting, even though they appear in responses; this field should not be visible on passes, so you should not populate label, order, etc.On iOS devices,
oneUserOneDeviceprohibits sharing ("sharingProhibited": true); all other values allow sharing.You can override the template setting on Apple Wallet passes. If you set this field in an adaptive link payload, it will only apply to Apple Wallet passes resulting from the adaptive link; Google Wallet passes will always use the sharing setting set at the template level.
OBJECT PROPERTIES- changeMessage string
The message that appears when you update this field.
- value stringREQUIRED
Determines whether a pass supports sharing across users, devices, or both. iOS interprets this as a boolean setting:
oneUserOneDeviceprohibits sharing; all other values allow sharing.Possible values:
multipleHolders,oneUserAllDevices,oneUserOneDevice
- strip_image object
The image residing in the barcode strip.
OBJECT PROPERTIES- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The URL for the header image.
- suppress_strip_shine object
Determines whether or not to suppress the strip shine effect on barcodes.
OBJECT PROPERTIES- fieldType string
Set to
barcodefor all barcode headers.Possible values:
barcode - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value boolean
- thumbnail_image object
An object containing the URL for the thumbnail image.
OBJECT PROPERTIES- fieldType string
Indicates that the
valueis an image.Possible values:
image - formatType integer
For iOS, a value of
1indicates that theformatTypefor the field is a string.Possible values:
1 - value string
The URL for the header image.
Apple template header object
An object in headers for an iOS template or pass contains the following items.
- fieldType string
The type of field for the iOS header.
Possible values:
topLevel,image,barcode - formatType integer
Indicates that the
formatTypefor the field is a string.Possible values:
1 - value string
The default value for the field/header. While the value is always a string, it takes on a different format based on the
fieldTypeand purpose.
Location object
Example location object
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
Represents a location on a pass or an adaptive link.
Place objects in the locations array to add location information to passes and templates. Updating locations on a pass or template will replace all locations on that pass; if you want to add to the locations on a pass, you must provide all locations already included on the pass and any additional locations you want to add.
Apple Wallet supports up to 10 locations per pass. If you exceed this limit for an iOS pass, we will use the 10 locations nearest to a user (located by IP address) when they install the pass.
OBJECT PROPERTIES- city string
The location city.
- country string
The country abbreviation or name.
- latitude numberREQUIRED
The latitude of the location.
- longitude numberREQUIRED
The longitude of the location.
- region string
The region or state name.
- regionCode string
The region or zip code.
- relevantText string
An optional value shown as lock screen text for iOS when the device is close to this location.
- streetAddress1 string
The first line of the location address.
- streetAddress2 string
The second line of the location address.
Pagination object
Example list pagination
{
"pagination": {
"order": "id",
"page": 1,
"start": 0,
"direction": "DESC",
"pageSize": 10
}
}
Contains information about pagination, according to your query parameters.
OBJECT PROPERTIES- direction string
The direction of results, ascending, or descending.
Possible values:
ASC,DESC - order string
The key in the result set that you want to order results by. Defaults to
id. - page integer
The page you are on. Multiply by the page size to determine the result set on the page.
- pageSize integer
The number of results per page.
- start integer
The first result on the page; results begin with 0.
Passenger capabilities
List of passenger capabilities.
Passenger information SSRs
A list of Special Service Requests (SSRs) information for passengers; supports any valid four-letter IATA SSR code in addition to those listed.
Passenger name object
OBJECT PROPERTIES- familyName string
The person’s family name or last name.
- givenName string
The person’s given name; also called the forename or first name in some countries.
- middleName string
The person’s middle name.
- namePrefix string
The prefix for the person’s name, such as “Dr”.
- nameSuffix string
The suffix for the person’s name, such as “Junior”.
- nickname string
The person’s nickname.
- phoneticRepresentation string
The phonetic representation of the person’s name.
Passenger service SSRs
A list of Special Service Requests (SSRs) for passengers; supports any valid four-letter IATA SSR code in addition to those listed.
Schedule update object
Scheduled pass update
{
"name": "New Offer Update",
"schedule": {
"scheduled_time": "2017-04-10T18:45:00"
},
"update": {
"audience": {
"tag": "TZ_ET"
},
"pass": {
"fields": {
"primary1": {
"value": "$20 Off"
},
"secondary1": {
"value": "Mega Offer"
}
}
},
"template": "12345"
}
}
Specifies updates to passes or adaptive links at a particular date and time.
OBJECT PROPERTIES- name string
A name for the schedule.
- schedule objectOBJECT PROPERTIES
- scheduled_time string
The ISO 8601 inclusive date, optionally including an offset, e.g., 2007-03-01T13:00:00+08:00. The value will be converted and stored as UTC.
- update object
The updates you want to make to an
OBJECT PROPERTIESaudienceorpass, generated from atemplatewithin the project. Cannot also use the “notify” object when using “update”.- audience object<Audience selector>
Determines the passes you want to target.
- pass objectOBJECT PROPERTIES
- fields object
- url string
A URL to get the schedule object.
Passenger seat object
Seating information, including cabin class.
OBJECT PROPERTIES- seatAisle string
The aisle that contains the seat.
- seatDescription string
A description of the seat, such as a flat bed seat.
- seatIdentifier string
The identifier code for the seat.
- seatLevel string
The level that contains the seat.
- seatNumber string
The number of the seat.
- seatRow string
The row that contains the seat.
- seatSection string
The section that contains the seat.
- seatSectionColor string
A color associated with identifying the seat, specified as a CSS-style RGB triple, such as
rgb(23, 187, 82). - seatType string
The type of seat, such as reserved seating.
Transit security programs
Security program names.
Segment selector
Segment selector
{
"and": [
{
"tag": "TZ_PST"
},
{
"not": {
"tag": "TZ_ET"
}
}
]
}
Boolean tag selectors specifying a group of passes. You can nest AND and OR selectors.
AND selector
OBJECT PROPERTIES- and array
OR selector
OBJECT PROPERTIES- or array
- object
NOT selector
General template headers
Example template headers
{
"vendor": "Google",
"projectType": "memberCard",
"type": "Loyalty1",
"vendorId": 2,
"deleted": "False",
"description": "description",
"name": "Adding Google"
}
Meta information about templates; this object appears on all templates and identifies templates associated with a project.
OBJECT PROPERTIES- deleted boolean
If true, the template is deleted. You can no longer create passes from this template.
- description string
A description for the template.
- disabled boolean
If true, the template is disabled; you cannot create new passes for this template until you update the template and enable it again.
- expiryInfo object
Determine when passes generated from the template should expire.
One of- Expire on a date object
Set the specific expiration date for passes generated from this template. Passes expire at 12:00 AM on the date you provide.
OBJECT PROPERTIES- expiryDate string
The date when passes expire.
- expiryTimeZone string
Passes expire at 12:00 AM in the time zone you set.
- Expire after object
Expire passes generated from this template after the specified number of minutes after creation.
OBJECT PROPERTIES- expiryDuration integer
The number of days after creation that passes will expire.
- Never expire object
Passes generated from the template will never expire.
OBJECT PROPERTIES- expireNever string
Any string value (or null) will prevent passes generated from this template from expiring.
- name stringREQUIRED
The name of the template.
- projectId integer
The ID of the Wallet project.
- projectType string
The type of pass the template supports; matches the
typesetting for the parent project.Possible values:
memberCard,coupon,boardingPass,eventTicket,generic,loyalty,giftCard - type string
The type of pass the template supports. This value corresponds to the
projectType.Possible values:
memberCard,coupon,boardingPass,eventTicket,generic,loyalty,giftCard - vendor stringREQUIRED
The device vendor the template is designed for.
Possible values:
Apple,Google - vendorId integerREQUIRED
Corresponds to the
vendorthe template supports.1indicates an Apple template;2indicates a Google template.Possible values:
1,2
Universal links
A list of key-value pairs that represents partner URLs.
OBJECT PROPERTIES- accessibilityURL string
The URL for special assistance.
- bagPolicyURL string
The URL for the bag policy information.
- changeSeatURL string
The URL for seat change.
- entertainmentURL string
The URL for inflight entertainment.
- managementURL string
The URL for managing the reservation.
- orderFoodURL string
The URL for ordering a meal.
- purchaseAdditionalBaggageURL string
The URL for adding/purchasing additional bags.
- purchaseLoungeAccessURL string
The URL for purchasing lounge access.
- purchaseWifiURL string
The URL for purchasing inflight Wi-Fi.
- registerServiceAnimalURL string
The URL for registering a service animal.
- reportLostBagURL string
The URL for reporting a lost bag.
- requestWheelchairURL string
The URL for requesting a wheelchair.
- transitProviderEmail string
The URL for the airline email address.
- transitProviderPhoneNumber string
The URL for the airline phone number.
- transitProviderWebsiteURL string
The URL for the airline website.
- upgradeURL string
The URL for upgrading a seat or fare.