Semantic tags for Apple Wallet boarding passes

About semantic tags

Semantic tags augment standard boarding pass fields without requiring changes to your existing template structure. Passes with semantic tags automatically deliver the appropriate experience based on the user’s iOS version.

Using the tags in boarding passes can transform your travelers’ experiences by enabling:

• Live Activities give real-time flight updates and can be shared so friends and family can follow along.
• Enhanced pass UI with airport maps, baggage tracking, and contextual information
• Intelligent notifications powered by structured flight and passenger data
• Seamless compatibility, where passes automatically provide the enhanced experience on iOS 26 while maintaining full backward compatibility with earlier iOS versions

Semantic tags are supported on devices running iOS 26 or later. On older versions, the semantic data is not rendered.

For more information, see Supporting semantic tags in Wallet passes  and the SemanticTags  object in Apple’s developer documentation.

iOS 26 boarding pass design and backward compatibility

Apple refreshed the boarding pass layout, behavior, and functionality for iOS 26. The updated design depends on the presence of semantic tags. Without them, your Apple boarding passes will render using the legacy design.

To preserve backward compatibility, design your boarding passes using standard (legacy) field data to support their appearance on devices running iOS versions lower than iOS 26.

Automatic tag mapping

Airship can automatically map standard boarding pass fields to semantic tags, so you can take advantage of Apple’s refreshed boarding pass experience immediately, without modifying your Wallet API integration.

To enable or disable the feature, go to Settings, then Project Details, and toggle Semantic tag auto-mapping for Apple Wallet.

You can keep auto-mapping enabled indefinitely. However, when you’re ready to unlock the full range of Apple’s capabilities, extend your Wallet API calls with additional semantic tag data. API-set values override auto-mapped ones.

The remainder of this guide walks you through using semantic tags in API calls.

Using semantic tags with boarding passes

First, define the flight in your project and design the pass’s visual appearance. Then you can generate Adaptive LinksA vendor-agnostic, shortened mobile wallet pass link that supports templates for both Google Wallet and Apple Wallet. When a user taps the link, Airship determines the user’s platform and generates the right pass for that platform. to distribute to users.

Create a flight

You can add semantic tags as key-value pairs within the semantics object at two levels:

• Top level — Within the fields object, provide flight-wide information like airport codes, gates, and departure times
• Field level — For individual fields, provide additional context such as whether a time is estimated or confirmed

A flight serves as the foundation that all boarding passes will reference, so when creating the object:

• Include semantic tags that apply to the entire flight experience, plus any field-level semantic tags you need.
• Populate canonical values wherever possible: IATA airport codes, ISO timestamps, marketing versus operating carrier, etc.

For a list of supported semantic tags, see the properties for the Flight semantics object in the Wallet API reference.

Include the flight object in the request body of a flight creation operation:

• Create flight
• Create flight with external ID

Note the flightId or flightExternalId in the response for reference when creating pass links.

Example flight object

The following example flight object contains these semantic tags:

• Field-level semantic tags — Individual field properties that provide context for specific values:
  • boardingTime with isEstimated: false indicates the boarding time is confirmed.
  • arrivalTime with isScheduled: true marks this as the scheduled arrival time.
  • boardingPolicy with priorityBoarding: true enables priority boarding features.
  • seatingPolicy with seatAssignmentRequired: true indicates seat assignments are required.
• Top-level flight semantic tags — Flight-wide information that enables iOS features:
  • Basic flight details: airline code, flight number, airport codes
  • Location details: terminal, gate, departure and destination cities
  • Time zone information for accurate time display
  • Original scheduled times for comparison with any updates

{
  "fields": {
    "airlineCode": { "value": "SAB" },
    "flightNumber": { "value": "1219" },
    "departureAirportCode": { "value": "SEA" },
    "arrivalAirportCode": { "value": "SFO" },
    "boardingTime": {
      "value": "2025-09-05T16:10:00-07:00",
      "semantics": { "isEstimated": false }
    },
    "arrivalTime": {
      "value": "2025-09-05T18:20:00-07:00",
      "semantics": { "isScheduled": true }
    },
    "boardingPolicy": {
      "value": "zoneBased",
      "semantics": { "priorityBoarding": true }
    },
    "seatingPolicy": {
      "value": "cabinBased",
      "semantics": { "seatAssignmentRequired": true }
    },
    "semantics": {
      "airlineCode": "SAB",
      "flightNumber": "1219",
      "departureAirportCode": "SEA",
      "destinationAirportCode": "SFO",
      "departureTerminal": "A25",
      "departureGate": "A21",
      "departureLocationTimeZone": "America/Los_Angeles",
      "departureCityName": "Seattle",
      "originalBoardingDate": "2025-09-05T16:10:00-07:00",
      "originalDepartureDate": "2025-09-05T16:30:00-07:00",
      "originalArrivalDate": "2025-09-05T18:20:00-07:00",
      "destinationCityName": "San Francisco",
      "destinationLocationTimeZone": "America/Los_Angeles"
    }
  }
}

Create a template

Your boarding pass requires a visual design. If you do not already have Apple template for the pass, create it now. See Designing and managing templates.

Semantic tags are not reflected in previews when designing boarding pass templates in the Airship dashboard.

Create pass links

After creating your flight and template, you can create Adaptive LinksA vendor-agnostic, shortened mobile wallet pass link that supports templates for both Google Wallet and Apple Wallet. When a user taps the link, Airship determines the user’s platform and generates the right pass for that platform. for the boarding passes. You will refer to both the template and flight when creating the links.

You can add semantic tags as key-value pairs within the semantics object at two levels:

• Top level — Within the fields object, provide passenger information like name and seat assignment
• Field level — For individual fields, provide additional context such as a seat row or a passenger’s loyalty level

You must use the /links/adaptive/multiple/project/{projectId} endpoint, not the standard /links/adaptive endpoint. See Create boarding pass Adaptive Links in the Wallet API reference. The request generates a separate Adaptive Link for each passenger in the passengers array. Each Adaptive Link references a flight and includes passenger-specific information.

For a list of supported semantic tags, see the properties for the Passenger semantics object in the Wallet API reference.

For comprehensive boarding pass guidance, see Adaptive Links for Boarding Passes in Flights and boarding passes. For request schema details, see Boarding pass Adaptive Link request in the Wallet API reference.

Example boarding pass Adaptive Link request

The following example contains these semantics:

• Field-level semantic tags: The seatNumber field includes detailed seat information: row and type.
• Top-level passenger semantic tags: Top-level passenger information enables iOS to recognize the traveler and provide personalized features, including loyalty program status.

{
  "payload": {
    "flights": [
      {
        "flightExternalId": "SAB1219-2025-09-05",
        "passengers": [
          {
            "fields": {
              "givenName": { "value": "Casey" },
              "familyName": { "value": "Lee" },
              "seatNumber": {
                "value": "12A",
                "semantics": {
                  "seat": {
                    "seatNumber": "12A",
                    "seatRow": "12",
                    "seatType": "window"
                  }
                }
              },
              "sequenceNumber": {
                "value": "007",
                "semantics": { "frequentFlyerTier": "GOLD" }
              }
            },
            "semantics": {
              "passenger": {
                "givenName": "Casey",
                "familyName": "Lee",
                "loyaltyProgram": "Mileage Plan",
                "loyaltyId": "MP123456"
              }
            }
          }
        ]
      }
    ]
  }
}