Migration Guide: uAPI to TripServices Stays API

This migration guide assists developers in transitioning from the legacy Travelport Universal API (uAPI) SOAP-based hotel booking flow to the modern TripServices Stays API. The TripServices API provides a RESTful interface with simplified request/response structures and improved performance.

Key Benefits of the TripServices API:

• TripServices instead of SOAP/XML - simpler integration
• OAuth 2.0 authentication instead of WS-Security
• Cleaner, more intuitive data structures
• Better error handling with standard HTTP status codes
• Consolidated endpoints reduce complexity
• Two workflow options: v11 (multi-step) or SearchComplete (single call)

Important: This guide covers migration to the TripServices Stays API, which has two versions:

• TripServices Stays API v11 - Multi-step workflow (Search > Availability > Rules)SearchComplete
• API - Single consolidated endpoint (recommended)

This guide shows both paths so you can choose the best approach for your needs.

As a quick refresher, uAPI is a SOAP-based API using XML payloads:

Key Characteristics:

• Protocol: SOAP over HTTP
• Data Format: XML
• Authentication: WS-Security headers
• Multiple SOAP actions for different operations
• Complex nested XML structures
• Property details require separate call

The TripServices Stays API is a modern RESTful API with two workflow options:

Option 1: TripServices API v11 (Multi-Step Workflow)

Option 2: SearchComplete (Single Call)

TripServices API Characteristics:

• Protocol: RESTful HTTP
• Data Format: JSON
• Authentication: OAuth 2.0 Bearer tokens
• Consolidated RESTful endpoints
• Simplified request/response structures
• Property details included in search response
• Standard HTTP status codes for errors

Summary Comparison

uAPI Authentication

uAPI uses WS-Security with username/password in SOAP headers:

<soap:Header>
  <wsse:Security>
    <wsse:UsernameToken>
      <wsse:Username>USERNAME</wsse:Username>
      <wsse:Password>PASSWORD</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
  <Header_v52_0:BranchCode>P1234567</Header_v52_0:BranchCode>
</soap:Header>

TripServices API Authentication

TripServices API uses OAuth 2.0. First, obtain an access token (see Authentication):

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials &
client_id=YOUR_CLIENT_ID &
client_secret=YOUR_CLIENT_SECRET

Then use the token in all API requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

XAUTH_TRAVELPORT_ACCESSGROUP: YOUR_PCC

Key Differences:

• OAuth tokens expire in 24 hours and must be refreshed
• Access group (PCC) is now in XAUTH_TRAVELPORT_ACCESSGROUP header
• No username/password in each authorization request - use token instead
• Token management required (cache tokens, refresh before expiry)

This section shows how to migrate several uAPI calls to the TripServices API v11 endpoints. This maintains the familiar multi-step workflow while modernizing the technology.

uAPI: HotelSearchAvailabilityReq

<soapenv:Envelope>
    <soapenv:Body>
        <hot:HotelSearchAvailabilityReq>
            <com:BillingPointOfSaleInfo OriginApplication="UAPI"/>
            <hot:HotelSearchLocation>
                <hot:HotelLocation Location="SFO"/>
            </hot:HotelSearchLocation>
            <hot:HotelSearchModifiers>
                <hot:NumberOfAdults>2</hot:NumberOfAdults>
            </hot:HotelSearchModifiers>
            <hot:HotelStay>
                <hot:CheckinDate>2025-03-15</hot:CheckinDate>
                <hot:CheckoutDate>2025-03-17</hot:CheckoutDate>
            </hot:HotelStay>
        </hot:HotelSearchAvailabilityReq>
    </soapenv:Body>
</soapenv:Envelope>

TripServices API v11:

{
 "PropertiesQuerySearch": {
  "@type": "PropertiesQuerySearch",
  "CheckInDate": "2025-03-15",
  "CheckOutDate": "2025-03-17",
  "SearchBy": {
   "@type": "SearchByIATACode",
   "IATACode": "SFO"
  },
  "RoomStayCandidate": [
   {
    "GuestCount": {
     "AdultCount": 2
    }
   }
  ]
 }
}

Key Changes:

• JSON instead of XML - simpler structure
• SearchBy object for location (supports coordinates, city, airport)
• RoomStayCandidate replaces HotelSearchModifiers
• Property details (images, amenities) included in response
• No separate HotelDetailsReq needed

uAPI: Availability Included in Search

In uAPI, availability is returned in the HotelSearchAvailabilityReq response.

TripServices API v11: Hotel Availability API

TripServices API v11 requires a separate availability call:

{
 "CatalogOfferingsQueryHospitality": {
  "@type": "CatalogOfferingsQueryHospitality",
  "PropertyIdentifier": [
   "TVPT-12345",
   "TVPT-67890"
  ],
  "HotelStay": {
   "CheckInDate": "2025-03-15",
   "CheckOutDate": "2025-03-17"
  },
  "GuestCount": {
   "AdultCount": 2
  }
 }
}

Key Changes:

• Separate call required (different from uAPI)
• Use PropertyIdentifier from search response
• Returns CatalogOfferingIdentifier needed for rules call
• Rate and room details in response

uAPI: HotelRulesReq

<soapenv:Envelope>
    <soapenv:Body>
        <hot:HotelRulesReq>
            <com:BillingPointOfSaleInfo OriginApplication="UAPI"/>
            <hot:HotelReservationLocatorCode>ABC123</hot:HotelReservationLocatorCode>
            <hot:HotelRulesModifiers>
                <hot:HotelRulesLookup>RatePlanType</hot:HotelRulesLookup>
            </hot:HotelRulesModifiers>
        </hot:HotelRulesReq>
    </soapenv:Body>
</soapenv:Envelope>

TripServices API v11:

{
 "BuildFromCatalogOfferingsRequestHospitality": {
  "CatalogOfferingIdentifier": "abc123-def456-ghi789"
 }
}

Key Changes:

• Use CatalogOfferingIdentifier from availability response
• Returns cancellation policies, deposit requirements, guarantees
• Simpler JSON structure vs XML
• More detailed policy information

Recommended Approach

SearchComplete consolidates search, availability, and rules into a single endpoint. This is the recommended approach for new implementations as it reduces complexity and improves performance.

uAPI: Three Separate SOAP Calls

In uAPI, you make:

• HotelSearchAvailabilityReq - Search and get basic availability
• HotelDetailsReq - Get property details
• HotelRulesReq - Get rate rules and policiesSearchComplete

Single REST Call

One call replaces all three

{
 "stayDetails": {
  "checkInDateLocal": "2025-03-15",
  "checkOutDateLocal": "2025-03-17",
  "guests": {
   "numberOfAdults": 2,
   "numberOfChildren": 0
  }
 },
 "propertyFilter": {
  "location": {
   "iataCode": "SFO"
  },
  "returnOnlyAvailableProperties": true,
  "returnRateSummaryInfo": true
 },
 "requestedCurrency": "USD"
}

What You Get Back:

• Properties with all details (name, address, amenities, images)
• Available rates with complete pricing
• Room type information
• Rate rules including cancellation and deposit policies
• All in one unified JSON response

Benefits vs uAPI:

• One API call instead of three - reduced latency
• No need to manage state between calls
• Simpler error handling (one point of failure)
• Cleaner JSON structure vs XML
• Built-in caching for better performance

The booking, retrieval, modification, and cancellation flows are similar between uAPI and TripServices API, with the main differences being REST/JSON vs SOAP/XML format.

Key Changes:

• Use propertyKey and rateKey from search response
• Payment object structure simplified
• Guest details in cleaner JSON format
• Response includes reservation confirmation immediately

Key Changes:

• RESTful GET instead of SOAP request
• Confirmation ID in URL path
• Complete reservation details in JSON response
• Standardized status codes

Key Changes:

• RESTful PUT for updates
• Send only changed fields
• Response includes updated reservation
• Clearer modification rules and restrictions

Key Changes:

• RESTful DELETE for cancellation
• Cancellation penalties clearly shown in response
• Standard HTTP status codes for success/failure
• Detailed cancellation confirmation

Error Handling

TripServices API error response example:

{
 "errors": [
  {
   "code": "INVALID_REQUEST",
   "message": "Check-in date must be in the future",
   "field": "stayDetails.checkInDateLocal"
  }
 ]
}

Request/Response Size

TripServices API payloads are typically 40-60% smaller than equivalent SOAP/XML:

• Faster transmission over network
• Reduced bandwidth costs
• Easier to parse and process
• More human-readable for debugging

Development Tools

Performance Improvements

• OAuth token caching reduces authentication overhead
• JSON parsing is faster than XMLSearchComplete
• API includes intelligent caching
• RESTful architecture enables better CDN usage
• Smaller payload sizes improve network performance

• Phase 1: Set up OAuth 2.0 authentication and test token management
• Phase 2: Migrate search functionality (choose v11 or SearchComplete)
• Phase 3: Test search thoroughly with various criteria
• Phase 4: Migrate booking workflow (create, retrieve, modify, cancel)
• Phase 5: Update error handling for HTTP status codes
• Phase 6: Performance testing and optimization
• Phase 7: Production cutover with monitoring

Migrating from uAPI to the TripServices Stays API modernizes your integration with significant benefits:

Technical Benefits:

• Simpler REST/JSON architecture vs SOAP/XML
• Modern OAuth 2.0 authentication
• Smaller payloads and faster performance
• Better development tools and documentation
• Standard HTTP status codes for errors
• Choice of workflow: v11 multi-step or SearchComplete single call

Business Benefits:

• Faster development and time-to-market
• Reduced bandwidth and infrastructure costs
• Easier maintenance and debugging
• Better performance for end users
• Modern architecture supporting future enhancements

Recommendation:

For new implementations, we strongly recommend using SearchComplete API. It provides the simplest integration path with best performance. For existing v11 implementations, SearchComplete offers a clear upgrade path with significant benefits.

The Travelport team is available to assist with your migration. Contact your account manager or visit the developer portal for additional resources and support.

We value your feedback on this documentation. If you have suggestions for improvements, find errors, or need clarification on any topic, please contact:

• Your Travelport Account Manager
• Travelport Support team
• Developer Portal feedback form

For urgent API issues or production support, contact Travelport support immediately.

Provide feedback about this documentation

This link does not provide Help Desk support. If you need immediate assistance with Travelport APIs, please create a support request in MyTravelport or use your normal support path.