Apple Wallet Semantic Tags

Semantic tags are machine-readable metadata that Apple Wallet uses to offer passes and suggest related actions to users. This documentation covers all semantic tags supported by Passcreator.

Overview

Semantic tags enable Apple Wallet to:

Display relevant information at the right time
Suggest actions based on pass content
Integrate with Apple services (Maps, Calendar, Siri)
Provide enhanced user experiences

Semantic tags are optional but highly recommended for passes where contextual information can improve the user experience. Not all tags apply to all pass types.

General Semantic Tags

These semantic tags can be used across multiple pass types.

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
totalPrice
Type
object
(optional)
Description
The total price for the pass. Use this key for any pass type.
Name
totalPrice.currencyCode
Type
string
(mandatory)
Description
ISO 4217 currency code (e.g., USD, EUR). Required if totalPrice is present.
Name
totalPrice.amount
Type
string
(mandatory)
Description
Price amount as string. Required if totalPrice is present.
Name
duration
Type
number
(optional)
Description
The duration of the event or transit journey, in seconds. Use this key for any type of boarding pass and any type of event ticket.
Name
silenceRequested
Type
boolean
(optional)
Description
Default: false
A Boolean value that determines whether the person's device remains silent during an event or transit journey. The system may override the key and determine the length of the period of silence. Use this key for any type of boarding pass or event ticket.
Name
wifiAccess
Type
array<object>
(optional)
Description
An array of objects that represent the Wi-Fi networks associated with the event or venue. Use this key for any type of pass.
Name
wifiAccess[].ssid
Type
string
(mandatory)
Description
The name for the Wi-Fi network. Required for each Wi-Fi access object.
Name
wifiAccess[].password
Type
string
(mandatory)
Description
The password for the Wi-Fi network. Required for each Wi-Fi access object.
Name
wifiAccess[].captiveToken
Type
string
(optional)
Description
Token credential required to log in to Captive Portal.
Name
wifiAccess[].captiveTokenAuthURL
Type
string
(optional)
Description
The URL of the authentication server that verifies the client using a token credential.

Request Body Example

General tags example

{
  "semantics": {
    "totalPrice": {
      "currencyCode": "USD",
      "amount": "129.99"
    },
    "duration": 7200,
    "silenceRequested": true,
    "wifiAccess": [
      {
        "ssid": "VenueWiFi",
        "password": "welcome2024"
      }
    ]
  }
}

Boarding Pass Semantic Tags

Semantic tags specifically for boarding passes (flights, trains, buses, boats).

Important for pass-specific data:

Best practice: Set pass-specific semantic tags (like seat assignments, gates, confirmation numbers, passenger names) at the individual pass level rather than in the template
Template-level semantic tags are best used for data that remains constant across all passes (e.g., airline code, flight number for a specific flight)

Flight Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
airlineCode
Type
string
(optional)
Description
The IATA airline code, such as ZZ for Example Airways with flightCode ZZ456. Must be a valid IATA airline code. Use this key only for airline boarding passes.
Name
flightCode
Type
string
(optional)
Description
The IATA flight code, such as ZZ456. Use this key only for airline boarding passes.
Name
flightNumber
Type
number
(optional)
Description
The numeric portion of the IATA flight code, such as 456 for flightCode ZZ456. Use this key only for airline boarding passes.

Request Body Example

Flight information example

{
  "semantics": {
    "airlineCode": "ZZ",
    "flightCode": "ZZ456",
    "flightNumber": 456
  }
}

Departure Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
departureAirportCode
Type
string
(optional)
Description
The IATA airport code for the departure airport, such as MPM or LHR. Use this key only for airline boarding passes.
Name
departureAirportName
Type
string
(optional)
Description
The full name of the departure airport, such as Maputo International Airport. Use this key only for airline boarding passes.
Name
departureCityName
Type
string
(optional)
Description
The name of the departure city to display on the boarding pass, such as London or Shanghai.
Name
departureGate
Type
string
(optional)
Description
The gate number or letters of the departure gate, such as 1A. Don't include the word gate.
Best practice: Set this at the individual pass level.
Name
departureTerminal
Type
string
(optional)
Description
The name or letter of the departure terminal, such as A. Don't include the word terminal. Use this key only for airline boarding passes.
Name
departureStationName
Type
string
(optional)
Description
The name of the departure station, such as 1st Street Station. Use this key only for a train or other rail boarding pass.
Name
departurePlatform
Type
string
(optional)
Description
The name of the departure platform, such as A. Don't include the word platform. Use this key only for a train or other rail boarding pass.
Best practice: Set this at the individual pass level.
Name
departureLocation
Type
object
(optional)
Description
An object that represents the geographic coordinates of the transit departure location, suitable for display on a map. If possible, use precise locations, which are more useful to travelers; for example, the specific location of an airport gate. Use this key for any type of boarding pass.
Name
departureLocation.latitude
Type
number
(mandatory)
Description
The latitude, in degrees. Required if departureLocation is present.
Name
departureLocation.longitude
Type
number
(mandatory)
Description
The longitude, in degrees. Required if departureLocation is present.
Name
departureLocationDescription
Type
string
(optional)
Description
A brief description of the departure location. For example, for a flight departing from an airport that has a code of LHR, an appropriate description might be London, Heathrow. Use this key for any type of boarding pass.
Name
departureLocationTimeZone
Type
string
(optional)
Description
The time zone of the departure location, such as America/Chicago. See the IANA Time Zone Database for the full list of supported time zones.
Name
departureLocationSecurityPrograms
Type
array<string>
(optional)
Description
A list of security programs that exist at the departure location. This only shows in the UI if a program is in passengerEligibleSecurityPrograms and at least one of departureLocationSecurityPrograms or destinationLocationSecurityPrograms.
Possible values:
- PKTransitSecurityProgramTSAPreCheck
- PKTransitSecurityProgramTSAPreCheckTouchlessID
- PKTransitSecurityProgramOSS
- PKTransitSecurityProgramITI
- PKTransitSecurityProgramITD
- PKTransitSecurityProgramGlobalEntry
- PKTransitSecurityProgramCLEAR

Request Body Example

Departure information example

{
  "semantics": {
    "departureAirportCode": "FRA",
    "departureAirportName": "Frankfurt Airport",
    "departureGate": "A23",
    "departureTerminal": "1",
    "departureLocation": {
      "latitude": 50.0379,
      "longitude": 8.5622
    },
    "departureLocationDescription": "Frankfurt, Germany",
    "departureLocationTimeZone": "Europe/Berlin",
    "departureLocationSecurityPrograms": [
      "PKTransitSecurityProgramTSAPreCheck"
    ]
  }
}

Destination Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
destinationAirportCode
Type
string
(optional)
Description
The IATA airport code for the destination airport, such as MPM or LHR. Use this key only for airline boarding passes.
Name
destinationAirportName
Type
string
(optional)
Description
The full name of the destination airport, such as London Heathrow. Use this key only for airline boarding passes.
Name
destinationCityName
Type
string
(optional)
Description
The name of the destination city to display on the boarding pass, such as London or Shanghai.
Name
destinationGate
Type
string
(optional)
Description
The gate number or letter of the destination gate, such as 1A. Don't include the word gate. Use this key only for airline boarding passes.
Best practice: Set this at the individual pass level.
Name
destinationTerminal
Type
string
(optional)
Description
The terminal name or letter of the destination terminal, such as A. Don't include the word terminal. Use this key only for airline boarding passes.
Name
destinationStationName
Type
string
(optional)
Description
The name of the destination station, such as 1st Street Station. Use this key only for a train or other rail boarding pass.
Name
destinationPlatform
Type
string
(optional)
Description
The name of the destination platform, such as A. Don't include the word platform. Use this key only for a train or other rail boarding pass.
Best practice: Set this at the individual pass level.
Name
destinationLocation
Type
object
(optional)
Description
An object that represents the geographic coordinates of the transit destination location, suitable for display on a map. Use this key for any type of boarding pass.
Name
destinationLocation.latitude
Type
number
(mandatory)
Description
The latitude, in degrees. Required if destinationLocation is present.
Name
destinationLocation.longitude
Type
number
(mandatory)
Description
The longitude, in degrees. Required if destinationLocation is present.
Name
destinationLocationDescription
Type
string
(optional)
Description
A brief description of the destination location. For example, for a flight arriving at an airport that has a code of MPM, Maputo might be an appropriate description. Use this key for any type of boarding pass.
Name
destinationLocationTimeZone
Type
string
(optional)
Description
The time zone of the destination location, such as America/Los_Angeles. See the IANA Time Zone Database for the full list of supported time zones.
Name
destinationLocationSecurityPrograms
Type
array<string>
(optional)
Description
A list of security programs that exist at the destination location. This only shows in the UI if a program is in passengerEligibleSecurityPrograms and at least one of departureLocationSecurityPrograms or destinationLocationSecurityPrograms.
Possible values:
- PKTransitSecurityProgramTSAPreCheck
- PKTransitSecurityProgramTSAPreCheckTouchlessID
- PKTransitSecurityProgramOSS
- PKTransitSecurityProgramITI
- PKTransitSecurityProgramITD
- PKTransitSecurityProgramGlobalEntry
- PKTransitSecurityProgramCLEAR

Request Body Example

Destination information example

{
  "semantics": {
    "destinationAirportCode": "JFK",
    "destinationAirportName": "John F. Kennedy International Airport",
    "destinationTerminal": "1",
    "destinationLocation": {
      "latitude": 40.6413,
      "longitude": -73.7781
    },
    "destinationLocationDescription": "New York, USA",
    "destinationLocationTimeZone": "America/New_York"
  }
}

Boarding and Timing

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
boardingGroup
Type
string
(optional)
Description
A group number for boarding. Use this key for any type of boarding pass.
Best practice: Set this at the individual pass level.
Name
boardingSequenceNumber
Type
string
(optional)
Description
A sequence number for boarding. Use this key for any type of boarding pass.
Best practice: Set this at the individual pass level.
Name
boardingZone
Type
string
(optional)
Description
A zone number for boarding. Don't include the word zone.
Best practice: Set this at the individual pass level.
Name
currentBoardingDate
Type
string
(optional)
Description
The updated date and time of boarding, if different from the originally scheduled date and time. Use ISO 8601 format. Use this key for any type of boarding pass.
Best practice: Set this at the individual pass level.
Name
originalBoardingDate
Type
string
(optional)
Description
The originally scheduled date and time of boarding. Use ISO 8601 format. Use this key for any type of boarding pass.
Name
currentDepartureDate
Type
string
(optional)
Description
The updated departure date and time, if different from the originally scheduled date and time. Use ISO 8601 format. Use this key for any type of boarding pass.
Best practice: Set this at the individual pass level.
Name
originalDepartureDate
Type
string
(optional)
Description
The originally scheduled date and time of departure. Use ISO 8601 format. Use this key for any type of boarding pass.
Name
currentArrivalDate
Type
string
(optional)
Description
The updated date and time of arrival, if different from the originally scheduled date and time. Use ISO 8601 format. Use this key for any type of boarding pass.
Best practice: Set this at the individual pass level.
Name
originalArrivalDate
Type
string
(optional)
Description
The originally scheduled date and time of arrival. Use ISO 8601 format. Use this key for any type of boarding pass.

Request Body Example

Boarding and timing example

{
  "semantics": {
    "boardingGroup": "2",
    "boardingZone": "A",
    "originalDepartureDate": "2025-10-15T14:30:00+01:00",
    "currentDepartureDate": "2025-10-15T16:00:00+01:00",
    "originalArrivalDate": "2025-10-15T17:45:00-04:00",
    "currentArrivalDate": "2025-10-15T19:15:00-04:00"
  }
}

Passenger Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
passengerName
Type
object
(optional)
Description
An object that represents the name of the passenger. Use this key for any type of boarding pass.
Best practice: Set this at the individual pass level.
Name
passengerName.familyName
Type
string
(optional)
Description
The person's family name or last name.
Best practice: Set this at the individual pass level.
Name
passengerName.givenName
Type
string
(optional)
Description
The person's given name; also called the forename or first name in some countries.
Best practice: Set this at the individual pass level.
Name
passengerName.middleName
Type
string
(optional)
Description
The person's middle name.
Best practice: Set this at the individual pass level.
Name
passengerName.namePrefix
Type
string
(optional)
Description
The prefix for the person's name, such as Dr.
Best practice: Set this at the individual pass level.
Name
passengerName.nameSuffix
Type
string
(optional)
Description
The suffix for the person's name, such as Junior.
Best practice: Set this at the individual pass level.
Name
passengerName.nickname
Type
string
(optional)
Description
The person's nickname.
Best practice: Set this at the individual pass level.
Name
passengerName.phoneticRepresentation
Type
string
(optional)
Description
The phonetic representation of the person's name.
Best practice: Set this at the individual pass level.
Name
confirmationNumber
Type
string
(optional)
Description
A booking or reservation confirmation number. Use this key for any type of boarding pass.
Best practice: Set this at the individual pass level.
Name
membershipProgramName
Type
string
(optional)
Description
The name of a frequent flyer or loyalty program. Use this key for any type of boarding pass.
Name
membershipProgramNumber
Type
string
(optional)
Description
The ticketed passenger's frequent flyer or loyalty number. Use this key for any type of boarding pass.
Name
membershipProgramStatus
Type
string
(optional)
Description
The ticketed passenger's frequent flyer or loyalty program status. Use this key for any type of boarding pass.
Name
priorityStatus
Type
string
(optional)
Description
The priority status the ticketed passenger holds, such as Gold or Silver. Use this key for any type of boarding pass.
Name
ticketFareClass
Type
string
(optional)
Description
A localizable string that denotes the ticket class, such as Saver, Economy, First. This value displays as a badge on the boarding pass.

Request Body Example

Passenger information example

{
  "semantics": {
    "passengerName": {
      "givenName": "John",
      "familyName": "Smith"
    },
    "confirmationNumber": "ABC123",
    "membershipProgramName": "Miles & More",
    "membershipProgramNumber": "1234567890",
    "membershipProgramStatus": "Gold",
    "priorityStatus": "Priority",
    "ticketFareClass": "Business"
  }
}

Passenger Capabilities and Security

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
passengerCapabilities
Type
array<string>
(optional)
Description
A list of capabilities the passenger has. Only use this key for airline boarding passes.
Possible values:
- PKPassengerCapabilityPreboarding
- PKPassengerCapabilityPriorityBoarding
- PKPassengerCapabilityCarryon
- PKPassengerCapabilityPersonalItem
Name
passengerEligibleSecurityPrograms
Type
array<string>
(optional)
Description
A list of security programs the passenger is eligible for. This only shows in the UI if a program is in passengerEligibleSecurityPrograms and at least one of departureLocationSecurityPrograms or destinationLocationSecurityPrograms.
Possible values:
- PKTransitSecurityProgramTSAPreCheck
- PKTransitSecurityProgramTSAPreCheckTouchlessID
- PKTransitSecurityProgramOSS
- PKTransitSecurityProgramITI
- PKTransitSecurityProgramITD
- PKTransitSecurityProgramGlobalEntry
- PKTransitSecurityProgramCLEAR
Name
securityScreening
Type
string
(optional)
Description
The type of security screening for the ticketed passenger, such as Priority. Use this key for any type of boarding pass.
Name
internationalDocumentsAreVerified
Type
boolean
(optional)
Description
Default: false
An optional boolean that indicates whether the passenger's international documents are verified. If set to true, Wallet displays the badge on the boarding pass with the value from internationalDocumentsVerifiedDeclarationName.
Name
internationalDocumentsVerifiedDeclarationName
Type
string
(optional)
Description
The name of the declaration given once the passenger's international documents are verified. Examples include DOCS OK or Travel Ready. If internationalDocumentsAreVerified is true, Wallet displays a badge on the boarding pass with this value.

Request Body Example

Passenger capabilities example

{
  "semantics": {
    "passengerCapabilities": [
      "PKPassengerCapabilityPriorityBoarding",
      "PKPassengerCapabilityCarryon"
    ],
    "passengerEligibleSecurityPrograms": [
      "PKTransitSecurityProgramTSAPreCheck"
    ],
    "securityScreening": "Priority",
    "internationalDocumentsAreVerified": true,
    "internationalDocumentsVerifiedDeclarationName": "DOCS OK"
  }
}

Passenger SSRs (Special Service Requests)

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
passengerAirlineSSRs
Type
array<string>
(optional)
Description
An array of airline-specific SSRs that apply to the ticketed passenger.
Name
passengerInformationSSRs
Type
array<string>
(optional)
Description
An array of IATA information SSRs that apply to the ticketed passenger. A comprehensive list of service SSRs can be found in the IATA Airlines Developer Guide under "A List of Information SSRs".
Name
passengerServiceSSRs
Type
array<string>
(optional)
Description
An array of IATA SSRs that apply to the ticketed passenger. A comprehensive list of service SSRs can be found in the IATA Airlines Developer Guide under "A List of Service SSRs".

Request Body Example

Passenger SSRs example

{
  "semantics": {
    "passengerAirlineSSRs": [
      "VGML"
    ],
    "passengerInformationSSRs": [
      "DOCS"
    ],
    "passengerServiceSSRs": [
      "WCHR",
      "VGML"
    ]
  }
}

Vehicle Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
vehicleName
Type
string
(optional)
Description
The name of the vehicle to board, such as the name of a boat. Use this key for any type of boarding pass.
Name
vehicleNumber
Type
string
(optional)
Description
The identifier of the vehicle to board, such as the aircraft registration number or train number. Use this key for any type of boarding pass.
Name
vehicleType
Type
string
(optional)
Description
A brief description of the type of vehicle to board, such as the model and manufacturer of a plane or the class of a boat. Use this key for any type of boarding pass.
Name
carNumber
Type
string
(optional)
Description
The number of the passenger car. A train car is also called a carriage, wagon, coach, or bogie in some countries. Use this key only for a train or other rail boarding pass.

Request Body Example

Vehicle information example

{
  "semantics": {
    "vehicleType": "Boeing 747-400",
    "vehicleNumber": "D-ABVM",
    "carNumber": "7"
  }
}

Transit Status

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
transitProvider
Type
string
(optional)
Description
The name of the transit company. Use this key for any type of boarding pass.
Name
transitStatus
Type
string
(optional)
Description
A brief description of the current boarding status for the vessel, such as On Time or Delayed. For delayed status, provide currentBoardingDate, currentDepartureDate, and currentArrivalDate where available. Use this key for any type of boarding pass.
Best practice: Set this at the individual pass level.
Name
transitStatusReason
Type
string
(optional)
Description
A brief description that explains the reason for the current transitStatus, such as Thunderstorms. Use this key for any type of boarding pass.
Best practice: Set this at the individual pass level.

Request Body Example

Transit status example

{
  "semantics": {
    "transitProvider": "Example Airways",
    "transitStatus": "Delayed",
    "transitStatusReason": "Weather conditions"
  }
}

Lounge Access

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
loungePlaceIDs
Type
array<string>
(optional)
Description
The MapKit Place IDs that reference the transit provider lounge locations. For more information, see Apple's documentation on "Identifying unique locations with Place IDs".

Request Body Example

Lounge access example

{
  "semantics": {
    "loungePlaceIDs": [
      "I7C123456789ABCDEF"
    ]
  }
}

Seating

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
seats
Type
array<object>
(optional)
Description
An array of objects that represent the details for each seat at an event or on a transit journey. Use this key for any type of boarding pass or event ticket.
Best practice: Set this at the individual pass level.
Name
seats[].seatSection
Type
string
(optional)
Description
The section that contains the seat.
Best practice: Set this at the individual pass level.
Name
seats[].seatRow
Type
string
(optional)
Description
The row that contains the seat.
Best practice: Set this at the individual pass level.
Name
seats[].seatNumber
Type
string
(optional)
Description
The number of the seat.
Best practice: Set this at the individual pass level.
Name
seats[].seatIdentifier
Type
string
(optional)
Description
The identifier code for the seat.
Best practice: Set this at the individual pass level.
Name
seats[].seatType
Type
string
(optional)
Description
The type of seat, such as Reserved seating.
Best practice: Set this at the individual pass level.
Name
seats[].seatDescription
Type
string
(optional)
Description
A description of the seat, such as A flat bed seat.
Best practice: Set this at the individual pass level.
Name
seats[].seatAisle
Type
string
(optional)
Description
The aisle that contains the seat.
Best practice: Set this at the individual pass level.
Name
seats[].seatLevel
Type
string
(optional)
Description
The level that contains the seat.
Best practice: Set this at the individual pass level.
Name
seats[].seatSectionColor
Type
string
(optional)
Description
A color associated with identifying the seat, specified as a CSS-style RGB triple, such as rgb(23, 187, 82).

Request Body Example

Seating example

{
  "semantics": {
    "seats": [
      {
        "seatSection": "Economy",
        "seatRow": "23",
        "seatNumber": "A",
        "seatType": "Window"
      },
      {
        "seatSection": "Economy",
        "seatRow": "23",
        "seatNumber": "B",
        "seatType": "Middle"
      }
    ]
  }
}

Complete Boarding Pass Example

A comprehensive example showing multiple boarding pass semantic tags together.

Request Body Example

Complete airline boarding pass

{
  "semantics": {
    "airlineCode": "ZZ",
    "flightCode": "ZZ456",
    "flightNumber": 456,
    "departureAirportCode": "FRA",
    "departureAirportName": "Frankfurt Airport",
    "departureGate": "A23",
    "departureTerminal": "1",
    "destinationAirportCode": "JFK",
    "destinationAirportName": "John F. Kennedy International Airport",
    "destinationTerminal": "1",
    "boardingGroup": "2",
    "boardingZone": "A",
    "currentDepartureDate": "2025-10-15T14:30:00+01:00",
    "currentArrivalDate": "2025-10-15T17:45:00-04:00",
    "passengerName": {
      "givenName": "John",
      "familyName": "Smith"
    },
    "confirmationNumber": "ABC123",
    "membershipProgramName": "Miles & More",
    "membershipProgramNumber": "1234567890",
    "seats": [
      {
        "seatSection": "Economy",
        "seatRow": "23",
        "seatNumber": "A",
        "seatType": "Window"
      }
    ],
    "transitStatus": "On Time"
  }
}

Event Ticket Semantic Tags

Semantic tags specifically for event tickets (concerts, sports, movies, conferences).

Event Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
eventName
Type
string
(optional)
Description
The full name of the event, such as the title of a movie. Use this key for any type of event ticket.
Name
eventType
Type
enum
(optional)
Description
The type of event. Use this key for any type of event ticket.
Possible values:
- PKEventTypeGeneric
- PKEventTypeLivePerformance
- PKEventTypeMovie
- PKEventTypeSports
- PKEventTypeConference
- PKEventTypeConvention
- PKEventTypeWorkshop
- PKEventTypeSocialGathering
Name
eventStartDate
Type
string
(optional)
Description
The date and time the event starts. Use ISO 8601 format. Use this key for any type of event ticket.
Name
eventEndDate
Type
string
(optional)
Description
The date and time the event ends. Use ISO 8601 format. Use this key for any type of event ticket.
Name
eventStartDateInfo
Type
object
(optional)
Description
An object that provides information for the date and time the event starts. Use this key for any type of event ticket.
Name
eventStartDateInfo.date
Type
string
(optional)
Description
The date.
Name
eventStartDateInfo.timeZone
Type
string
(optional)
Description
The time zone to display in the date. Time zone identifiers come from the IANA time zone database.
Name
eventStartDateInfo.ignoreTimeComponents
Type
boolean
(optional)
Description
A Boolean value that indicates whether the system ignores the time components of the date.
Name
eventStartDateInfo.unannounced
Type
boolean
(optional)
Description
A Boolean value that indicates whether the date of the event is announced.
Name
eventStartDateInfo.undetermined
Type
boolean
(optional)
Description
A Boolean value that indicates whether the date of the event is determined.

Request Body Example

Event information example

{
  "semantics": {
    "eventName": "Summer Music Festival 2025",
    "eventType": "PKEventTypeLivePerformance",
    "eventStartDate": "2025-07-20T19:00:00-04:00",
    "eventEndDate": "2025-07-20T23:00:00-04:00",
    "eventStartDateInfo": {
      "date": "2025-07-20T19:00:00-04:00",
      "timeZone": "America/New_York"
    }
  }
}

Venue Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
venueName
Type
string
(optional)
Description
The full name of the venue. Use this key for any type of event ticket.
Name
venueLocation
Type
object
(optional)
Description
An object that represents the geographic coordinates of the venue. Use this key for any type of event ticket.
Name
venueLocation.latitude
Type
number
(mandatory)
Description
The latitude, in degrees. Required if venueLocation is present.
Name
venueLocation.longitude
Type
number
(mandatory)
Description
The longitude, in degrees. Required if venueLocation is present.
Name
venueRoom
Type
string
(optional)
Description
The full name of the room where the ticketed event is to take place. Use this key for any type of event ticket.
Name
venueRegionName
Type
string
(optional)
Description
The name of the city or hosting region of the venue. Use this key for any type of event ticket.
Name
venuePhoneNumber
Type
string
(optional)
Description
The phone number for inquiries about the venue's ticketed event. Use this key for any type of event ticket.

Request Body Example

Venue information example

{
  "semantics": {
    "venueName": "Central Park",
    "venueLocation": {
      "latitude": 40.785091,
      "longitude": -73.968285
    },
    "venueRegionName": "New York",
    "venuePhoneNumber": "+1-212-555-0123"
  }
}

Venue Entry and Timing

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
venueEntrance
Type
string
(optional)
Description
The full name of the entrance, such as Gate A, to use to gain access to the ticketed event. Use this key for any type of event ticket.
Best practice: Set this at the individual pass level.
Name
venueEntranceGate
Type
string
(optional)
Description
The venue entrance gate. Use this key for any type of event ticket.
Best practice: Set this at the individual pass level.
Name
venueEntranceDoor
Type
string
(optional)
Description
The venue entrance door. Use this key for any type of event ticket.
Best practice: Set this at the individual pass level.
Name
venueEntrancePortal
Type
string
(optional)
Description
The venue entrance portal. Use this key for any type of event ticket.
Best practice: Set this at the individual pass level.
Name
entranceDescription
Type
string
(optional)
Description
The long description of the entrance information. Use this key for any type of event ticket.
Name
venueOpenDate
Type
string
(optional)
Description
The date when the venue opens. Use ISO 8601 format. Use this if none of the more specific venue open tags apply. Use this key for any type of event ticket.
Name
venueDoorsOpenDate
Type
string
(optional)
Description
The date the doors to the venue open. Use ISO 8601 format. Use this key for any type of event ticket.
Name
venueGatesOpenDate
Type
string
(optional)
Description
The date the gates to the venue open. Use ISO 8601 format. Use this key for any type of event ticket.
Name
venueBoxOfficeOpenDate
Type
string
(optional)
Description
The date when the box office opens. Use ISO 8601 format. Use this key for any type of event ticket.
Name
venueParkingLotsOpenDate
Type
string
(optional)
Description
The date the parking lots open. Use ISO 8601 format. Use this key for any type of event ticket.
Name
venueFanZoneOpenDate
Type
string
(optional)
Description
The date the fan zone opens. Use ISO 8601 format. Use this key for any type of event ticket.
Name
venueCloseDate
Type
string
(optional)
Description
The date when the venue closes. Use ISO 8601 format. Use this key for any type of event ticket.

Request Body Example

Venue entry and timing example

{
  "semantics": {
    "venueEntrance": "West Entrance",
    "venueEntranceGate": "Gate 5",
    "venueDoorsOpenDate": "2025-07-20T18:00:00-04:00",
    "venueGatesOpenDate": "2025-07-20T17:30:00-04:00",
    "venueParkingLotsOpenDate": "2025-07-20T16:00:00-04:00"
  }
}

Ticket Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
attendeeName
Type
string
(optional)
Description
The name of the person the ticket grants admission to. Use this key for any type of event ticket.
Best practice: Set this at the individual pass level.
Name
admissionLevel
Type
string
(optional)
Description
The level of admission the ticket provides, such as general admission, VIP, and so forth. Use this key for any type of event ticket.
Best practice: Set this at the individual pass level.
Name
admissionLevelAbbreviation
Type
string
(optional)
Description
An abbreviation of the level of admission the ticket provides, such as GA or VIP. Use this key for any type of event ticket.
Best practice: Set this at the individual pass level.
Name
additionalTicketAttributes
Type
string
(optional)
Description
Additional ticket attributes that other tags or keys in the pass don't include. Use this key for any type of event ticket.
Name
tailgatingAllowed
Type
boolean
(optional)
Description
Default: false
A Boolean value that indicates whether tailgating is allowed at the event. Use this key for any type of event ticket.

Request Body Example

Ticket information example

{
  "semantics": {
    "attendeeName": "Jane Doe",
    "admissionLevel": "VIP",
    "admissionLevelAbbreviation": "VIP",
    "tailgatingAllowed": true
  }
}

Performance Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
performerNames
Type
array<string>
(optional)
Description
An array of the full names of the performers and opening acts at the event, in decreasing order of significance. Use this key for any type of event ticket.
Name
genre
Type
string
(optional)
Description
The genre of the performance, such as classical. Use this key for any type of event ticket.
Name
artistIDs
Type
array<string>
(optional)
Description
An array of the Apple Music persistent ID for each artist performing at the event, in decreasing order of significance. Use this key for any type of event ticket.
Name
albumIDs
Type
array<string>
(optional)
Description
An array of the Apple Music persistent ID for each album corresponding to the event, in decreasing order of significance. Use this key for any type of event ticket.
Name
playlistIDs
Type
array<string>
(optional)
Description
An array of the Apple Music persistent ID for each playlist corresponding to the event, in decreasing order of significance. Use this key for any type of event ticket.

Request Body Example

Performance information example

{
  "semantics": {
    "performerNames": [
      "The Midnight Echo",
      "Sunset Collective"
    ],
    "genre": "Rock",
    "artistIDs": [
      "123456789"
    ]
  }
}

Sports Event Information

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
sportName
Type
string
(optional)
Description
The commonly used name of the sport. Use this key only for a sports event ticket.
Name
leagueName
Type
string
(optional)
Description
The unabbreviated league name for a sports event. Use this key only for a sports event ticket.
Name
leagueAbbreviation
Type
string
(optional)
Description
The abbreviated league name for a sports event. Use this key only for a sports event ticket.
Name
homeTeamName
Type
string
(optional)
Description
The name of the home team. Use this key only for a sports event ticket.
Name
homeTeamAbbreviation
Type
string
(optional)
Description
The unique abbreviation of the home team's name. Use this key only for a sports event ticket.
Name
homeTeamLocation
Type
string
(optional)
Description
The home location of the home team. Use this key only for a sports event ticket.
Name
awayTeamName
Type
string
(optional)
Description
The name of the away team. Use this key only for a sports event ticket.
Name
awayTeamAbbreviation
Type
string
(optional)
Description
The unique abbreviation of the away team's name. Use this key only for a sports event ticket.
Name
awayTeamLocation
Type
string
(optional)
Description
The home location of the away team. Use this key only for a sports event ticket.

Request Body Example

Sports event example

{
  "semantics": {
    "sportName": "Football",
    "leagueName": "Continental Football League",
    "leagueAbbreviation": "CFL",
    "homeTeamName": "Metro City Thunder",
    "homeTeamAbbreviation": "MCT",
    "homeTeamLocation": "Metro City",
    "awayTeamName": "Harbor Bay Strikers",
    "awayTeamAbbreviation": "HBS",
    "awayTeamLocation": "Harbor Bay"
  }
}

Complete Event Ticket Examples

Complete examples showing multiple event ticket semantic tags together for different event types.

Request Body Examples

{
  "semantics": {
    "totalPrice": {
      "currencyCode": "USD",
      "amount": "250.00"
    },
    "duration": 14400,
    "eventName": "Riverside Music Festival 2025",
    "eventType": "PKEventTypeLivePerformance",
    "eventStartDate": "2025-07-20T19:00:00-04:00",
    "eventEndDate": "2025-07-20T23:00:00-04:00",
    "venueName": "Greenfield Amphitheater",
    "venueLocation": {
      "latitude": 40.785091,
      "longitude": -73.968285
    },
    "venueDoorsOpenDate": "2025-07-20T18:00:00-04:00",
    "venueEntranceGate": "Gate 5",
    "attendeeName": "Jane Doe",
    "admissionLevel": "VIP",
    "performerNames": [
      "The Midnight Echo",
      "Sunset Collective"
    ],
    "genre": "Rock",
    "seats": [
      {
        "seatSection": "VIP",
        "seatRow": "5",
        "seatNumber": "12"
      }
    ]
  }
}

Store Card Semantic Tags

Semantic tags for store cards and loyalty programs.

Optional Parameters

All semantic tags are included in the request/response body within the semantics object.

Name
balance
Type
object
(optional)
Description
The current balance redeemable with the pass. Use this key only for a store card pass.
Name
balance.currencyCode
Type
string
(mandatory)
Description
ISO 4217 currency code. Required if balance is present.
Name
balance.amount
Type
string
(mandatory)
Description
Balance amount as string. Required if balance is present.

Request Body Example

Store card example

{
  "semantics": {
    "balance": {
      "currencyCode": "USD",
      "amount": "45.50"
    },
    "membershipProgramName": "Rewards Club",
    "membershipProgramNumber": "9876543210"
  }
}

Pass Template Management - Creating and managing pass templates
Pass Management - Creating and managing individual passes

References

For complete Apple Wallet semantic tags documentation, refer to: