Technical Integration

Authentication Setup

OAuth 2.0 Configuration

The Boardingpass API requires OAuth 2.0 Bearer token authentication. Contact the API product approvers to obtain credentials:

• emre.oegretmen@tui.com
• javier.temprano.fernandez@tui.be
• gema.jimenezruiz@tui.nl

Step-by-Step

1. Request API access — Apply for access via the developer portal
2. Receive credentials — You will receive a client_id and client_secret
3. Obtain token — Exchange credentials for an access token using client credentials flow
4. Include token — Add the token in the Authorization: Bearer <token> header on every request

Source Market Configuration

Every request MUST include the X-SourceMarket header. This determines which airline-specific configuration is applied (check-in rules, branding, email templates, etc.).

Integration Guide

1. Verify Connectivity

Start by calling the ping endpoint to verify your credentials and connectivity:

curl -X POST "https://test.api.tui/flight-newskies-boardingpass/system/ping" \
  -H "Authorization: Bearer <token>" \
  -H "X-SourceMarket: uk"

Expected: HTTP 200.

2. Check Availability

Before attempting to generate boarding passes, verify that check-in is available:

curl -X GET "https://test.api.tui/flight-newskies-boardingpass/settings/availability/LGW/PMI/BY/20260815" \
  -H "Authorization: Bearer <token>" \
  -H "X-SourceMarket: uk"

3. Check Configuration

Retrieve check-in rules for the carrier to understand time windows:

curl -X GET "https://test.api.tui/flight-newskies-boardingpass/settings/checkinconfig/BY" \
  -H "Authorization: Bearer <token>" \
  -H "X-SourceMarket: uk"

The checkInOpens and checkInCloses fields tell you the valid window (hours before departure).

4. Get Boarding Passes

Once check-in is confirmed available, retrieve boarding passes:

curl -X POST "https://test.api.tui/flight-newskies-boardingpass/bookings/ABC123/boardingpasses?lastname=Smith&outboundDate=20260815" \
  -H "Authorization: Bearer <token>" \
  -H "X-SourceMarket: uk"

5. Deliver Boarding Pass

Choose a delivery method:

• PDF — POST /bookings/{id}/pdf returns binary PDF
• Apple Wallet — POST /bookings/{id}/pkpass returns pkpass file
• Google Pay — POST /bookings/{id}/googlePayPass creates a Google Pay pass
• Email — POST /bookings/{id}/email sends directly to recipient

Best Practices

Date Format

All dates use the yyyyMMdd format (e.g., 20260815 for August 15, 2026). Other formats will result in a DateNotSupportedException.

Booking ID

The bookingId parameter is the NewSkies PNR (record locator), typically 6 alphanumeric characters (e.g., ABC123).

Segment and Passenger Selection

• segment identifies a flight leg (0-based index or segment identifier)
• paxNo identifies a passenger within the booking (0-based index)
• When generating individual passes (barcode, pkpass, Google Pay), specify both segment and paxNo
• For PDF, you can pass arrays to generate multiple passes in one document

Caching

Configuration endpoints (/settings/checkinconfig, /settings/availability) are cached for 1 minute on the Apigee layer. The X-Cache response header indicates hit/miss status.

Rate Limiting

• Spike Arrest: Protects against burst traffic on all endpoints
• Email Quota: Additional quota limit on the email endpoint to prevent abuse
• Implement exponential backoff when receiving HTTP 429 responses

Request Validation Rules

Environment Configuration

Troubleshooting

401 Unauthorized

• Verify your OAuth token is valid and not expired
• Ensure you are using the correct token endpoint for the environment
• Check that your client_id has been approved for the Boardingpass API product

400 Bad Request

• Verify X-SourceMarket header is present and valid
• Check date format is yyyyMMdd
• Ensure booking ID is a valid PNR format

404 Not Found / BookingNotFoundException

• Verify the booking exists in NewSkies for the specified source market
• Check that the lastname matches (if provided)

PastBookingException

• The outbound date is more than 7 days in the past
• Only current and upcoming flights can generate boarding passes

BoardingpassNotSupportedException

• The passenger/segment is not eligible for a boarding pass
• Check that the passenger is checked in (checkedIn: true in status)

Empty Response / No Boarding Passes

• Verify the passenger is checked in
• Check that the flight is within the check-in window
• Confirm the source market matches the booking's airline

429 Too Many Requests

• You have exceeded the spike arrest or email quota limit
• Implement exponential backoff: wait 2^attempt seconds before retrying