# Migration Guide: uAPI to TripServices Stays API

This document provides general information about the Stays API. For the most current endpoints and examples, see [Authentication](/docs/getting-started/authentication), [Stays Endpoints](/docs/stays/general/stays-api-endpoints), and the API References.

## Introduction

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.

## Overview of uAPI Hotel Booking Flow

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

| Step | SOAP Action | What It Does |
|  --- | --- | --- |
| Search | HotelSearchAvailabilityReq | Find hotels by location with Availability |
| Details | HotelDetailsReq | Get property details and Images |
| Rules | HotelRulesReq | Get rate rules and policies |


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


## Overview of TripServices Stays API

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

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

| Step | Endpoint | What It Does |
|  --- | --- | --- |
| 1. Search

 | POST /search/properties/search | Find hotels with property info |
| 1. Availability

 | POST /availability/catalogofferingshospitality | Get available rates |
| 1. Rules

 | /rules/offershospitality/buildfromcatalogoffering | Get rate policies |


Option 2: SearchComplete (Single Call)

| Step | Endpoint | What It Does |
|  --- | --- | --- |
| Search | /search/searchcomplete | Get everything - properties, rates, AND rules |


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


## Key Differences Between uAPI and TripServices API

Summary Comparison

| Feature | uAPI (SOAP) | TripServices API |
|  --- | --- | --- |
| Protocol | SOAP/XML | REST/JSON |
| Authentication | WS-Security headers | OAuth 2.0 Bearer tokens |
| Request Format | XML with nested elements | JSON with clear structure |
| Response Format | XML | JSON |
| Error Handling | SOAP Faults | HTTP status codes + JSON errors |
| API Calls for Shopping | 2-3 calls (Search, Details, Rules) | v11: 3 calls /
SearchComplete: 1 call |
| Endpoints | Multiple SOAP actions | RESTful endpoints |
| Documentation | WSDL | OpenAPI/Swagger |


## Authentication Migration

uAPI Authentication

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


```xml
<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](/docs/getting-started/authentication)):


```xml
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:


```xml
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)


## Migration Path 1: TripServices API v11 (Multi-Step Workflow)

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.

### Step 1: Hotel Search

uAPI: HotelSearchAvailabilityReq


```xml
<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


### Step 2: Hotel Availability

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


### Step 3: Rate Rules

uAPI: HotelRulesReq


```xml
<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


## Migration Path 2: SearchComplete (Single Call)

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


## Booking Workflow Changes

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.

### Create Booking

Key Changes:

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


### Retrieve Booking

Key Changes:

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


### Modify Booking

Key Changes:

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


### Cancel Booking

Key Changes:

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


## General Changes and Considerations

Error Handling

| uAPI | TripServices API |
|  --- | --- |
| SOAP Faults with error codes | HTTP status codes (400, 401, 404, 500, etc.) |
| Error details in XML structure | Error details in JSON errors array |


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

| uAPI | TripServices API |
|  --- | --- |
| WSDL documentation | OpenAPI/Swagger documentation |
| SoapUI for testing | Postman, Insomnia, curl for testing |


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


## Migration Strategy Recommendations

- 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


## Conclusion

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.

## Document Feedback

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](mailto:john.callaway@travelport.com?subject=JSON%20API%20Feedback)

*This link does not provide Help Desk support. If you need immediate assistance with Travelport APIs, please create a support request in [MyTravelport](https://my.travelport.com/) or use your normal support path.*