Flights and Boarding Passes

Managing boarding passes in Reach involves some unique differences from other pass types. This document covers information about flights, passengers, and boarding passes.

Note

While you can create and modify boarding pass templates from the dashboard, all other operations — flight creation, creating adaptive links with flight and passenger information, etc. — are performed through the API.

Boarding Pass Composition

A boarding pass is an adaptive link that references a boarding pass template, populated with one or more flights and one or more passengers per flight.

While boarding passes resemble adaptive links for other pass types, you cannot create a boarding pass using the standard dashboard or /links/adaptive methods. You must use the /links/adaptive/multiple/project endpoints instead.

A boarding pass works much like a standard adaptive link, with the following differences.

  • Boarding pass templates are referenced by ID in the adaptive link payload. Your request must include at least one of iosTemplate or googleTemplate (or external ID equivalents iosTemplateExternalId, androidTemplateExternalId).
  • Flights are referenced by ID in the adaptive link payload OR provided as an object in the payload.
  • Passengers are objects referenced within the flight object for each flight in the payload.
  • Assets referenced by ID (templates, flights, etc.) must belong to the same project; you cannot use combinations of flights or templates across projects to create a boarding pass.

Flights

The flights endpoint provides a mechanism to create and modify flight information for boarding passes, independent of adaptive links. The result of a successful POST or PUT call is a flightId. By referencing flights by ID, you can simplify adaptive link payloads and propagate changes to flights — delays, gate changes, etc. — to a group of passes associated with that flight.

While you can issue a flight object when creating an adaptive link, the Flights endpoint can help you manage flight information without having to deal with a host of adaptive links referencing the same flight; you can modify one flight and affect all adaptive links or passes associated with the flight.

Flight Request Example:

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

{
  "fields": {
    "flightNumber": { "value": "815" },
    "airlineCode": { "value": "WN" },
    "airlineName": { "value": "Southwest Airlines" },
    "departureAirport": {
      "label": "San Francisco",
      "value": "SFO"
    },
    "departureGate": {
      "label": "Gate #",
      "value": "25"
    },
    "boardingTime": { "value": "2018-07-30T08:35:00" },
    "departureTime": { "value": "2018-07-30T09:00:00" },
    "arrivalAirport": {
      "label": "Portland",
      "value": "PDX"
    },
    "arrivalTime": { "value": "2018-07-30T11:00:00" },
    "flightStatus": { "value": "scheduled" }
  }
}

External IDs for Flights

You can create a flight with a custom identifier using the /v1/flights/project/id/ (projectExternalId/id/(flightExternalId) endpoint. A request specifying an external flight ID returns the custom identifier as flightExternalId, and you reference flights using this external identifier in lieu of the standard flightId in subsequent payloads, including the request to create boarding pass adaptive links.

Passengers

The passengers array appears within an individual flight object when creating boarding pass adaptive links. Each object in the array represents an individual passenger on a flight, and a recipient of an adaptive link.

Example Passenger Array:

{
  "passengers": [
    {
      "fields": {
        "passengerName": { "value": "SMITH/JOE" },
        "seatNumber": { "value": "13A" },
        "seatClass": { "value": "Economy" },
        "boardingGroup": { "value": "5" },
        "securityProgram": { "value": "tsaPrecheck" },
        "confirmationCode": { "value": "E4583B" },
        "eticketNumber": { "value": "20595923485" },
        "frequentFlyerProgramName": { "value": "Rapid Rewards®" },
        "frequentFlyerNumber": { "value": "34525" },
        "drinkCoupon":  { "label": "Drink Coupon", "value": "Premium Drink" },
        "fareType": { "label": "Fare Type", "value": "Business Select" },
        "specialAssistance": { "label": "Special Assistance", "value": "Wheelchair" }
      }
    }
  ]
}

Boarding Pass Templates

Boarding pass templates are not as customizable as other template types. Many of the fields on a boarding pass are required, like seat number, gate number, etc. These fields cannot have default values, nor can they be moved or customized in any way.

You can set colors, logos, and otherwise customize the general feel of your boarding pass. But with boarding passes, moreso than other pass types, you will focus less on templates, and much more on modifying the information that populates adaptive links built from those templates.

Note

For date-time fields on iOS boarding pass templates, you may want to set set ignoresTimeZone: true. Date-times for flights are set local to an airport terminal. Setting ignoresTimeZone: true prevents Apple Wallet from modifying times based on recipients' time zones.

Adaptive Links for Boarding Passes

Note

You must use the /links/adaptive/multiple/project/ endpoints to create boarding passes. While a boarding pass adaptive link has a similar request structure to other adaptive links, you cannot create boarding pass adaptive links through the standard /links/adaptive endpoint.

A boarding pass adaptive link is an adaptive link that generates or returns platform-appropriate passes of the boarding pass type. It is created from boarding pass templates and associated with flights and passengers.

When you create an adaptive link, you can specify flights by flightId — the identifier from a successful POST to the /flights endpoint. Templates and flights referenced by ID must belong to the same project.

Within each flight, you will specify passengers — an array of objects, each object representing an individual passenger with information like their seat number, boarding group, etc.

Example Adaptive Link Request:

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

{
  "availablePasses": 1,
  "iosTemplateExternalId": "<iosTemplateExternalId>",
  "androidTemplateExternalId": "<androidTemplateExternalId>",
  "payload": {
    "flights": [
      {
        "flightId": "<flightId1>",
        "passengers": [
          {
            "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
            "fields": {
              "seatNumber": { "value": "13A" },
              "confirmationCode": { "value": "E4583B" },
              "passengerName": { "value": "SMITH/JOE" },
              "specialAssistance": { "label": "Special Assistance", "value": "Wheelchair" }
            }
          },
          {
            "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
            "fields": {
              "seatNumber": { "value": "13B" },
              "confirmationCode": { "value": "E4583B" },
              "passengerName": { "value": "SMITH/SALLY" }
            }
          },
          {
            "adaptiveLinkExternalId": "<adaptiveLinkExternalId2>",
            "fields": {
              "seatNumber": { "value": "13C" },
              "confirmationCode": { "value": "E4583B" },
              "passengerName": { "value": "SMITH/SAM" }
            }
          }
        ]
      }
    ]
  }
}

Adaptive Link Response:

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

[
  {
      "status": 201,
      "adaptiveLinkId": "<uaAdaptiveLinkId1>",
      "adaptiveLinkExternalId": "<adaptiveLinkExternalId1>",
      "iosTemplateId": "<iosTemplateId>",
      "iosTemplateExternalId": "<iosTemplateExternalId>",
      "androidTemplateId": "<androidTemplateId>",
      "androidTemplateExternalId": "<androidTemplateExternalId>",
      "url": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber1>",
      "iosUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumbe1r>/ios",
      "androidUrl": "https://wallet-api.urbanairship.com/v1/pass/<adaptiveLinkSerialNumber1>/android",
      "createdAt": "2018-07-05T09:12:32Z",
      "updatedAt": "2018-07-05T09:12:32Z",
      "isPersonalized": "false",
      "availablePasses": 1000000,
      "flightId": 465,
      "flightExternalId": "<flightExternalId1>",
      "iosPassLinkId": "eb94e8e0-4353-4e0b-bfe9-cfd21c52a540",
      "androidPassLinkId": "41c1ea48-f469-4968-b610-a98629ea19bc"
  }
]

Modifying Flights and Passengers

Any endpoint you can provide a flight payload to will return a flightId. You can look up, modify, or delete a flight using this ID in the path of the /v1/flights endpoint, regardless of whether you created the flight using the /v1/flights endpoint or provided all flight information directly in an adaptive link payload.

Passenger objects exist on adaptive links (boarding passes). If you want to modify passengers on a flight (if a passenger moves seats, or cancels their ticket), you will do so by modifying adaptive links directly.

Modifying, Looking-up, and Deleting Boarding Passes

You can modify boarding pass adaptive links using a POST to /v1/links/adaptive/multiple/id/ {adaptiveLinkExternalId}. A POST call that specifies an existing adaptiveLinkExternalId is treated as a PUT, and updates the adaptive link accordingly. You cannot do the same with standard adaptiveLinkId. Therefore, you should expect to set external IDs for your adaptive links.

You can look up and delete boarding pass adaptive links using the standard GET and DELETE methods for the /v1/links/adaptive/{adaptiveLinkId} and /v1/links/adaptive/id/ {adaptiveLinkExternalId} endpoints.

Resources