Introduction

The Kiosk API provides a complete set of endpoints for airline kiosk self-service functionality. This API enables passengers to search for their bookings, view seat maps, assign seats, check-in, and generate boarding passes through self-service kiosks.

Important: Each airline has their own specific domain. The API endpoints are hosted on airline-specific domains.

Base URL Pattern: https://{your-airline-domain}/api

Important: All API endpoints are prefixed with /api due to the servlet context path configuration.

To get your airline’s specific API domain, contact your technical integration manager.

Airline Identification

The Kiosk API requires airline identification to provide airline-specific functionality. All requests must include the airline identifier in the request headers.

Required header: X-AIRLINE-ID

Input Validation

The API performs automatic validation on input parameters to ensure data quality and security:

  • Passenger Names (lastName): Only letters, spaces, hyphens, and apostrophes are allowed. Maximum length: 50 characters.

  • Booking Numbers (bookingNumber): Only uppercase letters and digits are allowed. Length: 3-20 characters.

  • Seat Numbers (seatNumber): Must follow the format of 1-3 digits followed by a single uppercase letter (e.g., "1A", "12B", "123C").

Invalid input will result in a 400 Bad Request response with a descriptive error message.

Endpoints Summary

Method Endpoint Description

GET

/v1/kiosk/passenger/search

Search passengers by last name and booking number

GET

/v1/kiosk/passenger/fetch

Get passenger details by passenger ID

GET

/v1/kiosk/passenger/seatmap

Get seatmap for passenger (adult/child or infant)

POST

/v1/kiosk/passenger/seat-assign

Assign seat to passenger

POST

/v1/kiosk/passenger/checkin

Check-in passenger

GET

/v1/kiosk/passenger/boarding-pass

Generate boarding pass for checked-in passenger

API Endpoints

Passenger Search

Search for passengers by booking number and last name.

HTTP Request

GET /v1/kiosk/passenger/search?lastName={lastName}&bookingNumber={bookingNumber}

Request Parameters

Parameter Type Required Description

lastName

String

Yes

Passenger’s last name (letters, spaces, hyphens, apostrophes only, max 50 chars)

bookingNumber

String

Yes

Booking reference number (uppercase letters and digits only, 3-20 chars)

Response

{
  "data": [
    {
      "airline": "AF",
      "flightCode": "AF1234",
      "flightStatus": "ON_TIME",
      "departDate": "2025-08-27",
      "departTime": "12:00",
      "srcAirport": "LAX",
      "dstAirport": "JFK",
      "allowCheckIn": true,
      "paxSegmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "passengerId": "b2c3d4e5-f6g7-8901-bcde-f12345678901",
      "eticket": "1234567890",
      "lastName": "DOE",
      "firstName": "JOHN",
      "gender": "MALE",
      "documentInfo": {
        "type": "PASSPORT",
        "issueCountry": "US",
        "idNumber": "123456789",
        "nationality": "US",
        "birthDate": "1990-01-01",
        "expiryDate": "2025-12-25",
        "surname": "DOE",
        "firstName": "JOHN"
      },
      "bookings": [
        {
          "airline": "AF",
          "bookingNumber": "ABC123"
        }
      ],
      "seat": "12A",
      "paxType": "ADT",
      "status": "ISSUED",
      "cabinClass": "ECONOMY",
      "bookingClass": "Y"
    }
  ]
}

Response Fields

Field Type Description

airline

String

Airline code

flightCode

String

Flight number/code

flightStatus

Enum

Current flight status: "ON_TIME", "CANCELED", "RESCHEDULED"

departDate

LocalDate

Departure date (ISO date format: YYYY-MM-DD)

departTime

LocalTime

Departure time (HH:mm format)

srcAirport

String

Source/origin airport code

dstAirport

String

Destination airport code

allowCheckIn

Boolean

Whether check-in is allowed for this passenger

paxSegmentId

UUID

Unique identifier for passenger segment

passengerId

UUID

Unique identifier for passenger

eticket

String

Electronic ticket number (can be null)

lastName

String

Passenger’s last name

firstName

String

Passenger’s first name

gender

String

Passenger’s gender (MALE, FEMALE, UNKNOWN)

documentInfo

Object

Passenger document information

bookings

Array

Booking reference information

seat

String or null

Assigned seat number (null if no seat assigned)

paxType

Enum

Passenger type. Possible values: ADT (Adult), CHD (Child), INF (Infant)

status

Enum

Current passenger segment status. Possible values: CREATED, DECLINED, EXPIRED, ISSUED, REFUNDING, REFUNDED, CHANGED, CHECKED_IN, BOARDED, FLOWN, CHANGING, TRANSFERRED, TRANSFERRING, CANCELLED, NO_SHOW, BOOKING_OWNER_CHANGING

cabinClass

Enum

Cabin class. Possible values: FIRST_PREMIUM, FIRST, BUSINESS_PREMIUM, BUSINESS, ECONOMY_PREMIUM, ECONOMY

bookingClass

String

Booking class code

documentInfo.type

Enum

Document type. Possible values: IDENTIFICATION_CARD, PASSPORT, FOREIGN_PASSPORT, BIRTH_CERTIFICATE, RESIDENT_CARD

documentInfo.issueCountry

String

Country that issued the document

documentInfo.idNumber

String

Document number

documentInfo.nationality

String

Passenger nationality

documentInfo.birthDate

Date or null

Passenger birth date (null if not provided)

documentInfo.expiryDate

Date or null

Document expiry date (null if not provided)

documentInfo.surname

String

Surname from document

documentInfo.firstName

String

First name from document

bookings[].airline

String

Airline code for this booking

bookings[].bookingNumber

String

Booking reference number

Passenger Details by ID

Retrieve passenger information by passenger ID. This endpoint provides an alternative way to access passenger data when you already have the passenger identifier.

HTTP Request

GET /v1/kiosk/passenger/fetch?passengerId={passengerId}

Request Parameters

Parameter Type Required Description

passengerId

UUID

Yes

Unique identifier for the passenger

Response

{
  "data": {
    "airline": "AF",
    "flightCode": "AF1234",
    "flightStatus": "ON_TIME",
    "departDate": "2025-08-27",
    "departTime": "12:00",
    "srcAirport": "LAX",
    "dstAirport": "JFK",
    "allowCheckIn": true,
    "paxSegmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "passengerId": "b2c3d4e5-f6g7-8901-bcde-f12345678901",
    "eticket": "1234567890",
    "lastName": "DOE",
    "firstName": "JOHN",
    "gender": "MALE",
    "documentInfo": {
      "type": "PASSPORT",
      "issueCountry": "US",
      "idNumber": "123456789",
      "nationality": "US",
      "birthDate": "1990-01-01",
      "expiryDate": "2025-12-25",
      "surname": "DOE",
      "firstName": "JOHN"
    },
    "bookings": [
      {
        "airline": "AF",
        "bookingNumber": "ABC123"
      }
    ],
    "seat": "12A",
    "paxType": "ADT",
    "status": "ISSUED",
    "cabinClass": "ECONOMY",
    "bookingClass": "Y"
  }
}

Response Fields

The response fields are identical to the passenger search endpoint. See Passenger Search Response Fields for detailed field descriptions.

Error Responses

  • 404 Not Found - Passenger not found with the provided ID

  • 400 Bad Request - Invalid passenger ID format

Passenger Seatmap

Retrieve available seats for passenger seat assignment.

HTTP Request

GET /v1/kiosk/passenger/seatmap?paxSegmentId=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Request Parameters

Parameter Type Description

paxSegmentId

UUID (required)

Passenger segment identifier

Response

The response format depends on the passenger type. The response uses a discriminator field type to determine the structure:

Adult/Child Seatmap Response
{
  "data": {
    "type": "ADT",
    "decks": [
      {
        "name": "Main Deck",
        "parts": [
          {
            "classId": "ECONOMY",
            "name": "Economy",
            "config": [
              {
                "tag": "A",
                "attrs": {}
              },
              {
                "tag": "B",
                "attrs": {}
              },
              {
                "tag": "",
                "attrs": {}
              },
              {
                "tag": "C",
                "attrs": {}
              }
            ],
            "rows": [
              {
                "id": 1,
                "slots": [
                  {
                    "id": "1A",
                    "attrs": {
                      "occupied": false,
                      "facilities": [
                        {
                          "facilityType": "EXIT",
                          "facilityPointer": "LEFT",
                          "description": "Emergency exit"
                        }
                      ]
                    }
                  },
                  {
                    "id": "1B",
                    "attrs": {
                      "occupied": true,
                      "facilities": [
                        {
                          "facilityType": "GAP",
                          "facilityPointer": "RIGHT",
                          "description": "Aisle"
                        }
                      ]
                    }
                  },
                  {
                    "id": "",
                    "attrs": {}
                  },
                  {
                    "id": "1C",
                    "attrs": {
                      "occupied": false,
                      "facilities": []
                    }
                  }
                ],
                "attrs": {}
              }
            ]
          }
        ]
      }
    ],
    "seatsFree": 150,
    "seatsOccupied": 30,
    "seatsSelectable": 120
  }
}
Infant Seatmap Response
{
  "data": {
    "type": "INF",
    "decks": [
      {
        "name": "Main Deck",
        "parts": [
          {
            "classId": "ECONOMY",
            "name": "Economy",
            "config": [
              {
                "tag": "A",
                "attrs": {}
              }
            ],
            "rows": [
              {
                "id": 1,
                "slots": [
                  {
                    "id": "1A",
                    "attrs": {
                      "selectable": true,
                      "pairedWithAdult": true,
                      "pairedAdultPaxId": "b2c3d4e5-f6a7-8901-bcde-fa2345678901",
                      "facilities": []
                    }
                  }
                ],
                "attrs": {}
              }
            ]
          }
        ]
      }
    ],
    "seatsSelectable": 5
  }
}

Response Fields

Field Type Description

type

String

Response type: "ADT" (for both adults and children) or "INF"

decks

Array

Aircraft deck configuration

seatsFree

Integer

Number of free seats (adult response only)

seatsOccupied

Integer

Number of occupied seats (adult response only)

seatsSelectable

Integer

Number of selectable seats

decks[].name

String

Deck name (e.g., "Main Deck")

decks[].parts

Array

Cabin parts configuration

parts[].classId

Enum

Cabin class: "FIRST_PREMIUM", "FIRST", "BUSINESS_PREMIUM", "BUSINESS", "ECONOMY_PREMIUM", "ECONOMY"

parts[].name

String

Cabin class name

parts[].config

Array

Column configuration

parts[].rows

Array

Seat row configuration

config[].tag

String

Column identifier (e.g., "A", "B", "C") or empty string ("") for aisles

config[].attrs

Object

Column attributes

rows[].id

Integer

Row number

rows[].slots

Array

Seat slots in this row (includes both seats and aisles)

rows[].attrs

Object

Row attributes

slots[].id

String

Seat identifier (e.g., "1A") or empty string ("") for aisles

slots[].attrs

Object

Seat attributes

attrs.occupied

Boolean

Whether the seat is occupied

attrs.selectable

Boolean

Whether seat can be selected (infant response only)

attrs.pairedWithAdult

Boolean

Whether infant seat is paired with adult (infant response only)

attrs.pairedAdultPaxId

UUID

Adult passenger segment ID (infant response only)

attrs.facilities

Array

List of seat facilities and amenities

facilities[].facilityType

Enum

Facility type: "GAP", "REST_ROOM", "EMPTY_PLACE", "EXIT", "EMERGENCY_EXIT"

facilities[].facilityPointer

Enum

Facility position: "LEFT", "RIGHT", "BEFORE", "AFTER", "LEFT_BEFORE", "LEFT_AFTER", "RIGHT_BEFORE", "RIGHT_AFTER"

facilities[].description

String

Facility description

Seat Assignment

Assign a seat to a passenger.

HTTP Request

POST /v1/kiosk/passenger/seat-assign

Request Body

{
  "paxSegmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "seatNumber": "12A"
}

Request Fields

Field Type Required Description

paxSegmentId

UUID

Yes

Passenger segment identifier

seatNumber

String

Yes

Seat number to assign (format: 1-3 digits + letter, e.g., "12A")

Response

{
  "paxSegmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Fields

Field Type Description

paxSegmentId

UUID

Passenger segment identifier

Passenger Check-in

Check-in a passenger for their flight.

HTTP Request

POST /v1/kiosk/passenger/checkin

Request Body

{
  "paxSegmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Request Fields

Field Type Required Description

paxSegmentId

UUID

Yes

Passenger segment identifier

Response

{
  "paxSegmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response Fields

Field Type Description

paxSegmentId

UUID

Passenger segment identifier

Boarding Pass

Generate a boarding pass for a checked-in passenger.

HTTP Request

GET /v1/kiosk/passenger/boarding-pass?paxSegmentId={paxSegmentId}

Request Parameters

Parameter Type Required Description

paxSegmentId

UUID

Yes

Passenger segment identifier

Response

{
  "data": {
    "paxSegmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "flightId": "f1e2d3c4-b5a6-9807-bcde-ef9876543210",
    "boardingPassData": "M1JOHNSON/JOHN      E123456 LAXJFKAF 1234 123Y018A0025 100",
    "format": "AEA"
  }
}

Response Fields

Field Type Description

paxSegmentId

UUID

Passenger segment identifier

flightId

UUID

Flight identifier

boardingPassData

String

Boarding pass barcode data in AEA format (contains only the barcode string, not print commands)

format

Enum

Boarding pass format. Possible values: AEA, IATA (default: AEA)

Business Rules

Seat Assignment Rules

Adult Passengers

  • Can be assigned to any available seat in their cabin class

  • Seat assignment is optional before check-in

  • Seat assignment becomes mandatory during check-in

Child Passengers

  • Follow the same rules as adult passengers

  • May have restricted seating based on airline policy

Infant Passengers

  • Must be assigned to the same seat as an accompanying adult from the same booking

  • Cannot be assigned to adjacent seats

  • Only one infant per adult seat is allowed

  • If no suitable adult seat is available, infant seatmap returns empty

Seatmap Layout Rules

Aisle Generation

  • Aisles are automatically generated based on seat facility data in the seat_facility table

  • An aisle is placed after a seat that has a GAP facility with RIGHT pointer

  • Aisles appear as empty slots with id: "" and tag: "" in the seatmap response

  • The seatmap layout is dynamically determined per aircraft configuration - aisles are not hardcoded

  • Both config (column configuration) and slots (seat data) are generated using unified logic to ensure consistency

Facility Types

Seats may have various facilities that affect the seatmap layout: * GAP - Indicates an aisle or gap next to the seat * EXIT - Emergency exit row * EMERGENCY_EXIT - Emergency exit door * REST_ROOM - Restroom nearby * EMPTY_PLACE - Empty space or missing seat

Facility Pointers

Facilities can be positioned relative to seats: * LEFT - To the left of the seat * RIGHT - To the right of the seat (used for aisle generation) * BEFORE - In front of the seat * AFTER - Behind the seat * LEFT_BEFORE, LEFT_AFTER, RIGHT_BEFORE, RIGHT_AFTER - Diagonal positions

Check-in Rules

  • Passengers must have a valid booking in ISSUED status

  • Seat assignment is required for check-in

  • Online check-in window must be open for the flight

  • Passengers cannot check-in if the flight is already departed or cancelled

Boarding Pass Rules

  • Only available for passengers in CHECKED_IN status

  • Boarding pass contains all necessary flight and passenger information

  • Generated in AEA format by default

  • Returns only the barcode data, not printer commands

  • Barcode data can be used for boarding verification

Error Handling

The Kiosk API uses standard HTTP response codes and returns detailed error information:

HTTP Status Codes

Code Description

200

Success

400

Bad Request - Invalid request parameters

401

Unauthorized - Invalid or missing airline ID

404

Not Found - Passenger or booking not found

409

Conflict - Business rule violation (e.g., seat already occupied)

500

Internal Server Error

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional error details"
  }
}

Common Error Codes

Error Code Description

PASSENGER_NOT_FOUND

No passenger found with provided booking details

SEAT_NOT_AVAILABLE

Requested seat is not available for assignment

CHECK_IN_NOT_ALLOWED

Check-in is not permitted for this passenger

BOARDING_PASS_NOT_AVAILABLE

Boarding pass cannot be generated (passenger not checked-in)

INVALID_PASSENGER_TYPE

Invalid passenger type for requested operation

SEAT_ASSIGNMENT_REQUIRED

Seat must be assigned before check-in

Integration Notes

Infant Seat Assignment

When handling infant passengers, the API enforces strict business rules:

  1. Infants can only occupy the same seat as an adult from the same booking

  2. The API automatically filters available seats to show only those occupied by adults from the same booking

  3. If an adult seat is already occupied by another infant, it will not be available

  4. The seatmap response for infants includes pairedAdultPaxId to identify the accompanying adult

State Transitions

Passenger segments follow this state flow:

CREATED → [payment] → ISSUED → [seat assignment] → ISSUED → [check-in] → CHECKED_IN → [boarding] → BOARDED → [flight completion] → FLOWN

Additional states include: * CANCELLED - Flight or booking cancelled * NO_SHOW - Passenger didn’t board * REFUNDING/REFUNDED - Booking refunded * CHANGING/CHANGED - Booking changed * TRANSFERRING/TRANSFERRED - Booking transferred

Idempotency

All POST operations are idempotent where applicable: * Seat assignment to the same seat returns success * Check-in of already checked-in passenger returns success * Multiple boarding pass requests return the same boarding pass

Technical Implementation

Data Types

  • All UUIDs are in standard UUID format (e.g., 123e4567-e89b-12d3-a456-426614174000)

  • Dates follow ISO 8601 format (YYYY-MM-DD)

  • DateTimes follow ISO 8601 format with time (YYYY-MM-DDTHH:mm:ss)

  • Enums are case-sensitive strings in UPPER_CASE

  • Boarding pass data is returned as raw string format

Response Structure

Response structures vary by endpoint: * Search, passenger details, seatmap, and boarding pass endpoints wrap responses in KioskResponse<T> with a data field * Check-in and seat assignment endpoints return KioskSuccessResponse directly

Endpoint Architecture

  • Passenger Search: Traditional search by booking number and last name

  • Passenger Details: Direct access by passenger ID for known passengers

  • Seatmap: Dynamic layout generation with automatic aisle placement based on aircraft configuration

  • Seat Assignment: Validates seat availability and assigns seats

  • Check-in: Processes passenger check-in with required validations

  • Boarding Pass: Generates AEA format boarding passes for checked-in passengers

Polymorphic Responses

The seatmap endpoint returns different response structures based on passenger type using a discriminator field type: * type: "ADT" returns AdultSeatmapResponse with full deck configuration (used for both ADT and CHD passenger types) * type: "INF" returns InfantSeatmapResponse with available adult seats for infant assignment

Error Handling

The API returns structured error responses with localized messages and specific error codes for common business rule violations.