Wallet API
Airship’s REST API for Mobile Wallet projects. Use this API to create Apple Wallet and Google Wallet passes for your customers.
Libraries
Airship maintains open source server libraries to support your integrations with our APIs in multiple languages. Click below for library documentation.
Introduction
The Wallet API provides programmatic access to Airship Wallet service, where you can create passes for Apple Wallet and Google Wallet. Passes are:
- Created from templates within a project. The project determines the types of templates and passes you create; your templates determine the style and default data for your passes.
- Distributed as links—When creating a pass or an adaptive link, you are creating a link. Users tap this link (or scan a QR code representing the link, etc.) to install the pass on their device.
- Customizable—Add relevant data to your users when they install your pass.
- Updatable with relevant field and value changes. After users install your passes, you can update passes with relevant field and values so your users’ passes are always up to date.
For a better understanding of Airship Wallet projects and passes, see How mobile wallet works.
See the Getting Started Guide for help setting up an Airship Wallet project.
API Request Format
All API requests are HTTP requests. For all requests with a body, the body may be in JSON
format or other formats like CSV as specified for the endpoint. The proper Content-Type for
JSON is application/json and the proper content type for CSV is text/csv.
Date/Time Format
All date/time values are represented according to ISO 8601 in UTC.
A T separator is preferred but not required. It will be included in all date/time values generated by the API.
Example: 2023-01-28T15:00-05:00
Security
- Our APIs only work under 2048-bit HTTPS encrypted connections to ensure your data is private from client to server connections.
- Access is authenticated through a unique secret API key which we provide to you in your Wallet dashboard. It is your responsibility to keep this key well-guarded, as it represents your identity.
- You will use your own Apple Pass Type Certificate or Google Pay certificate to sign production passes.
Specifying a version
The current version of the Wallet API is 1.2. The versioning for the Wallet API is currently distinct from the versioning for the Airship Engage API.
Always specify the version of the API you want to use by adding an HTTP header called
Api-Revision. The value of that header should be in the format x.y where x is the API version and y the sub-revision. For instance, 1.2 is for the /v1 API, revision 2.
External IDs
Most endpoints support an externalId parameter in the path. While all assets
within this API typically have an internal id, you can use the externalId parameter to grant custom identifiers to your assets — projects, templates, passes, etc. These identifiers can make your assets more recognizable and help you integrate with an external application or system.
If you want to use external IDs, you should use them for all assets — projects, templates, passes, etc.
In general you can support external IDs by appending /id/{externalId} to an endpoint path that would either take or generate a standard id.
Base URL
Select the domain associated with your Airship project.
- The North American base URL for Wallet endpoints, including the API major version number. In addition to the major version, all requests must include an
Api-Revisionheader, with a more specific version number, e.g.,1.2. - The European base URL for Wallet endpoints, including the API major version number. In addition to the major version, all requests must include an
Api-Revisionheader, with a more specific version number, e.g.,1.2. - The deprecated base URL for Wallet (formerly known as Reach) endpoints. Use
https://wallet-api.urbanairship.com/v1instead.
Authentication
HTTP Authentication
Basic AuthAll 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
Example request
GET /v1/project HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"projects":[
{
"updatedAt": "2013-06-27T20:55:06.000Z",
"id": "12345",
"description": "Aztec Barcode",
"createdAt": "2013-06-27T20:51:02.000Z",
"contextId": "myvWKam4QN9Iu2K2fXK-Bd",
"templates": [
],
"settings": {
"barcode_alt_text": "123456789",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_label": "Member ID",
"barcode_type_text": "Aztec",
"barcode_type": "aztec"
},
"name": "Aztec Barcode",
"projectType": "loyalty"
},
{
"updatedAt": "2013-06-27T01:38:21.000Z",
"id": "12346",
"description": "Apple Templates",
"createdAt": "2013-06-26T18:43:07.000Z",
"contextId": "myvULam4QN3Iu2K4fXK-Bf",
"templates": [
],
"settings": {
"barcode_alt_text": "123456789",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_label": "Member ID",
"barcode_type": "pdf417"
},
"name": "Apple Templates",
"projectType": "loyalty"
}
],
"count": 89,
"pagination": {
"order": "id",
"page": 1,
"start": 0,
"direction": "DESC",
"pageSize": 10
}
}GET /project
List the projects belonging to you.
Security:
query PARAMETERSpageSize : Integer
The number of results per page. Defaults to 10.
page : Integer
The page of the search you want to return.
order : String
Determines the order of results. Defaults to
id.Possible values:
id,name,createdAt,updatedAtdirection : String
The direction of the result set, ascending or descending. Defaults to
DESC.Possible values:
ASC,DESC
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
An array of projects belonging to you.
RESPONSE BODYContent-Type: application/json; charset=utf-8
OBJECT PROPERTIEScount : String
The total number of results.
pagination : Pagination object
Contains information about pagination, according to your query parameters.
projects : Array [Project response]
Create project
Example request
POST /v1/project HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"name": "Aztec Barcode",
"projectType": "loyalty",
"description": "Aztec Barcode",
"settings": {
"barcode_alt_text": "123json=456789",
"barcode_label": "Member ID",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_type": "pdf417"
}
}Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"updatedAt": "2013-07-01T19:57:36.190Z",
"id": "12345",
"contextId":"nEkzVdIcTP2eNqP1--xQ_A",
"templates": [
],
"description": "Aztec Barcode",
"createdAt": "2013-07-01T19:57:36.190Z",
"settings": {
"barcode_alt_text": "123json=456789",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_label": "Member ID",
"barcode_type": "pdf417"
},
"name": "Aztec Barcode",
"projectType": "loyalty"
}POST /project
Create an empty project. Your project is based around the type of passes you want to create and the type of barcode you will include on your passes.
The response includes an id and contextId. Use these values to access your project via the API and dashboard, respectively.
See also Create project with external ID.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Request Body
Create a project. Your project is based around a pass type and your certificates.
Content-Type: application/json; charset=utf-8
Project request
A project request determines the type of passes you can create and the types of barcode your passes will use.
Responses
200
Create a project. Your project is based around a pass type and your certificates.
RESPONSE BODYContent-Type: application/json; charset=utf-8
A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.
Duplicate project
Example request
POST /v1/project/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
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/id/67890 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response with external ID
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"
}POST /project/duplicate/{projectId}
Duplicate a project by ID. The duplicate project will be named “Copy of [ProjectName]” and have a new id but will otherwise use the same settings and templates as the original project. The response payload returns the same information as a Get Project call, with new identifiers for the new project.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The 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 BODYContent-Type: application/json
A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.
Create project with external ID
Example request
POST /v1/project/id/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
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"
}POST /project/id/{externalId}
Create a project with a custom identifier. Your project is based around the type of passes you want to create and the type of barcode you will include on your passes. It is a container for your templates and passes.
The response includes an id and contextId. Use these values to access your project via the API and dashboard, respectively.
See also Create project.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
externalId : StringREQUIRED
The custom/external ID you want to use for your project.
Request Body
Create a project. Your project is based around a pass type and your certificates.
Content-Type: application/json; charset=utf-8
Project request
A project request determines the type of passes you can create and the types of barcode your passes will use.
Responses
200
Create a project. Your project is based around a pass type and your certificates.
RESPONSE BODYContent-Type: application/json; charset=utf-8
A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.
Get project
Example request
GET /v1/project/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
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/id/myProject HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response with external ID
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"updatedAt": "2013-06-27T20:55:06.000Z",
"externalId": "myProject",
"id": "12345",
"description": "Aztec Barcode",
"createdAt": "2013-06-27T20:51:02.000Z",
"contextId": "myvWKam4QN9Iu2K2fXK-Bd",
"templates": [
],
"settings": {
"barcode_alt_text": "123456789",
"barcode_default_value": "123456789",
"barcode_encoding": "iso-8859-1",
"barcode_label": "Member ID",
"barcode_type_text": "Aztec",
"barcode_type": "aztec"
},
"name": "Aztec Barcode",
"projectType": "loyalty"
}GET /project/{projectId}
Get the project with the specified id. The response includes information about the project (set when Creating a Project) and an array of templates associated with the project. The templates array contains all the information found in the templateHeader object.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The ID of the project. For External IDs, format the
{projectId}asid/{externalId}.
Responses
200
A project and a list of templates within the project.
RESPONSE BODYContent-Type: application/json
A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.
Update project
Example request
PUT /v1/project/12345 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"name": "New And Improved Name",
"description": "Significantly more detailed description"
}Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"updatedAt": "2013-07-01T19:57:36.000Z",
"id": 12345,
"templates": [
],
"description": "Significantly more detailed description",
"createdAt": "2013-07-01T19:57:36.000Z",
"settings": {
},
"name": "New And Improved Name",
"projectType": "loyalty"
}Example request with external ID
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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"updatedAt": "2013-07-01T19:57:36.000Z",
"externalId": "myProject",
"id": 12345,
"templates": [
],
"description": "Significantly more detailed description",
"createdAt": "2013-07-01T19:57:36.000Z",
"settings": {
},
"name": "New And Improved Name",
"projectType": "loyalty"
}PUT /project/{projectId}
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:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The ID of the project. For External IDs, format the
{projectId}asid/{externalId}.
Request Body
An update request can take the same payload as a Create Project request. However, you should provide only the keys you want to update; keys you do not provide will remain unchanged.
Content-Type: application/json
Project request
A project request determines the type of passes you can create and the types of barcode your passes will use.
Responses
200
Returns project metadata and a list of templates for the project.
RESPONSE BODYContent-Type: application/json
A project response includes all fields in a project request, along with identifiers for the project and a list of templates created within the project.
List NFC merchants
Example request
GET /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Example request with external ID
GET /v1/project/id/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Response
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"
}
]
}GET /project/{projectId}/nfcMerchants
Return all NFC merchant information for a project.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The 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 BODYContent-Type: application/json
OBJECT PROPERTIESmerchants : Array [Object]
ARRAY ITEMA response contains information generated by Airship and/or gathered from Google Wallet services.
All ofObject
Describes NFC support for your project (and related templates/passes).
OBJECT PROPERTIESkeyVersion : Integer
The SSH protocol version for your key. Can be set to
1. Max: 4 Min: 1merchantEmail : 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
OBJECT PROPERTIESkeySource : String
Set by Airship, either
GENERATEDif Airship generates your public/private keys orIMPORTEDif you provide your ownpublicKey.Possible values:
GENERATED,IMPORTEDmerchantId : 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 : String
Google only, represents your platform and may contain more than one
collectorId.updatedAt : String
The date and time when your NFC merchant information was last updated. Format:
date-time
Add NFC merchant
Example request — Apple and Google vendors
POST /v1/project/13137/nfcMerchants HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
Api-Revision: 1.2
{
"vendor": "ANY",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
"keyVersion": 1,
"keySource": "IMPORTED"
}Example request with external ID — Apple and Google vendors
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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"merchantId": "a535fc29-9e90-434a-b8e9-4a5851292ccc",
"projectId": 13137,
"vendor": "APPLE",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADIAvHog/qg3dG4d0X0knYEIdvHnTXlk9SIm39iv1PM1w=",
"keyVersion": 1,
"keySource": "IMPORTED",
"updatedAt": "2020-09-16T18:17:49.349Z"
}POST /project/{projectId}/nfcMerchants
Provide your merchant information and keys to support NFC interaction with passes and SmartTap for Android. When your project is NFC enabled, your audience can tap their device to a terminal to use their passes — consume point balances, use coupons, scan boarding passes, etc.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The project you want to add or lookup NFC merchant information for. For External IDs, format the
{projectId}asid/{projectExternalId}.
Request Body
Content-Type: application/json
Object
Describes NFC support for your project (and related templates/passes).
OBJECT PROPERTIESkeyVersion : Integer
The SSH protocol version for your key. Can be set to
1. Max: 4 Min: 1merchantEmail : 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
Returns the newly-added NFC merchant information for your project.
RESPONSE BODYContent-Type: application/json
A response contains information generated by Airship and/or gathered from Google Wallet services.
All ofObject
Describes NFC support for your project (and related templates/passes).
OBJECT PROPERTIESkeyVersion : Integer
The SSH protocol version for your key. Can be set to
1. Max: 4 Min: 1merchantEmail : 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
OBJECT PROPERTIESkeySource : String
Set by Airship, either
GENERATEDif Airship generates your public/private keys orIMPORTEDif you provide your ownpublicKey.Possible values:
GENERATED,IMPORTEDmerchantId : 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 : String
Google only, represents your platform and may contain more than one
collectorId.updatedAt : String
The date and time when your NFC merchant information was last updated. Format:
date-time
Get NFC merchant
Example request
GET /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Example request with external ID
GET /v1/project/id/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
"projectId": 13137,
"vendor": "GOOGLE",
"merchantName": "testMerchant5",
"merchantEmail": "test@example.com",
"terminalProvider": "Verifone",
"publicKeyPem": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEo/TGGLW++AE05GAYnXgCo/ebGLN1\nbdjF01imojOydLhts4VsYDCU69pRXuWKn6wRgmymSAB4+b72n3/uB8lW0w==\n",
"keyVersion": 1,
"keySource": "GENERATED",
"updatedAt": "2020-09-16T18:20:45.000Z"
}GET /project/{projectId}/nfcMerchants/{merchantId}
Get an individual NFC merchant.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The project you want to add or lookup NFC merchant information for. For External IDs, format the
{projectId}asid/{projectExternalId}.merchantId : StringREQUIRED
The merchant ID you want to modify.
Responses
200
Returns the merchant information associated with the
merchantId.RESPONSE BODYContent-Type: application/json
A response contains information generated by Airship and/or gathered from Google Wallet services.
All ofObject
Describes NFC support for your project (and related templates/passes).
OBJECT PROPERTIESkeyVersion : Integer
The SSH protocol version for your key. Can be set to
1. Max: 4 Min: 1merchantEmail : 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
OBJECT PROPERTIESkeySource : String
Set by Airship, either
GENERATEDif Airship generates your public/private keys orIMPORTEDif you provide your ownpublicKey.Possible values:
GENERATED,IMPORTEDmerchantId : 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 : String
Google only, represents your platform and may contain more than one
collectorId.updatedAt : String
The date and time when your NFC merchant information was last updated. Format:
date-time
Update NFC merchant information
Example request
PUT /v1/project/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/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
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"
}PUT /project/{projectId}/nfcMerchants/{merchantId}
Update your NFC merchant information.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The project you want to add or lookup NFC merchant information for. For External IDs, format the
{projectId}asid/{projectExternalId}.merchantId : StringREQUIRED
The merchant ID you want to modify.
Request Body
You cannot update your public/private key. If you need to update keys, you should add a new NFC merchant configuration using new keys and delete the existing configuration.
Content-Type: application/json
Object
OBJECT PROPERTIESmerchantEmail : String
The google merchant email address, used when configuring smartTap.
merchantName : String
The google merchant name, used when configuring smartTap.
Responses
200
Returns your updated merchant information.
RESPONSE BODYContent-Type: application/json
A response contains information generated by Airship and/or gathered from Google Wallet services.
All ofObject
Describes NFC support for your project (and related templates/passes).
OBJECT PROPERTIESkeyVersion : Integer
The SSH protocol version for your key. Can be set to
1. Max: 4 Min: 1merchantEmail : 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
OBJECT PROPERTIESkeySource : String
Set by Airship, either
GENERATEDif Airship generates your public/private keys orIMPORTEDif you provide your ownpublicKey.Possible values:
GENERATED,IMPORTEDmerchantId : 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 : String
Google only, represents your platform and may contain more than one
collectorId.updatedAt : String
The date and time when your NFC merchant information was last updated. Format:
date-time
Delete NFC merchant
Example request
DELETE /v1/project/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Example request with external ID
DELETE /v1/project/id/13137/nfcMerchants/23c0da58-3b79-4d44-9191-b69faef7b24c HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Example request
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"merchantId": "23c0da58-3b79-4d44-9191-b69faef7b24c",
"updatedAt": "2020-09-16T18:20:45.000Z"
}DELETE /project/{projectId}/nfcMerchants/{merchantId}
Delete an NFC merchant. Deleting your NFC information prevents users from redeeming passes using NFC for the associated terminal, unless you have already added new/different NFC information to your project.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The project you want to add or lookup NFC merchant information for. For External IDs, format the
{projectId}asid/{projectExternalId}.merchantId : StringREQUIRED
The merchant ID you want to modify.
Responses
200
The merchant information was deleted.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESmerchantId : String
The merchant ID that you deleted. Format:
uuidupdatedAt : String
The date and time when the merchant information was deleted. Format:
date-time
Templates
A template determines the format, style, field placement, and default values for passes. You must specify a template when creating passes or adaptive links.
The Create Template and Update Template calls expect a different data structure than the response from a Get Template call.
Duplicate template
Example request
POST /v1/template/duplicate/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": 12346
}POST /template/duplicate/{templateId}
Duplicates the specified template and put it in the same project.
/v1/template/duplicate/id/(templateExternalId) duplicates the template specified by the external ID and puts the newly created template in the same project.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateId : StringREQUIRED
The templateId of the template you want to duplicate.
Responses
200
A successful request returns the ID of the newly created template.
RESPONSE BODYContent-Type: application/json; charset=utf-8
OBJECT PROPERTIEStemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
List templates
Example request
GET /v1/template/headers HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
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
}
}GET /template/headers
List the headers for templates you created.
Security:
query PARAMETERSpageSize : Number
Number of templates per page. Defaults to 10.
page : Number
The page you want to retrieve. Defaults to 1.
order : String
The order you want the projects returned in. Defaults to
id.Possible values:
id,name,createdAt,updatedAtdirection : String
The values ordered ascending or descending. Defaults to
DESC.Possible values:
ASC,DESC
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
A successful response includes an array of template headers for templates you created. Look up an individual template to see field and header information for any individual template.
RESPONSE BODYContent-Type: application/json; charset=utf-8
OBJECT PROPERTIEScount : String
The total number of results.
pagination : Pagination object
Contains information about pagination, according to your query parameters.
templateHeaders : Array [Object]
A list of template header objects.
ARRAY ITEM- All of
Object
OBJECT PROPERTIEScreatedAt : String
The date and time when the item was created. Format:
date-timeid : Integer
The identifier for the template. You can recall the template by ID in other operations.
updatedAt : String
The date and time when the item was last updated. Format:
date-time
General template headers
Meta information about templates; this object appears on all templates and identifies templates associated with a project.
- All of
Get template
Example request
GET /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Example request with external ID
GET /v1/template/id/myTemplate HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response — Apple template
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.store.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
}
},
"templateHeader": {
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"id": "12345",
"updatedAt": "2013-07-01T18:28:33.000Z",
"description": "Description",
"createdAt": "2013-07-01T18:28:33.000Z",
"name": "Loyalty Card",
"disabled": "False",
"expiryDuration": 730
}
}GET /template/{id}
Get the template specified by the templateId.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
id : StringREQUIRED
The
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 BODYContent-Type: application/json
All ofObject
OBJECT PROPERTIEScreatedAt : String
The date and time when the item was created. Format:
date-timeid : Integer
The identifier for the template. You can recall the template by ID in other operations.
updatedAt : String
The date and time when the item was last updated. Format:
date-time
- One of
Apple Wallet template request
A complete iOS template includes template meta information, headers, and fields.
Google Wallet template request
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
Update template
Example request — Apple template
PUT /v1/template/12345 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"logo_color": {
"formatType": "1",
"fieldType": "topLevel",
"value": "rgb(24,86,148)"
},
"icon_image": {
"formatType": "1",
"fieldType": "image",
"value": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png"
},
"logo_text": {
"formatType": "1",
"fieldType": "topLevel",
"value": "Logo Text"
},
"barcode_encoding": {
"formatType": "1",
"fieldType": "barcode",
"value": "iso-8859-1"
},
"suppress_strip_shine": {
"formatType": "1",
"fieldType": "topLevel",
"value": "true"
},
"logo_image": {
"formatType": "1",
"fieldType": "image",
"value": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-logo.png"
},
"foreground_color": {
"formatType": "1",
"fieldType": "topLevel",
"value": "rgb(255,255,255)"
},
"background_color": {
"formatType": "1",
"fieldType": "topLevel",
"value": "rgb(49,159,196)"
}
},
"fields": {
"Coupon": {
"formatType": "String",
"changeMessage": "Enjoy %@ off your next order!",
"order": 1,
"fieldType": "primary",
"textAlignment": "textAlignmentRight",
"value": "20%",
"label": "coupon",
"required": false,
"hideEmpty": true
},
"SiteAddress": {
"formatType": "Number",
"changeMessage": "New stuff, just for you at %@",
"order": 2,
"textAlignment": "textAlignmentCenter",
"fieldType": "secondary",
"value": "https://www.store.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
],
"vendor": "Apple",
"projectType": "memberCard",
"projectId": "1234",
"type": "Store Card",
"vendorId": "1",
"deleted": "False",
"description": "Description",
"name": "Loyalty Card (Edited)",
"disabled": "False"
}Example request with external ID - Google template
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.test.com",
"order": 1,
"formatType": "URL"
}
},
"messageModule": {
},
"imageModulesData": {
},
"pointsModule": {
"Tier": {
"label": "Tier",
"value": 2,
"row": 0,
"col": 1,
"formatType": "Number",
"numberStyle": "PKNumberStyleDecimal"
},
"Points": {
"label": "Points",
"value": 1234,
"row": 0,
"col": 0,
"formatType": "Number"
}
},
"notAssigned": {
},
"titleModule": {
"image": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
"imageDescription": "Logo Image",
"Program Name": {
"label": "Program Name",
"value": "UA",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"vendor": "Google",
"projectType": "memberCard",
"type": "Loyalty1",
"vendorId": 2,
"deleted": "False",
"description": "description",
"name": "Adding Google"
}Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": "12345"
}PUT /template/{id}
Update the specified template. This endpoint takes any of the parameters used for Creating a Template. You can also add or remove fields from the template with this call by adding or omitting those fields from the request.
Provide a complete template object when updating a template. This call replaces the existing template object in its entirety. You must include all keys and fields that should remain in the template, otherwise they are removed.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
id : StringREQUIRED
The
templateIdof the template you want to update. For External IDs, format the{id}asid/{templateExternalId}.
Request Body
The shape of your template is determined by the device/wallet vendor you create passes for.
Content-Type: application/json
One ofApple Wallet template request
A complete iOS template includes template meta information, headers, and fields.
Google Wallet template request
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
Responses
200
A response returns the template’s unique identifier. Use this
templateIdto reference the template in subsequent operations.RESPONSE BODYContent-Type: application/json; charset=utf-8
OBJECT PROPERTIEStemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
Create template
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.store.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"description": "Description",
"name": "Loyalty Card",
"disabled": "False",
"expiryInfo": {
"expiryDuration": 365
}
}Example Google template
POST /v1/template/12345 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"infoModuleData": {
"hexFontColor": "#666666",
"hexBackgroundColor": "#0096e1",
"Program ID": {
"label": "Program ID",
"value": "12345678",
"row": 0,
"col": 0,
"formatType": "String"
},
"Tier Name": {
"label": "Tier Name",
"value": "Silver",
"row": 0,
"col": 1,
"formatType": "String"
},
"Last Updated": {
"label": "Last Updated",
"value": "Five days ago",
"row": 1,
"col": 0,
"formatType": "String"
}
},
"headers": {
"barcode_type": {
"fieldType": "barcode",
"value": "",
"notShared": true
},
"barcode_value": {
"fieldType": "barcode",
"value": "",
"notShared": true
},
"barcode_label": {
"fieldType": "barcode",
"value": "",
"notShared": true
},
"barcode_encoding": {
"fieldType": "barcode",
"value": "",
"notShared": true
},
"barcodeAltText": {
"fieldType": "barcode",
"value": "",
"notShared": true
}
},
"textModulesData": {
"Program Details": {
"header": "Program Details",
"body": "Some Basic Text",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"linksModuleData": {
"Merchant Website": {
"description": "Merchant Website",
"uri": "http:\/\/www.test.com",
"order": 1,
"formatType": "URL"
}
},
"messageModule": {
},
"imageModulesData": {
},
"pointsModule": {
"Tier": {
"label": "Tier",
"value": 2,
"row": 0,
"col": 1,
"formatType": "Number",
"numberStyle": "PKNumberStyleDecimal"
},
"Points": {
"label": "Points",
"value": 1234,
"row": 0,
"col": 0,
"formatType": "Number"
}
},
"notAssigned": {
},
"titleModule": {
"image": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
"imageDescription": "Logo Image",
"Program Name": {
"label": "Program Name",
"value": "UA",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"vendor": "Google",
"projectType": "memberCard",
"type": "Loyalty1",
"vendorId": 2,
"deleted": "False",
"description": "description",
"name": "Adding Google",
"expiryDuration": 365
}Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": 12345
}POST /template/{id}
Create a template within the specified project. A template is specific to a vendor platform, Apple or Google. See also Create template with external ID.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
id : StringREQUIRED
The
projectIdof the project that will contain the new template.
Request Body
The request body is shaped by platform vendor your template and subsequent passes are intended for.
Content-Type: application/json
One ofApple Wallet template request
A complete iOS template includes template meta information, headers, and fields.
Google Wallet template request
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
Responses
200
A response returns the template’s unique identifier. Use this
templateIdto reference the template in subsequent operations.RESPONSE BODYContent-Type: application/json; charset=utf-8
OBJECT PROPERTIEStemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
Delete template
Example request
DELETE /v1/template/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Example request with external ID
DELETE /v1/template/id/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"status": "Deleted",
"TemplateID": "12345"
}DELETE /template/{id}
Delete the specified template.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
id : StringREQUIRED
The
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 BODYContent-Type: application/json
OBJECT PROPERTIESTemplateId : Integer
The identifier of the deleted template.
status : String
Indicates that the request succeeded.
Possible values:
success
Create template with external ID
Example Apple template
POST /v1/template/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.store.com/new?custnumb=123456",
"label": "personalDeals",
"required": false,
"hideEmpty": true
},
"InStore": {
"formatType": "String",
"changeMessage": "Or visit your nearest store at %@",
"order": 1,
"fieldType": "secondary",
"value": "1234 Fake St.",
"label": "nearestStore",
"required": false,
"hideEmpty": false
}
},
"vendor": "Apple",
"projectType": "memberCard",
"projectId": 1234,
"type": "Store Card",
"vendorId": 1,
"deleted": "False",
"description": "Description",
"name": "Loyalty Card",
"disabled": "False",
"expiryInfo": {
"expiryDuration": 365
}
}Example Google template
POST /v1/template/project/id/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.test.com",
"order": 1,
"formatType": "URL"
}
},
"messageModule": {
},
"imageModulesData": {
},
"pointsModule": {
"Tier": {
"label": "Tier",
"value": 2,
"row": 0,
"col": 1,
"formatType": "Number",
"numberStyle": "PKNumberStyleDecimal"
},
"Points": {
"label": "Points",
"value": 1234,
"row": 0,
"col": 0,
"formatType": "Number"
}
},
"notAssigned": {
},
"titleModule": {
"image": "https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/default-pass-icon.png",
"imageDescription": "Logo Image",
"Program Name": {
"label": "Program Name",
"value": "UA",
"row": 0,
"col": 0,
"formatType": "String"
}
},
"vendor": "Google",
"projectType": "memberCard",
"type": "Loyalty1",
"vendorId": 2,
"deleted": "False",
"description": "description",
"name": "Adding Google",
"expiryInfo": {
"expiryDuration": 365
}
}Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"templateId": 12345
}POST /template/{projectId}/id/{templateExternalId}
Create a template with an external ID within the specified project. A template is specific to a vendor platform, Apple or Google. See also Create template.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The project you want to associate your new template with.
templateExternalId : StringREQUIRED
The custom identifier you want to give to your new template.
Request Body
The request body is shaped by platform vendor your template and subsequent passes are intended for.
Content-Type: application/json
One ofApple Wallet template request
A complete iOS template includes template meta information, headers, and fields.
Google Wallet template request
A google template organizes fields into a series of module objects. Include only the objects you want to populate for a particular template; some modules may not apply to your template type.
Responses
200
A response returns the template’s unique identifier. Use this
templateIdor the external ID to reference the template in subsequent operations.RESPONSE BODYContent-Type: application/json; charset=utf-8
OBJECT PROPERTIEStemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
Delete location from template
Example request
DELETE /v1/template/12345/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Example request with external ID
DELETE /v1/template/id/myTemplate/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2DELETE /template/{templateId}/location/{locationId}
Remove a location from template.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateId : StringREQUIRED
The template you want to remove a location from. For External IDs, format the
{templateId}asid/{externalId}.locationId : StringREQUIRED
The ID of the location you want to remove.
Responses
200
The location is deleted.
RESPONSE BODYContent-Type: application/json; charset=utf-8
Add locations to template
Example request
POST /v1/template/12345/locations HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
]
}Example request with external ID
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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"locationId": 65,
"value": {
"region": "CA",
"regionCode": "94404",
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"longitude": -122.374,
"latitude": 37.618,
"city": "San Francisco"
},
"fieldId": 1842
}
]POST /template/{templateId}/locations
Add locations to the specified template.
As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services, which affects most Google Wallet passes. Google has not announced when they will make Location triggers available again.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateId : StringREQUIRED
The 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: application/json
Object
OBJECT PROPERTIESLocations : Array [Location object]
Responses
200
A successful request returns the locations on the pass.
RESPONSE BODYContent-Type: application/json; charset=utf-8
ARRAY ITEM- OBJECT PROPERTIES
LocationId : Integer
The identifier for a location.
fieldId : Integer
value : Location object
Represents a location on a pass or an adaptive link.
Place objects in the locations array to add location information to passes and templates. Updating locations on a pass or template will replace all locations on that pass; if you want to add to the locations on a pass, you must provide all locations already included on the pass and any additional locations you want to add.
Apple Wallet supports up to 10 locations per pass. If you exceed this limit for an iOS pass, we will use the 10 locations nearest to a user (located by IP address) when they install the pass.
- OBJECT PROPERTIES
Get template passes
Example request
GET /v1/template/12345/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 3,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/3/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da051",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "uninstalled",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 1,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/1/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e253",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}GET /template/{templateId}/passes
List passes for a template.
Security:
query PARAMETERSstatus : 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_installedpageSize : Integer
The number of passes per page. Defaults to 10.
page : Integer
The page of results you want to retrieve, starting at 1.
order : String
The order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtdirection : String
Determines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESC
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateId : IntegerREQUIRED
The
templateIdof the template you want to get passes for.
Responses
200
A successful request returns a paged list of passes for a particular template.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESpagination : 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.
ARRAY ITEMPass Metadata
Meta information about passes.
OBJECT PROPERTIEScreatedAt : String
The date and time when the item was last updated. Format:
date-timeid : Integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
installedAt : String
The date and time when pass was first installed on the device. Format:
date-timeplatform : String
Wallet platform.
Possible values:
iOS,AndroidserialNumber : String
The serial number of the pass.
status : String
Recent on-device pass status.
Possible values:
installed,uninstalled,not_been_installedtemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
uninstalledAt : String
The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format:
date-timeupdatedAt : String
The date and time when the item was created. Format:
date-timeurl : String
Pass download URL.
404
Template not found.
Publish a bulk update to 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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"ticketId": 56789
}PUT /template/{templateId}/passes
Updates all passes based on a particular template. The only information you can modify on passes for the specified template ID are images, barcode data, and the following fields:
- Membership ID fields
- Coupon codes
- Barcode values or alternative text
- Any other field or image on the pass
Updating the order value for linkModulesData can only be done in an Event or Boarding Pass template.
Security:
query PARAMETERSstatus : 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_installedpageSize : Integer
The number of passes per page. Defaults to 10.
page : Integer
The page of results you want to retrieve, starting at 1.
order : String
The order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtdirection : String
Determines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESC
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateId : IntegerREQUIRED
The
templateIdof the template you want to get passes for.
Request Body
Specify the fields you want to update. Any field you do not specify in this payload remains unchanged.
Content-Type: application/json
Object
OBJECT PROPERTIESfields : Object
OBJECT PROPERTIESField Name (String) : Object
OBJECT PROPERTIESvalue : String
The
valuekey that you want to change for the field.
Responses
200
Returns a ticket ID as a reference for the update operation.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESticketId : Integer
A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.
404
Template with ID
templateIdwas not found.
Apple Wallet Pass Personalization
Adding personalization to an Apple Wallet loyalty template creates a pass that prompts the user for relevant personal information when signing up for a rewards program. These endpoints help you manage the personalizable information that you require users to provide when signing up for your loyalty/rewards program.
Get personalization requirements
Example request
GET /v1/template/12345/personalization HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}GET /template/{templateId}/personalization
Returns personalization requirements for a template.
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateId : StringREQUIRED
The loyalty card template you want to add, modify, or retrieve personalization information for.
Responses
200
Your template has the following personalization requirements.
RESPONSE BODYContent-Type: application/json
Update personalization requirements
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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}PUT /template/{templateId}/personalization
When updating personalization requirements for a template, you must provide a complete payload. This request overwrites all previous personalization requirements attached to the template; any information you leave out of this request will be removed from the personalization requirements for the template.
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateId : StringREQUIRED
The loyalty card template you want to add, modify, or retrieve personalization information for.
Request Body
Content-Type: application/json
Apple Pass personalization requirements
Responses
200
Your personalization requirements have been updated for the template.
RESPONSE BODYContent-Type: application/json
Add personalization requirements
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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}POST /template/{templateId}/personalization
Adds personalization requirements to a template. When a user attempts to install a pass with personalization requirements, they are first prompted for the requiredPersonalizationFields specified in this payload. When the user fills out the information and accepts the terms and conditions (if present), they receive a personalized pass.
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateId : StringREQUIRED
The loyalty card template you want to add, modify, or retrieve personalization information for.
Request Body
Content-Type: application/json
Apple Pass personalization requirements
Responses
200
Your personalization requirements have been added to the template.
RESPONSE BODYContent-Type: application/json
Delete personalization requirements
Example request
DELETE /v1/template/12345/personalization HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"requiredPersonalizationFields": ["name", "postalCode", "emailAddress", "phoneNumber"
],
"description": "Enter your information to sign up and earn points.",
"termsAndConditions": "Terms and conditions go here"
}DELETE /template/{templateId}/personalization
Removes personalization requirements from a template.
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateId : StringREQUIRED
The loyalty card template you want to add, modify, or retrieve personalization information for.
Responses
200
Your personalization requirements removed from the template.
RESPONSE BODYContent-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
Example request
GET /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>Response
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
}
]
}GET /links/adaptive
Returns a list of adaptive links.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The 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 BODYContent-Type: application/json
OBJECT PROPERTIESlinks : Array [Adaptive Link response]
Create Adaptive Link
Example request
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://acustomer.com/landing.html",
"availablePasses": 100000,
"payload": {}
}Example request with expiration date
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://acustomer.com/landing.html",
"expirationDate": "2022-10-01",
"availablePasses": 100000,
"ttlInDays": 730,
"payload": {}
}Example request with payload
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"payload": {"fields": {"tier": {"value": "gold"}}}
}Example request with locations
POST /v1/links/adaptive HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 12345,
"androidTemplateId": 154321,
"isPersonalized": "true",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://acustomer.com/landing.html",
"availablePasses": 100000,
"ttlInDays": 30,
"parameterEncoding": "base64",
"locationRadius": 10,
"maxResultLocations": 5,
"payload": {},
"locations": [
{
"latitude": 45.5898,
"longitude": -122.5951,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97218",
"relevantText": "Welcome to Portland... Voodoo Donuts is only 11 miles away",
"streetAddress1": "7000 NE Airport Way"
},
{
"latitude": 45.525492,
"longitude": -122.686092,
"city": "Portland",
"country": "US",
"region": "OR",
"regionCode": "97209",
"relevantText": "Welcome to the Ship!",
"streetAddress1": "1417 NW Everett St #300",
"streetAddress2": ""
},
{
"latitude": 45.5205,
"longitude": -122.6788,
"relevantText": "See you at dinner tonight… or did you already hit voodoo donuts?"
}
]
}Response
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://acustomer.com/landing.html",
"isPersonalized": "true",
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 30
}POST /links/adaptive
If a template for a device type is not provided, the adaptive link will not be able to create passes for that device. Visiting the adaptive link URL associated with an unsupported device will redirect to the landingPageUrl, if present.
Templates can be provided either implicitly as part of Dynamic Link objects or explicitly with IDs. So either one or both of iosPassLinkId and androidPassLinkId must be present, or payload must be present along with one or both of iosTemplateId and androidTemplateId.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Request Body
Content-Type: application/json
Adaptive Link request
An adaptive link request contains identifiers for the templates you used to generate passes from the link, and any fields you want to set when users create passes from the link.
Responses
200
A successful request results in an adaptive link.
RESPONSE BODYContent-Type: application/json
An adaptive link response includes URLs that users can access to detect and install a pass.
404
Could not find template(s), or could not find or create Dynamic Link object(s).
Create boarding pass or event ticket Adaptive Links
Example boarding pass request
POST /v1/links/adaptive/multiple/project/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
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"
},
]
}POST /links/adaptive/multiple/project/{projectId}
Create boarding pass or event ticket adaptive links. Creating boarding passes or event tickets is similar to other adaptive links, with a few additional items in the request and response payloads.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The project you want to create the boarding pass in.
Request Body
An adaptive link request where the fields object can
include an array of flights or events, each with an array of passengers
or attendees, respectively.
Content-Type: application/json
One ofEvent ticket Adaptive Link request
An event ticket requires similar information to other adaptive link types, but does not support some of the same fields, and requires event and attendee information.
Like other adaptive links, you must provide the
idorexternalIdof an iOS or Android template. You can create the event within this request or specify an event byeventIdoreventExternalId. In either case, you must also provide an array of attendees for the event.Boarding pass Adaptive Link request
A boarding pass adaptive link requires similar information to other adaptive link types, but the payload includes flight information and an array of passengers for each flight.
Like other adaptive links, you must provide the
idorexternalIdof an iOS or Android template.
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 BODYContent-Type: application/json
OBJECT PROPERTIESlinks : Array [Any]
An array of adaptive links.
ARRAY ITEM- One of
Boarding pass Adaptive Link response
The boarding pass operations return responses like other adaptive links, with the addition of the identifier of the event and an HTTP status for each individual adaptive link.
Like other adaptive links, you must provide the
idorexternalIdof an iOS or Android template.Event ticket Adaptive Link response
The response for event ticket operations is much like any other adaptive link, with the addition of the identifier of the event and an HTTP status for each individual adaptive link.
- One of
List Adaptive Links for a project
Example request
GET /v1/links/adaptive/projects/7331?pageSize=2 HTTP/1.1
Authorization: Basic <authorization string>Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"adaptiveLinkId": "7XRMaSpcEQk",
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/adaptive/7XRMaSpcEQk",
"isPersonalized": false,
"availablePasses": 998,
"iosTemplateId": 106178,
"projectId": 7331,
"createdAt": "2023-05-23T20:21:10.446Z",
"updatedAt": "2023-05-23T20:21:10.446Z",
"status": 200,
"isExpired": false,
"doesAllowUrlParameters": true,
"expiry": "2023-11-19",
"isAvailablePassesUnlimited": false
},
{
"adaptiveLinkId": "Y0E6EXuTx5i",
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/adaptive/Y0E6EXuTx5i",
"isPersonalized": false,
"availablePasses": 998,
"iosTemplateId": 106178,
"projectId": 7331,
"createdAt": "2023-05-23T20:20:39.808Z",
"updatedAt": "2023-05-23T20:20:39.808Z",
"status": 200,
"isExpired": false,
"doesAllowUrlParameters": true,
"expiry": "2023-11-19",
"isAvailablePassesUnlimited": false
}
],
"nextPageToken": "XGMuDpx2RDs.1684443368127"
}GET /links/adaptive/projects/{projectId}
Returns a list of adaptive links for a project.
Security:
query PARAMETERSpageSize : Integer
The maximum items to return per page. Defaults to 10.
nextPageToken : String
The token for the next page of results.
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The ID of the project.
Responses
200
Returns a list of all adaptive links for a project.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESlinks : Array [Adaptive Link response]
Max items: 1000
List Adaptive Links for a template
Example request
GET /v1/links/adaptive/projects/7331/templates/106178 HTTP/1.1
Authorization: Basic <authorization string>Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"links": [
{
"adaptiveLinkId": "7XRMaSpcEQk",
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/adaptive/7XRMaSpcEQk",
"isPersonalized": false,
"availablePasses": 998,
"iosTemplateId": 106178,
"projectId": 7331,
"createdAt": "2023-05-23T20:21:10.446Z",
"updatedAt": "2023-05-23T20:21:10.446Z",
"status": 200,
"isExpired": false,
"doesAllowUrlParameters": true,
"expiry": "2023-11-19",
"isAvailablePassesUnlimited": false
}
],
"nextPageToken": "Y0E6EXuTx5i.1684873239808"
}GET /links/adaptive/projects/{projectId}/templates/{templateId}
Returns a list of adaptive links for a template.
Security:
query PARAMETERSpageSize : Integer
The maximum items to return per page. Defaults to 10.
nextPageToken : String
The token for the next page of results.
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The ID of the project.
templateId : StringREQUIRED
The ID of the template.
Responses
200
Returns a list of all adaptive links for a template.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESlinks : Array [Adaptive Link response]
Max items: 1000
Get Adaptive Link
Example request
GET /v1/links/adaptive/abchd345678 HTTP/1.1
Authorization: Basic <authorization string>Response
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://acustomer.com/landing.html",
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 30
}GET /links/adaptive/{adaptiveLinkId}
Returns information about a single adaptive link.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
adaptiveLinkId : StringREQUIRED
The ID of the adaptive link.
Responses
200
Lists urls and available passes for an individual link.
RESPONSE BODYContent-Type: application/json
An 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
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://acustomer.com/landing.html",
"payload": {"fields": {"tier": {"value": "gold"}}}
}Response
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://acustomer.com/landing.html",
"isPersonalized": "true",
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 30
}PUT /links/adaptive/{adaptiveLinkId}
Updates an individual adaptive link. You can provide any part of an adaptive link body. Adaptive link fields that you do not provide in this request remain unchanged.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
adaptiveLinkId : StringREQUIRED
The 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/json
Adaptive Link request
An adaptive link request contains identifiers for the templates you used to generate passes from the link, and any fields you want to set when users create passes from the link.
Responses
200
A successful request results in an adaptive link.
RESPONSE BODYContent-Type: application/json
An 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
Example request
DELETE /v1/links/adaptive/rthBWAWDaAA HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json
{}DELETE /links/adaptive/{adaptiveLinkId}
Deletes an adaptive link.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
adaptiveLinkId : StringREQUIRED
The 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
Example request
GET /v1/links/adaptive/rthBWAWDaAA/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 616,
"templateId": 1000057,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/616/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da0b8",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "installed",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 610,
"templateId": 1000083,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/610/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e216",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}GET /links/adaptive/{adaptiveLinkId}/passes
List passes for an adaptive link.
Security:
query PARAMETERSstatus : 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_installedpageSize : Integer
The number of passes per page. Defaults to 10.
page : Integer
The page of results you want to retrieve, starting at 1.
order : String
The order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtdirection : String
Determines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESC
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
adaptiveLinkId : StringREQUIRED
The adaptive link ID used for pass creation.
Responses
200
A successful request returns a paged list of passes for a particular adaptive link.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIEScount : Integer
The total number of passes associated with an adaptive link.
pagination : 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.
ARRAY ITEMPass Metadata
Meta information about passes.
OBJECT PROPERTIEScreatedAt : String
The date and time when the item was last updated. Format:
date-timeid : Integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
installedAt : String
The date and time when pass was first installed on the device. Format:
date-timeplatform : String
Wallet platform.
Possible values:
iOS,AndroidserialNumber : String
The serial number of the pass.
status : String
Recent on-device pass status.
Possible values:
installed,uninstalled,not_been_installedtemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
uninstalledAt : String
The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format:
date-timeupdatedAt : String
The date and time when the item was created. Format:
date-timeurl : String
Pass download URL.
404
The adaptive link ID does not exist.
Generate multiple passes from a single Adaptive Link
Example iOS request
GET /v1/pass/adaptive?ids=rthBWAWDaAA,Y0E6EXuTx5i&deviceType=ios HTTP/1.1iOS response
HTTP/1.1 200 OK
Content-Type: application/vnd.apple.pkpass
[.pkpass]Example Android request
GET /v1/pass/adaptive?ids=rthBWAWDaAA,Y0E6EXuTx5i&deviceType=android HTTP/1.1Android response
HTTP/1.1 301 RedirectGET /pass/adaptive
Generates a multi-pass bundle from an Adaptive Link.
query PARAMETERSids : StringREQUIRED
Comma-separated Adaptive Link IDs to bundle.
deviceType : StringREQUIRED
The 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
Api-Revision : StringREQUIRED
The 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 BODYContent-Type: application/json
A 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.pkpass
A .pkpass file for iOS users.
404
Could not find an entry with specified
adaptiveLinkId.
Generate pass from Adaptive Link
Example iOS request
GET /v1/pass/adaptive/rthBWAWDaAA/ios HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2iOS response
HTTP/1.1 200 OK
Content-Type: application/vnd.apple.pkpass
[.pkpass]Example Android request
GET /v1/pass/adaptive/rthBWAWDaAA/android HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Android response
HTTP/1.1 301 RedirectGET /pass/adaptive/{adaptiveLinkId}/{deviceType}
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).
barcode : String
Sets the barcode value for the new pass.
barcodeAltText : String
The alternative text for the barcode on the pass. If unspecified, the barcode value is used as the barcodeAltText.
tags : String
Tags you want to associate with the pass. Multiple tags may be separated by
~, e.g.,&tags=tag1~tag2~tag3.exid : String
The external_id you want to set for this pass.
lat : String
The latitude of the device installing the pass, used to calculate distance to locations specified in the adaptive link.
long : String
The longitude of the device installing the pass, used to calculate distance to locations specified in the adaptive link.
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
adaptiveLinkId : StringREQUIRED
The identifier of the adaptive link you want to create a pass from.
deviceType : StringREQUIRED
The 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 BODYContent-Type: application/json
A 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.pkpass
A .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
Example request
GET /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "1KVMz6NlFb",
"adaptiveLinkExternalId": "coolNewAdaptiveLink",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
"landingPageUrl": "https://acustomer.com/landing.html",
"isPersonalized": false,
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 730,
"iosTemplateId": 54321,
"iosTemplateExternalId": "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 /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}
Get an adaptive link with an external ID from a project that also has an external ID.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectExternalId : StringREQUIRED
The external ID of the project containing an adaptive link.
adaptiveLinkExternalId : StringREQUIRED
The custom identifier for an adaptive link.
Responses
200
Lists urls and available passes for an individual link.
RESPONSE BODYContent-Type: application/json
An 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
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://acustomer.com/landing.html",
"availablePasses": 100000,
"payload": {}
}Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "1KVMz6NlFb",
"adaptiveLinkExternalId": "coolNewAdaptiveLink",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
"landingPageUrl": "https://acustomer.com/landing.html",
"isPersonalized": false,
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 730,
"iosTemplateId": 54321,
"iosTemplateExternalId": "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
}POST /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}
Create an adaptive link in a project that also has an external ID. The adaptiveLinkExternalID you use in the path becomes the ID for your new adaptive link.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectExternalId : StringREQUIRED
The external ID of the project containing an adaptive link.
adaptiveLinkExternalId : StringREQUIRED
The custom identifier for an adaptive link.
Request Body
Content-Type: application/json
Adaptive Link request
An adaptive link request contains identifiers for the templates you used to generate passes from the link, and any fields you want to set when users create passes from the link.
Responses
200
A successful request results in an adaptive link.
RESPONSE BODYContent-Type: application/json
An adaptive link response includes URLs that users can access to detect and install a pass.
404
Could not find project, or could not find or create Dynamic Link object(s).
Get pass from Adaptive Link
Example request
GET /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [
{
"id": 39,
"templateId": 6,
"serialNumber": "6f019144-2285-4bb9-b28a-f863af887e53",
"createdAt": "2019-03-06T17:48:28.000Z",
"updatedAt": "2019-03-06T17:48:29.000Z",
"externalId": "ext14"
},
{
"id": 38,
"templateId": 5,
"serialNumber": "7f57d625-cf7c-455b-b3d9-c70adef7d889",
"createdAt": "2019-03-06T17:39:00.000Z",
"updatedAt": "2019-03-06T17:39:01.000Z",
"externalId": "ext14"
}
]
}GET /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes/id/{passExternalId}
Get a pass with an external ID that was created from an adaptive link with an external ID.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
passExternalId : StringREQUIRED
The external ID of the pass you want to get.
projectExternalId : StringREQUIRED
The external ID of the project containing the adaptive link.
adaptiveLinkExternalId : StringREQUIRED
The adaptive link passes were created from.
Responses
200
Returns an array up to two passes created from the adaptive link — one for each template supported by the adaptive link.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESpasses : Array [Object]
The metadata for passes associated with the adaptive link. Each object in the array represents a pass. Max items: 2 Min items: 1
ARRAY ITEMPass Metadata
Meta information about passes.
OBJECT PROPERTIEScreatedAt : String
The date and time when the item was last updated. Format:
date-timeid : Integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
installedAt : String
The date and time when pass was first installed on the device. Format:
date-timeplatform : String
Wallet platform.
Possible values:
iOS,AndroidserialNumber : String
The serial number of the pass.
status : String
Recent on-device pass status.
Possible values:
installed,uninstalled,not_been_installedtemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
uninstalledAt : String
The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format:
date-timeupdatedAt : String
The date and time when the item was created. Format:
date-timeurl : String
Pass download URL.
404
The project, adaptive link, or pass ID does not exist.
Update passes from Adaptive Link
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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"tickets": [
{
"id": 15
},
{
"id": 16
}
]
}PUT /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes/id/{passExternalId}
Update a pass with an external ID that was created from an adaptive link with an external ID. You need only provide the fields and headers you want to update for the pass; all other information will remain unchanged.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
passExternalId : StringREQUIRED
The external ID of the pass you want to update.
projectExternalId : StringREQUIRED
The external ID of the project containing the adaptive link.
adaptiveLinkExternalId : StringREQUIRED
The adaptive link passes were created from.
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/json
Update Apple Wallet Pass : Object
OBJECT PROPERTIESbeacons : Array [Beacon object (iOS only)]
You can only include beacons for Apple Wallet passes.
fields : Object
The fields you want update on the pass.
headers : Object
The headers you want to update for this pass.
locations : Array [Location object]
The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
Responses
200
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 BODYContent-Type: application/json
OBJECT PROPERTIEStickets : Array [Object]
Max items: 2 Min items: 1
ARRAY ITEM- OBJECT PROPERTIES
ticketId : Integer
A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.
- OBJECT PROPERTIES
404
The project, adaptive link, or pass ID does not exist.
Get Adaptive Link
Example request
GET /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "1KVMz6NlFb",
"adaptiveLinkExternalId": "coolNewAdaptiveLink",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
"landingPageUrl": "https://acustomer.com/landing.html",
"isPersonalized": false,
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 730,
"iosTemplateId": 54321,
"androidTemplateId": 54322,
"projectId": 12345,
"createdAt": "2019-05-28T23:55:00.000Z",
"updatedAt": "2019-05-31T00:59:42.000Z",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"status": 200
}GET /links/adaptive/project/{projectId}/id/{adaptiveLinkExternalId}
Get an adaptive link with an external ID.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The ID of the project, generated by Airship, containing the adaptive link.
adaptiveLinkExternalId : StringREQUIRED
The custom identifier for the adaptive link.
Responses
200
Lists urls and available passes for an individual link.
RESPONSE BODYContent-Type: application/json
An 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
Example request
POST /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json
{
"iosTemplateId": 54321,
"androidTemplateId": 54322,
"isPersonalized": false,
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"landingPageUrl": "https://acustomer.com/landing.html",
"availablePasses": 100000,
"payload": {}
}Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"adaptiveLinkId": "1KVMz6NlFb",
"adaptiveLinkExternalId": "coolNewAdaptiveLink",
"url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
"iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
"androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
"landingPageUrl": "https://acustomer.com/landing.html",
"isPersonalized": false,
"isExpired": false,
"availablePasses": 100000,
"ttlInDays": 730,
"iosTemplateId": 54321,
"androidTemplateId": 54322,
"projectId": 12345,
"createdAt": "2019-05-28T23:55:00.000Z",
"updatedAt": "2019-05-31T00:59:42.000Z",
"iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
"androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
"status": 200
}POST /links/adaptive/project/{projectId}/id/{adaptiveLinkExternalId}
Create an adaptive link with an external ID. The adaptiveLinkExternalID you use in the path becomes the ID for your new adaptive link.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
projectId : StringREQUIRED
The ID of the project, generated by Airship, containing the adaptive link.
adaptiveLinkExternalId : StringREQUIRED
The custom identifier for the adaptive link.
Request Body
Content-Type: application/json
Adaptive Link request
An adaptive link request contains identifiers for the templates you used to generate passes from the link, and any fields you want to set when users create passes from the link.
Responses
200
A successful request results in an adaptive link.
RESPONSE BODYContent-Type: application/json
An adaptive link response includes URLs that users can access to detect and install a pass.
404
Could not find or create Dynamic Link object(s).
Get passes from Adaptive Link
Example request
GET /v1/links/adaptive/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/jsonResponse
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [
{
"id": 39,
"templateId": 6,
"serialNumber": "6f019144-2285-4bb9-b28a-f863af887e53",
"createdAt": "2019-03-06T17:48:28.000Z",
"updatedAt": "2019-03-06T17:48:29.000Z",
"externalId": "ext14"
},
{
"id": 38,
"templateId": 5,
"serialNumber": "7f57d625-cf7c-455b-b3d9-c70adef7d889",
"createdAt": "2019-03-06T17:39:00.000Z",
"updatedAt": "2019-03-06T17:39:01.000Z",
"externalId": "ext14"
}
]
}GET /links/adaptive/{adaptiveLinkId}/passes/id/{passExternalId}
Get passes with an external IDs that were created from an adaptive link.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
passExternalId : StringREQUIRED
The external ID of the pass you want to get.
adaptiveLinkId : StringREQUIRED
The adaptive link passes were created from.
Responses
200
Returns an array up to two passes created from the adaptive link — one for each template supported by the adaptive link.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESpasses : Array [Object]
The metadata for passes associated with the adaptive link. Each object in the array represents a pass. Max items: 2 Min items: 1
ARRAY ITEMPass Metadata
Meta information about passes.
OBJECT PROPERTIEScreatedAt : String
The date and time when the item was last updated. Format:
date-timeid : Integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
installedAt : String
The date and time when pass was first installed on the device. Format:
date-timeplatform : String
Wallet platform.
Possible values:
iOS,AndroidserialNumber : String
The serial number of the pass.
status : String
Recent on-device pass status.
Possible values:
installed,uninstalled,not_been_installedtemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
uninstalledAt : String
The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format:
date-timeupdatedAt : String
The date and time when the item was created. Format:
date-timeurl : String
Pass download URL.
404
The adaptive link or pass ID does not exist.
Update passes from Adaptive Link
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
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"tickets": [
{
"id": 15
},
{
"id": 16
}
]
}PUT /links/adaptive/{adaptiveLinkId}/passes/id/{passExternalId}
Update a pass with an external ID that was created from an adaptive link. You need only provide the fields and headers you want to update for the pass; all other information will remain unchanged.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
passExternalId : StringREQUIRED
The external ID of the pass you want to update.
adaptiveLinkId : StringREQUIRED
The adaptive link passes were created from.
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/json
Update Apple Wallet Pass : Object
OBJECT PROPERTIESbeacons : Array [Beacon object (iOS only)]
You can only include beacons for Apple Wallet passes.
fields : Object
The fields you want update on the pass.
headers : Object
The headers you want to update for this pass.
locations : Array [Location object]
The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
Responses
200
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 BODYContent-Type: application/json
OBJECT PROPERTIEStickets : Array [Object]
Max items: 2 Min items: 1
ARRAY ITEM- OBJECT PROPERTIES
ticketId : Integer
A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.
- OBJECT PROPERTIES
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
Example request
GET /v1/links/adaptive/rthBWAWDaAA/passes HTTP/1.1
Authorization: Basic <authorization string>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 616,
"templateId": 1000057,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/616/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da0b8",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "installed",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 610,
"templateId": 1000083,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/610/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e216",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}GET /links/adaptive/{adaptiveLinkId}/passes
List passes for an adaptive link.
Security:
query PARAMETERSstatus : 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_installedpageSize : Integer
The number of passes per page. Defaults to 10.
page : Integer
The page of results you want to retrieve, starting at 1.
order : String
The order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtdirection : String
Determines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESC
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
adaptiveLinkId : StringREQUIRED
The adaptive link ID used for pass creation.
Responses
200
A successful request returns a paged list of passes for a particular adaptive link.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIEScount : Integer
The total number of passes associated with an adaptive link.
pagination : 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.
ARRAY ITEMPass Metadata
Meta information about passes.
OBJECT PROPERTIEScreatedAt : String
The date and time when the item was last updated. Format:
date-timeid : Integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
installedAt : String
The date and time when pass was first installed on the device. Format:
date-timeplatform : String
Wallet platform.
Possible values:
iOS,AndroidserialNumber : String
The serial number of the pass.
status : String
Recent on-device pass status.
Possible values:
installed,uninstalled,not_been_installedtemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
uninstalledAt : String
The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format:
date-timeupdatedAt : String
The date and time when the item was created. Format:
date-timeurl : String
Pass download URL.
404
The adaptive link ID does not exist.
List passes
Example request
GET /v1/pass?templateId=12345&status=uninstalled HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 61,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
"createdAt": "2023-04-19T06:17:01.000Z",
"updatedAt": "2023-04-19T06:17:01.000Z",
"status": "uninstalled",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 60,
"templateId": 12345,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/60/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e201",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "android"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}GET /pass
List passes that your user account is responsible for. You can provide an optional template parameter, returning passes created from a particular template.
Security:
query PARAMETERStemplateId : String
The
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_installedpageSize : Integer
The number of passes per page. Defaults to 10.
page : Integer
The page of results you want to retrieve, starting at 1.
order : String
The order you want passes returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtdirection : String
Determines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESC
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
Responses
200
A successful request returns a paged list of passes created from a particular template.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIEScount : Integer
The total number of passes associated with the template.
pagination : 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.
ARRAY ITEMPass Metadata
Meta information about passes.
OBJECT PROPERTIEScreatedAt : String
The date and time when the item was last updated. Format:
date-timeid : Integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
installedAt : String
The date and time when pass was first installed on the device. Format:
date-timeplatform : String
Wallet platform.
Possible values:
iOS,AndroidserialNumber : String
The serial number of the pass.
status : String
Recent on-device pass status.
Possible values:
installed,uninstalled,not_been_installedtemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
uninstalledAt : String
The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format:
date-timeupdatedAt : String
The date and time when the item was created. Format:
date-timeurl : String
Pass download URL.
Get pass
Example request
GET /v1/pass/1234 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
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",
"url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/1249\/download",
"fields": {
"Merchant Website": {
"formatType": "URL",
"changeMessage": "Get event details at %@",
"order": 2,
"fieldType": "back",
"value": "http:\/\/www.test.com",
"label": "Merchant Website",
"required": false,
"hideEmpty": false
},
"More Details": {
"formatType": "String",
"changeMessage": "%@",
"order": 1,
"fieldType": "back",
"value": "More details about how to use this event ticket. Additional terms and support information.",
"label": "More Details",
"required": false,
"hideEmpty": false
},
"Seat": {
"textAlignment": "textAlignmentNatural",
"changeMessage": "You are now seated at %@",
"numberStyle": "PKNumberStyleDecimal",
"label": "Seat",
"hideEmpty": false,
"formatType": "Number",
"value": 1.0,
"fieldType": "auxiliary",
"required": false,
"order": 3
},
"Row": {
"textAlignment": "textAlignmentNatural",
"changeMessage": "You are now seated in row %@",
"numberStyle": "PKNumberStyleDecimal",
"label": "Row",
"hideEmpty": false,
"formatType": "Number",
"value": 1.0,
"fieldType": "auxiliary",
"required": false,
"order": 2
},
"Section": {
"textAlignment": "textAlignmentLeft",
"changeMessage": "You are now seated in section %@",
"label": "Section",
"hideEmpty": false,
"formatType": "String",
"value": "1",
"fieldType": "auxiliary",
"required": true,
"order": 1
}
}
}GET /pass/{id}
Get the specified pass. This endpoint will return the external ID of a pass, but only if there is one associated with it.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
id : StringREQUIRED
The
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 BODYContent-Type: application/json
One ofApple Wallet pass response
A pass response includes both identifiers and the content of all fields on a pass.
Google Wallet pass response
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
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
Update expiration date example request
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2024-08-20T9:41-08:00"
}
},
"fields": {
"Seat": {
"value": "26E"
}
}
}Render pass void example request
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"label": "voided"
}
}
}Example request
PUT /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.store.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons": [
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 1,
"minor": 777
},
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship"
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
]
}Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 1234
}PUT /pass/{id}
Update the specified pass. You need only include the fields that you want to update for the pass.
Optionally, you can also Schedule an update if you want to update a pass at a later date and time. See the /schedules endpoints for information about scheduling updates.
Do not use the response payload from the GET /v1/pass/(id) endpoint to update a pass, as it contains information from both the pass itself and the template used to create the pass, and you cannot update a template from the /v1/pass endpoint. You should only populate the JSON Parameters below. Within the headers and fields objects, these are the changeMessage, value, and label fields.
You can update locations on a pass, but doing so will replace all locations on the pass. See the Location Object for more about the fields you should provide in the locations array.
You can also update a pass to include an expiration date using the expirationDate key.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
id : StringREQUIRED
The
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/json
Update Apple Wallet Pass : Object
OBJECT PROPERTIESbeacons : Array [Beacon object (iOS only)]
You can only include beacons for Apple Wallet passes.
fields : Object
The fields you want update on the pass.
headers : Object
The headers you want to update for this pass.
locations : Array [Location object]
The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
Responses
200
A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.
RESPONSE BODYContent-Type: application/json
One ofApple Wallet pass response
A pass response includes both identifiers and the content of all fields on a pass.
Google Wallet pass response
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
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
Example request
POST /v1/pass/123 HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2014-08-20T09:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.store.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
],
"publicUrl": {
"type": "single"
}
}Response
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
}
]
}POST /pass/{id}
Create a pass from the specified template.
You can optionally assign an external ID to the pass or generate the pass from templates with external IDs. See the appropriate endpoints to assign or use external IDs.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
id : StringREQUIRED
The
idof the template you want to create your pass from.
Request Body
Create a pass; pass composition varies by vendor.
Content-Type: application/json
One ofApple Wallet pass request
A pass for Apple Wallet.
Google Wallet pass request
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 BODYContent-Type: application/json
One ofApple Wallet pass response
A pass response includes both identifiers and the content of all fields on a pass.
Google Wallet pass response
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
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
Example request
DELETE /v1/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"status": "deleted",
"passId": "123"
}DELETE /pass/{id}
Delete the specified pass.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
id : StringREQUIRED
The
idof the pass you want to delete.
Responses
200
The pass was successfully deleted.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESpassId : 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
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.store.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
],
"publicURL": {
"type": "single"
},
"externalId": "abcd"
}Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"url": "https://wallet-api.urbanairship.com/v1/pass/dynamic/44e128a5-ac7a-4c9a-be4c-224b6bf81b20"
}POST /pass/{id}/dynamic
Generates a pass with an optional expiration date and serial number. You can also assign an external ID to passes generated from this endpoint.
Security:
query PARAMETERSexpiry : String
The expiration date for the pass.
Format:
date
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
id : StringREQUIRED
The
templateIdof the template you want to create the pass from.
Request Body
Create a pass; pass composition varies by vendor.
Content-Type: application/json
One ofApple Wallet pass request
A pass for Apple Wallet.
Google Wallet pass request
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 BODYContent-Type: application/json
One ofApple Wallet pass response
A pass response includes both identifiers and the content of all fields on a pass.
Google Wallet pass response
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
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
Example request
DELETE /v1/pass/123/location/456 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2DELETE /pass/{passId}/location/{passLocationId}
Delete the specified location from the specified pass.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
passId : StringREQUIRED
The
idof the pass you want to remove locations from.passLocationId : StringREQUIRED
The location you want to remove from the pass.
Responses
200
Success.
RESPONSE BODYContent-Type: application/json
OBJECT PROPERTIESlocations : Array [Location object]
Add locations to pass
Example request
POST /v1/pass/123/locations HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"locations": [
{
"longitude": "-122.374",
"latitude": "37.618",
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
},
{ "...": "..." }
]
}Response
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"
}
}
]POST /pass/{passId}/locations
Add the locations to the specified pass.
As of August 2020, Location triggers are unavailable for all mobile devices upgraded to Google Play Services, which affects most Google Wallet passes. Google has not announced when they will make Location triggers available again.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
passId : StringREQUIRED
The pass you want to add locations to.
Request Body
Set locations for the pass.
Content-Type: application/json
Object
OBJECT PROPERTIESlocations : Array [Location object]
Responses
200
Returns
passLocationIdfor each location on the pass. Use this value to identify locations in other location-based operations.RESPONSE BODYContent-Type: application/json
ARRAY ITEM- OBJECT PROPERTIES
passLocationId : Integer
The identifier for a location.
value : Location object
Represents a location on a pass or an adaptive link.
Place objects in the locations array to add location information to passes and templates. Updating locations on a pass or template will replace all locations on that pass; if you want to add to the locations on a pass, you must provide all locations already included on the pass and any additional locations you want to add.
Apple Wallet supports up to 10 locations per pass. If you exceed this limit for an iOS pass, we will use the 10 locations nearest to a user (located by IP address) when they install the pass.
- OBJECT PROPERTIES
List passes for a tag
Example request
GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"passes": [{
"id": 61,
"templateId": 1000057,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
"serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
"createdAt": "2023-04-19T06:15:01.000Z",
"updatedAt": "2023-04-19T06:15:01.000Z",
"status": "installed",
"installedAt": "2023-04-19T06:17:02.000Z",
"platform": "android"
},
{
"id": 51,
"templateId": 1000081,
"url": "https://d720-104-177-34-165.ngrok.io/v1/pass/51/download",
"serialNumber": "34b6f9de-3745-4107-99ae-3f952208e223",
"createdAt": "2023-04-05T17:55:23.000Z",
"updatedAt": "2023-04-05T17:55:23.000Z",
"status": "installed",
"installedAt": "2023-04-05T17:55:23.000Z",
"platform": "ios"
}
],
"pagination": {
"order": "id",
"direction": "desc",
"page": 1,
"start": 0,
"pageSize": 2
}
}GET /tag/{tag}/passes
List the passes associated with the specified tag.
Security:
query PARAMETERSstatus : 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_installedpageSize : Integer
The number of passes per page. Defaults to 10.
page : Integer
The page of results you want to retrieve, starting at 1.
order : String
The order you want tags returned in, defaulting to
id.Possible values:
id,createdAt,updatedAtdirection : String
Determines whether to return values in ascending or descending order. Defaults to
DESC.Possible values:
ASC,DESC
Api-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
tag : StringREQUIRED
A 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 BODYContent-Type: application/json
OBJECT PROPERTIEScount : Integer
The total number of results.
pagination : Pagination object
Contains information about pagination, according to your query parameters.
passes : Object
Meta information about passes.
OBJECT PROPERTIEScreatedAt : String
The date and time when the item was last updated. Format:
date-timeid : Integer
The internal identifier for the pass. Use this ID to get or modify the pass in other calls.
installedAt : String
The date and time when pass was first installed on the device. Format:
date-timeplatform : String
Wallet platform.
Possible values:
iOS,AndroidserialNumber : String
The serial number of the pass.
status : String
Recent on-device pass status.
Possible values:
installed,uninstalled,not_been_installedtemplateId : Integer
The identifier for the template. You can recall the template by ID in other operations.
uninstalledAt : String
The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled. Format:
date-timeupdatedAt : String
The date and time when the item was created. Format:
date-timeurl : 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
Example request
PUT /v1/pass/id/myExternalPassId HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"templates": ["5350", "5359"],
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.store.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons": [
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 1,
"minor": 777
},
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship"
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
]
}Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"ticketId": 1234
}PUT /pass/id/{externalId}
Update the specified pass. You need only include the fields that you want to update for the pass.
Do not use the response payload from a GET to update a pass, as it contains information from both the pass itself and the template used to create the pass, and you cannot update a template from the /v1/pass endpoint. You should only populate the JSON Parameters below. Within the headers and fields objects, these are the changeMessage, value, and label fields.
You can update locations on a pass, but doing so will replace all locations on the pass. See the Location Object for more about the fields you should provide in the locations array.
You can also update a pass to include an expiration date using the expirationDate key.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
externalId : StringREQUIRED
The external ID of the pass you want to modify.
Request Body
Provide only the fields you want to update.
Locations operate as a set operation. The array of pass locations is replaced by the locations you provide in an update; if you want to add to the locations on the pass, you must provide both the current locations and the locations you want to add in the payload.
Content-Type: application/json
All ofObject
OBJECT PROPERTIEStemplates : Array [Integer]
Include an array of templates IDs, required to identify individual passes if there are multiple passes for the external ID in the path. If there are multiple passes for the external ID and you do not specify the templates corresponding to the passes you want to update, your request will return a 400.
Update Apple Wallet Pass : Object
OBJECT PROPERTIESbeacons : Array [Beacon object (iOS only)]
You can only include beacons for Apple Wallet passes.
fields : Object
The fields you want update on the pass.
headers : Object
The headers you want to update for this pass.
locations : Array [Location object]
The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
Responses
200
A response returns one or more
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 BODYContent-Type: application/json
One ofObject
OBJECT PROPERTIESticketId : Integer
A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.
Array [Object]
ARRAY ITEM- OBJECT PROPERTIES
ticketId : Integer
A ticket you can use to reference this operation for status, troubleshooting, or logging purposes.
- OBJECT PROPERTIES
Create pass from a template
Example request
POST /v1/pass/id/myExternalTemplate/id/myNewPass HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2014-08-20T09:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.store.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
],
"publicUrl": {
"type": "single"
}
}Response
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
}
]
}POST /pass/id/{templateExternalId}/id/{passExternalId}
Create a pass from the specified template and give it a custom identifier. You can use this custom ID to perform operations against the pass in addition to the standard, unique id given by Wallet.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
templateExternalId : StringREQUIRED
The external ID of the template you want to create your pass from.
passExternalId : StringREQUIRED
The external ID that you want to give your pass.
Request Body
Create a pass; pass composition varies by vendor.
Content-Type: application/json
One ofApple Wallet pass request
A pass for Apple Wallet.
Google Wallet pass request
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 BODYContent-Type: application/json
One ofApple Wallet pass response
A pass response includes both identifiers and the content of all fields on a pass.
Google Wallet pass response
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
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
Example request
GET /v1/pass/template/123/id/mypass HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2Response
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",
"url": "https:\/\/wallet-api.urbanairship.com\/v1\/pass\/1249\/download",
"fields": {
"Merchant Website": {
"formatType": "URL",
"changeMessage": "Get event details at %@",
"order": 2,
"fieldType": "back",
"value": "http:\/\/www.test.com",
"label": "Merchant Website",
"required": false,
"hideEmpty": false
},
"More Details": {
"formatType": "String",
"changeMessage": "%@",
"order": 1,
"fieldType": "back",
"value": "More details about how to use this event ticket. Additional terms and support information.",
"label": "More Details",
"required": false,
"hideEmpty": false
},
"Seat": {
"textAlignment": "textAlignmentNatural",
"changeMessage": "You are now seated at %@",
"numberStyle": "PKNumberStyleDecimal",
"label": "Seat",
"hideEmpty": false,
"formatType": "Number",
"value": 1.0,
"fieldType": "auxiliary",
"required": false,
"order": 3
},
"Row": {
"textAlignment": "textAlignmentNatural",
"changeMessage": "You are now seated in row %@",
"numberStyle": "PKNumberStyleDecimal",
"label": "Row",
"hideEmpty": false,
"formatType": "Number",
"value": 1.0,
"fieldType": "auxiliary",
"required": false,
"order": 2
},
"Section": {
"textAlignment": "textAlignmentLeft",
"changeMessage": "You are now seated in section %@",
"label": "Section",
"hideEmpty": false,
"formatType": "String",
"value": "1",
"fieldType": "auxiliary",
"required": true,
"order": 1
}
}
}GET /pass/template/{templateId}/id/{passExternalId}
Get a pass with an external ID.
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
passExternalId : StringREQUIRED
The custom ID assigned to the pass.
templateId : StringREQUIRED
The ID of the template the pass will be or was created from.
Responses
200
A response is a populated pass and meta information about the pass. The pass response includes fields that are read only, some of which are populated directly from the template specified in the request.
RESPONSE BODYContent-Type: application/json
One ofApple Wallet pass response
A pass response includes both identifiers and the content of all fields on a pass.
Google Wallet pass response
A pass response for Google Wallet. A pass is a populated template. Therefore, the pass includes all headers and fields from the template, along with identifiers for the pass and URLs to access it.
Unlike templates, in which the
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
Example request
PUT /v1/pass/template/123/id/mypass HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.store.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons": [
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 1,
"minor": 777
},
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship"
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
]
}Response
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
"ticketId": 1234
}PUT /pass/template/{templateId}/id/{passExternalId}
Update a pass with an external ID
Security:
header PARAMETERSApi-Revision : StringREQUIRED
The particular API revision you want to use. In general, this is
1.2.Possible values:
1.2
passExternalId : StringREQUIRED
The external ID of the pass you want to modify.
templateId : StringREQUIRED
The ID of the template the pass will be or was created from.
Request Body
Update a pass. You can provide any of the fields or headers used when creating a pass to update the pass.
Content-Type: application/json
One ofApple Wallet pass request
A pass for Apple Wallet.
Google Wallet pass request
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 BODYContent-Type: application/json
OBJECT PROPERTIESticketId : Integer
An identifier for this operation.
400
The request was malformed.
404
The pass or template ID does not exist.
Create pass
Example request
POST /v1/pass/template/123/id/mypass HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2
{
"headers": {
"expirationDate": {
"value": "2014-08-20T09:41-08:00"
},
"barcodeAltText": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
},
"barcode_value": {
"changeMessage": null,
"value": "abc1234567890",
"label": ""
}
},
"fields": {
"Coupon": {
"changeMessage": "Enjoy %@ off your next order!",
"value": "20%",
"label": "Coupon"
},
"SiteAddress": {
"changeMessage": "Check out things we think you would like at %@",
"value": "https://www.store.com/new?custnumb=123456",
"label": "personal deals"
},
"InStore": {
"changeMessage": "Or visit your nearest store at %@",
"value": "1234 Fake St.",
"label": "nearestStore"
},
"thumbnail_image": {
"value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
}
},
"beacons":[
{
"uuid": "55502220-A123-A88A-F321-555A444B333C",
"relevantText": "You are near the Ship",
"major": 2,
"minor": 346
}
],
"locations":[
{
"longitude": -122.374,
"latitude": 37.618,
"relevantText": "Hello loc0",
"streetAddress1": "address line #1",
"streetAddress2": "address line #2",
"city": "San Francisco",
"region": "CA",
"regionCode": "94404",
"country": "US"
}
],
"publicUrl": {
"type": "single"
}
}Response
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
},
</