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.

Create Adaptive Link

Create an adaptive link with an external ID. The adaptiveLinkExternalID you use in the path becomes the ID for your new adaptive link.

Jump to examples ↓

POST /links/adaptive/project/{projectId}/id/{adaptiveLinkExternalId}

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

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. If you need to create a boarding pass adaptive link, go to the boarding pass object.

Responses

200
A successful request results in an adaptive link.
Response body:
- Content-Type: application/json
  Adaptive Link response
  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).

Examples

POST /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
    "iosTemplateId": 54321,
    "androidTemplateId": 54322,
    "isPersonalized": false,
    "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
    "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
    "landingPageUrl": "https://example.com/landing.html",
    "availablePasses": 100000,
    "payload": {}
}

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

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://example.com/landing.html",
  "isPersonalized": false,
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 730,
  "iosTemplateId": 54321,
  "androidTemplateId": 54322,
  "projectId": 12345,
  "createdAt": "2019-05-28T23:55:00.000Z",
  "updatedAt": "2019-05-31T00:59:42.000Z",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
  "status": 200
}

Create Adaptive Link in project

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.

Jump to examples ↓

POST /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

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. If you need to create a boarding pass adaptive link, go to the boarding pass object.

Responses

200
A successful request results in an adaptive link.
Response body:
- Content-Type: application/json
  Adaptive Link response
  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).

Examples

POST /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
    "iosTemplateExternalId": "ios123ExtId",
    "androidTemplateExternalId": "android123ExtId",
    "isPersonalized": "true",
    "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
    "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
    "landingPageUrl": "https://example.com/landing.html",
    "availablePasses": 100000,
    "payload": {}
}

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

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://example.com/landing.html",
  "isPersonalized": false,
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 730,
  "iosTemplateId": 54321,
  "iosTemplateExternalId": "ios123ExtId",
  "androidTemplateId": 54322,
  "androidTemplateExternalId": "android123ExtId",
  "projectId": 12345,
  "projectExternalId": "myExternalProject",
  "createdAt": "2019-05-28T23:55:00.000Z",
  "updatedAt": "2019-05-31T00:59:42.000Z",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
  "status": 200
}

Get Adaptive Link

Get an adaptive link with an external ID.

Jump to examples ↓

GET /links/adaptive/project/{projectId}/id/{adaptiveLinkExternalId}

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

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 body:
- Content-Type: application/json
  Adaptive Link response
  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.

Examples

GET /v1/links/adaptive/project/12345/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>

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

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://example.com/landing.html",
  "isPersonalized": false,
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 730,
  "iosTemplateId": 54321,
  "androidTemplateId": 54322,
  "projectId": 12345,
  "createdAt": "2019-05-28T23:55:00.000Z",
  "updatedAt": "2019-05-31T00:59:42.000Z",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
  "status": 200
}

Get Adaptive Link from project

Get an adaptive link with an external ID from a project that also has an external ID.

Jump to examples ↓

GET /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

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 body:
- Content-Type: application/json
  Adaptive Link response
  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.

Examples

GET /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink HTTP/1.1
Authorization: Basic <authorization string>

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

{
  "adaptiveLinkId": "1KVMz6NlFb",
  "adaptiveLinkExternalId": "coolNewAdaptiveLink",
  "url": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb",
  "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/ios",
  "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/adaptive/1KVMz6NlFb/android",
  "landingPageUrl": "https://example.com/landing.html",
  "isPersonalized": false,
  "isExpired": false,
  "availablePasses": 100000,
  "ttlInDays": 730,
  "iosTemplateId": 54321,
  "iosTemplateExternalId": "ios123ExtId",
  "androidTemplateId": 54322,
  "androidTemplateExternalId": "android123ExtId",
  "projectId": 12345,
  "projectExternalId": "myExternalProject",
  "createdAt": "2019-05-28T23:55:00.000Z",
  "updatedAt": "2019-05-31T00:59:42.000Z",
  "iosPassLinkId": "44e128a5-ac7a-4c9a-be4c-224b6bf81b20",
  "androidPassLinkId": "19d128a6-ac7a-3c6c-2a4d-214b6bf81b21",
  "status": 200
}

Get pass from Adaptive Link

Get a pass with an external ID that was created from an adaptive link with an external ID.

Jump to examples ↓

GET /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes/id/{passExternalId}

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

projectExternalId stringREQUIRED
The external ID of the project containing the adaptive link.
adaptiveLinkExternalId stringREQUIRED
The adaptive link passes were created from.
passExternalId stringREQUIRED
The external ID of the pass you want to get.

Responses

200
Returns an array up to two passes created from the adaptive link — one for each template supported by the adaptive link.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - passes array[object]
    The metadata for passes associated with the adaptive link. Each object in the array represents a pass.
404
The project, adaptive link, or pass ID does not exist.

Examples

GET /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>

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

{
    "passes": [
        {
            "id": 39,
            "templateId": 6,
            "serialNumber": "6f019144-2285-4bb9-b28a-f863af887e53",
            "createdAt": "2019-03-06T17:48:28.000Z",
            "updatedAt": "2019-03-06T17:48:29.000Z",
            "externalId": "ext14"
        },
        {
            "id": 38,
            "templateId": 5,
            "serialNumber": "7f57d625-cf7c-455b-b3d9-c70adef7d889",
            "createdAt": "2019-03-06T17:39:00.000Z",
            "updatedAt": "2019-03-06T17:39:01.000Z",
            "externalId": "ext14"
        }
    ]
}

Get passes from Adaptive Link

Get passes with an external IDs that were created from an adaptive link.

Jump to examples ↓

GET /links/adaptive/{adaptiveLinkId}/passes/id/{passExternalId}

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

adaptiveLinkId stringREQUIRED
The adaptive link passes were created from.
passExternalId stringREQUIRED
The external ID of the pass you want to get.

Responses

200
Returns an array up to two passes created from the adaptive link — one for each template supported by the adaptive link.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - passes array[object]
    The metadata for passes associated with the adaptive link. Each object in the array represents a pass.
404
The adaptive link or pass ID does not exist.

Examples

GET /v1/links/adaptive/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

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

{
    "passes": [
        {
            "id": 39,
            "templateId": 6,
            "serialNumber": "6f019144-2285-4bb9-b28a-f863af887e53",
            "createdAt": "2019-03-06T17:48:28.000Z",
            "updatedAt": "2019-03-06T17:48:29.000Z",
            "externalId": "ext14"
        },
        {
            "id": 38,
            "templateId": 5,
            "serialNumber": "7f57d625-cf7c-455b-b3d9-c70adef7d889",
            "createdAt": "2019-03-06T17:39:00.000Z",
            "updatedAt": "2019-03-06T17:39:01.000Z",
            "externalId": "ext14"
        }
    ]
}

Update passes from Adaptive Link

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.

Jump to examples ↓

PUT /links/adaptive/project/id/{projectExternalId}/id/{adaptiveLinkExternalId}/passes/id/{passExternalId}

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

projectExternalId stringREQUIRED
The external ID of the project containing the adaptive link.
adaptiveLinkExternalId stringREQUIRED
The adaptive link passes were created from.
passExternalId stringREQUIRED
The external ID of the pass you want to update.

Request body:

Provide only the fields or headers that you want to update for the specified pass.

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

Content-Type: application/json
Update Wallet Pass
OBJECT PROPERTIES
- beacons arrayAPPLE ONLY
  An array of beacon objects you want to update for this pass.
- fields object
  The fields you want to update on the pass.
- headers object
  The headers you want to update for this pass.
- locations array
  The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
- semantics object<Boarding pass semantics>
  An object that defines structured metadata for an Apple Wallet pass using key-value pairs. These semantic tags provide contextual information to the system to enhance the user experience.
  For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within fields.
- universalLinks object<Universal links>
  An object containing key-value pairs of universal links where each key-value pair defines a universal link.
  A list of key-value pairs that represents partner URLs.

Responses

200
Returns a ticket IDs corresponding to the templates the adaptive link generated passes from. For example, if the pass was installed on both Android and iOS devices, the response will include two tickets — one to update passes supported by each template.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - tickets array[object]
404
The project, adaptive link, or pass ID does not exist.

Examples

PUT /v1/links/adaptive/project/id/myExternalProject/id/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
    "fields": {
      "Details": {
          "changeMessage": "Enjoy %@ off your next order!",
          "value": "20%",
          "label": "Coupon"
      },
      "thumbnail_image": {
          "value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
      }
    },
    "beacons": [
      {
          "uuid": "55502220-A123-A88A-F321-555A444B333C",
          "relevantText": "You are near the Ship",
          "major": 1,
          "minor": 777
      }
    ],
    "locations":[
      {
          "longitude": -122.374,
          "latitude": 37.618,
          "relevantText": "Hello loc0",
          "streetAddress1": "address line #1",
          "streetAddress2": "address line #2",
          "city": "San Francisco",
          "region": "CA",
          "regionCode": "94404",
          "country": "US"
      }
    ]
}

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

{
    "tickets": [
        {
            "id": 15
        },
        {
            "id": 16
        }
    ]
}

Update passes from Adaptive Link

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.

Jump to examples ↓

PUT /links/adaptive/{adaptiveLinkId}/passes/id/{passExternalId}

Security:

httpBasic

Request headers:

Api-Revision stringREQUIRED
The particular API revision you want to use. In general, this is 1.2.
Possible values: 1.2

Path parameters:

adaptiveLinkId stringREQUIRED
The adaptive link passes were created from.
passExternalId stringREQUIRED
The external ID of the pass you want to update.

Request body:

Provide only the fields or headers that you want to update for the specified pass.

Content-Type: application/json
Update Wallet Pass
OBJECT PROPERTIES
- beacons arrayAPPLE ONLY
  An array of beacon objects you want to update for this pass.
- fields object
  The fields you want to update on the pass.
- headers object
  The headers you want to update for this pass.
- locations array
  The locations you want to update for this pass. Location updates replace existing locations on the pass. When updating locations, you should provide all the locations that you want to remain on the pass.
- semantics object<Boarding pass semantics>
  An object that defines structured metadata for an Apple Wallet pass using key-value pairs. These semantic tags provide contextual information to the system to enhance the user experience.
  For Apple boarding passes only, a JSON object that uses key-value pairs to add rich, machine-readable data that enhances passes. You can nest this object within fields.
- universalLinks object<Universal links>
  An object containing key-value pairs of universal links where each key-value pair defines a universal link.
  A list of key-value pairs that represents partner URLs.

Responses

200
Returns a ticket IDs corresponding to the templates the adaptive link generated passes from. For example, if the pass was installed on both Android and iOS devices, the response will include two tickets — one to update passes supported by each template.
Response body:
- Content-Type: application/json
  OBJECT PROPERTIES
  - tickets array[object]
404
The adaptive link or pass ID does not exist.

Examples

PUT /v1/links/adaptive/coolNewAdaptiveLink/passes/id/mypass HTTP/1.1
Authorization: Basic <authorization string>
Content-Type: application/json

{
    "fields": {
      "Details": {
          "changeMessage": "Enjoy %@ off your next order!",
          "value": "20%",
          "label": "Coupon"
      },
      "thumbnail_image": {
          "value": "https:\/\/wallet.urbanairship.com\/assets\/favicon.png"
      }
    },
    "beacons": [
      {
          "uuid": "55502220-A123-A88A-F321-555A444B333C",
          "relevantText": "You are near the Ship",
          "major": 1,
          "minor": 777
      }
    ],
    "locations":[
      {
          "longitude": -122.374,
          "latitude": 37.618,
          "relevantText": "Hello loc0",
          "streetAddress1": "address line #1",
          "streetAddress2": "address line #2",
          "city": "San Francisco",
          "region": "CA",
          "regionCode": "94404",
          "country": "US"
      }
    ]
}

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

{
    "tickets": [
        {
            "id": 15
        },
        {
            "id": 16
        }
    ]
}