# Integration Requirements

This page defines the technical standards, security protocols, and operational requirements that apply across all pmsXchange API components. These requirements ensure reliable, secure, and efficient connectivity between your system and the SiteMinder platform.

## Compliance Policy

All integration partners must adhere to these requirements. Due to the growing number of partner integrations, SiteMinder can no longer accommodate exceptions.

**Non-Compliance Timeline**:

* Partners have **90 days** to remediate non-compliance issues after notification.
* Failure to comply may result in interface deactivation.
* **Critical issues** affecting production stability may result in **immediate temporary suspension**.

***

## Technical Foundation

**Open Travel Alliance (OTA) Specifications**

The pmsXchange API is built on Open Travel Alliance (OTA) version 2003/05 specifications. Integration developers should be familiar with these standards, available at [http://www.opentravel.org](http://www.opentravel.org/). While this documentation is comprehensive, the OTA specifications provide additional context for complex scenarios and edge cases.

#### **SOAP Protocol Requirements**

pmsXchange **exclusively** supports **SOAP 1.1**.

**Message Structure Standards**:

* All messages follow SOAP envelope structure
* OTA message must be within `<SOAP-ENV:Body>`
* Requests include SOAP Security Header (see [Security](#security))
* Responses use empty SOAP Header: `<SOAP-ENV:Header/>`
* Content-Type: `text/xml; charset=utf-8` (no other Content-Types accepted)
* Character Encoding: UTF-8 exclusively

{% hint style="danger" %}
SOAP 1.2, or other protocols are **not supported** for XML/SOAP messages. Systems using alternative protocols must be modified to use SOAP 1.1.
{% endhint %}

#### **REST Endpoints**

pmsXchange includes REST endpoints for specific components:

* [Rooms and Rates](/pmsxchange-api/reference/rooms-and-rates/sm-to-pms.md)
* [Reservation Import](/pmsxchange-api/reference/reservations/import.md)

REST endpoints use standard JSON over HTTPS with Basic Authentication.

***

## Security

### Transport Layer Security

**Minimum Standard**: TLS 1.2 or higher

**Requirements**:

* All communication **must** use HTTPS over port 443
* HTTP (non-secure) connections are **prohibited**
* Production endpoints must use valid SSL certificates
* Self-signed certificates are **not supported**

### Authentication

**Method**: WS-Security (WSSE) UsernameToken (username and password) for SOAP messages and Basic Authentication for REST endpoints.

All SOAP requests include a Security Header with credentials transmitted as plain text within the HTTPS encrypted channel. REST endpoints use HTTP Basic Authentication.

**Authentication Scope**:

* One set of credentials covers all properties in your integration (PMS-level)
* Same credentials used for all API components
* SiteMinder validates credentials on every request
* Invalid credentials return SOAP fault with error code

{% hint style="success" %}
**Security Header Format**: See individual API component pages for complete examples.
{% endhint %}

### Authentication Models

| Model                       | Credentials                | SOAP/XML | REST/JSON |
| --------------------------- | -------------------------- | -------- | --------- |
| **PMS-Level** (Recommended) | One set for all properties | ✅        | ✅         |
| **Hotel-Level** (Legacy)    | Per-property credentials   | ✅        | ❌         |

{% hint style="warning" %}
Hotel-level authentication is maintained for backward compatibility only. New integrations **must** use PMS-level to ensure access to all current and future functionality, including REST endpoints.
{% endhint %}

### Strong Password Policy

**Minimum Requirements**:

* At least **12 characters** long
* Mix of uppercase and lowercase letters
* At least one number
* At least one special character (e.g., `!` `@` `#` `?` `]`)

**Example Strong Password**: `MyP@ssw0rd2024!Secure`

{% hint style="warning" %}
**Restricted Characters**: Do **NOT** use the characters `<` `>` `&` `"` `'` in usernames or passwords as they cause XML parsing issues.
{% endhint %}

### IP Whitelisting (Optional)

Partners may whitelist our IPs for additional security.

**Pre-Production IPs**:

* `52.13.134.140`
* `34.213.128.113`
* `35.164.250.223`

**Production IPs**: Provided by Partner Integrations team during go-live.

{% hint style="success" %}
All SiteMinder requests originate from **port 443** (HTTPS).
{% endhint %}

***

## Message Standards

### EchoToken (Request Identifier)

**Purpose**: Unique identifier for request/response correlation and troubleshooting.

**Requirements**:

* **Must be unique** for every request
* Both request and response include the **same** EchoToken
* Used for log searching and debugging across environments
* **Format**: UUID with `8-4-4-4-12` pattern

**Example**: `ed8835ff-6198-4f38-b589-3058397f677c`

{% hint style="warning" %}
**Critical for Support**: Highly unique EchoTokens enable efficient troubleshooting. Sequential numbers or timestamp-only values slow issue resolution significantly.
{% endhint %}

### TimeStamp Format

**Standard**: ISO 8601 Date and Time format

**Accepted Formats**:

**UTC Time** (recommended):

```
2024-11-19T13:15:30Z
```

**Local Time with Offset**:

```
2024-11-19T08:15:30-05:00
```

{% hint style="success" %}
**Best Practice**: Use UTC timestamps (with `Z` suffix) to eliminate timezone confusion and simplify troubleshooting.
{% endhint %}

### XML Formatting Requirements

**Production Requirement**: Minified XML (single line, no whitespace)

All SOAP XML messages sent to SiteMinder **must be minified**, removing line breaks, newlines, and unnecessary whitespace. Single-line XML enables support teams to efficiently extract complete messages from logs using text searches.

**Correct Format**:

{% code overflow="wrap" %}

```xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header><wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" SOAP-ENV:mustUnderstand="1"><wsse:UsernameToken><wsse:Username>USERNAME</wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password></wsse:UsernameToken></wsse:Security></SOAP-ENV:Header><SOAP-ENV:Body><OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2024-07-06T15:27:41Z" EchoToken="ed8835ff-6198-4f38-b589-3058397f677c"><POS><Source><RequestorID Type="22" ID="PMSCODE"/></Source></POS><AvailStatusMessages HotelCode="HOTELCODE"><AvailStatusMessage BookingLimit="10"><StatusApplicationControl Start="2025-03-01" End="2025-03-01" InvTypeCode="SUP"/></AvailStatusMessage></AvailStatusMessages></OTA_HotelAvailNotifRQ></SOAP-ENV:Body></SOAP-ENV:Envelope>
```

{% endcode %}

**Incorrect Format**:

```xml
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Header>
		<wsse:Security
			xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" SOAP-ENV:mustUnderstand="1">
			<wsse:UsernameToken>
				<wsse:Username>USERNAME</wsse:Username>
				<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASSWORD</wsse:Password>
			</wsse:UsernameToken>
		</wsse:Security>
	</SOAP-ENV:Header>
	<SOAP-ENV:Body>
		<OTA_HotelAvailNotifRQ
			xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0" TimeStamp="2024-07-06T15:27:41+00:00" EchoToken="ed8835ff-6198-4f38-b589-3058397f677c">
			<!-- ... other elements and attributes have been omitted for brevity ... -->
		</OTA_HotelAvailNotifRQ>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

### API Version and Namespace

**API Version**: `1.0`

All OTA messages must include `Version="1.0"` attribute in the root element.

**XML Namespace**: `http://www.opentravel.org/OTA/2003/05`

All OTA messages must declare this namespace using the `xmlns` attribute in the root element.

***

## Configuration

### Endpoint Requirements

**SiteMinder Endpoints** (SiteMinder Provides):

**Test Environment**:

* **SOAP**: `https://tpi-pmsx.preprod.siteminderlabs.com/webservices/{RequestorID}`
* **REST**: `https://pmsx-core-api.dev.siteminderlabs.com/pmses/{pmsCode}`

**Production Environment**: Provided during go-live by Partner Integrations team

**Your Endpoint Requirements** (For Reservations PUSH - Partner Provides):

**Mandatory Requirements**:

* Must use **registered domain name** (direct IP addresses not supported)
* Must be accessible via HTTPS on port 443
* Must accept SOAP 1.1 messages with proper Content-Type
* Must process `OTA_HotelResNotifRQ` messages

{% hint style="info" %}
**Delivery Method Configuration**: Reservation delivery (PUSH or PULL) is configured at PMS level and applies to all properties. You cannot mix delivery methods across properties.
{% endhint %}

### Property Identification (HotelCode)

**Definition**: Unique identifier assigned by SiteMinder for each property.

**Requirements**:

* Must be **unique per property**
* Used consistently across all API components
* Cannot be changed without re-mapping (causes service disruption)

**Format**: Alphanumeric string

**Examples**: `PROP12345`, `HOTEL001`, `ABC`

{% hint style="warning" %}
**Important**: HotelCode is assigned by SiteMinder during property configuration. Your PMS must store and use these codes for all API interactions.
{% endhint %}

### RequestorID / PMS Code

**Definition**: Unique identifier for your PMS integration.

**Usage**:

* **SOAP Messages**: `<RequestorID Type="22" ID="PMSCODE"/>`
* **REST Endpoints**: Part of URL path `/pmses/{pmsCode}/`
* **WSDL URLs**: Part of path `/webservices/{RequestorID}/`

**Requirements**:

* Must match across all message types
* Case-sensitive
* Provided by SiteMinder during setup

***

## Performance and Reliability

### Response Time Requirements

**Target Performance** (per request):

* **Ideal**: Sub-1-second response
* **Acceptable**: 1-2 seconds average
* **Timeout**: 60-120 seconds (failsafe, **not a target**)

{% hint style="danger" %}
**Critical**: The 60-120 second timeout is a failsafe mechanism, not a performance goal. Responses consistently approaching this timeout indicate performance issues requiring immediate attention.
{% endhint %}

**Response Behaviour**:

* Respond with `<Success/>` or `<Errors>` immediately
* Acknowledge receipt promptly
* Process asynchronously if downstream operations take time
* Do not delay HTTP response while performing internal processing

### Message Size Limits

**Maximum Size**: 2MB (uncompressed)

**Requirements**:

* Messages exceeding 2MB will be rejected with SOAP fault
* Break large updates into multiple messages
* Use message bundling effectively (see [Best Practices](#best-practices))

**Error Response for Oversized Messages**:

```xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
            <faultcode>SOAP-ENV:Server</faultcode>
            <faultstring xml:lang="en">Unable to process message. Payload too large</faultstring>
        </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

### Error Handling

**Mandatory Capabilities**:

Your application **must** implement:

**1. Robust Error Detection**

* Validate all requests against OTA schema
* Detect authentication failures immediately
* Identify malformed XML and missing required fields
* Return proper SOAP faults with appropriate error codes

**2. Queuing Mechanism**

* Queue failed updates for retry
* Persist queue across application restarts
* Prevent duplicate processing
* Monitor queue depth and age

**3. Retry Strategy**

* Implement exponential backoff for transient errors
* Distinguish permanent vs. temporary failures
* Define maximum retry attempts
* Establish escalation path for persistent failures

**Recommended Retry Pattern**:

```
Attempt 1: Immediate (0 seconds)
Attempt 2: 5 seconds
Attempt 3: 15 seconds
Attempt 4: 30 seconds
Attempt 5: 60 seconds
After 5 attempts: Alert + manual intervention
```

**Detailed Guidance**: See [Error Handling](/pmsxchange-api/guides/error-handling.md) for complete specifications and error code reference.

***

## Best Practices

### Real-Time Updates

**Timing Requirements**:

* Send updates to SiteMinder within **2 minutes** of changes in PMS
* Ensures accurate, timely synchronization across distribution channels
* Prevents booking conflicts and inventory mismatches

**Implementation**:

* Monitor PMS data changes in real-time
* Trigger immediate update when changes occur
* Do not batch updates on fixed schedules unless changes are frequent

### Response Handling

**Wait for Responses**:

* Wait for SiteMinder response before sending next request for same property
* Set timeout between 60-120 seconds
* Prevents request queuing and duplicate processing

**Process Responses**:

* Validate `<Success/>` or `<Errors>` element
* Log all responses with EchoToken for troubleshooting
* Retry on transient failures, alert on permanent failures

### Delta Updates

**Definition**: Send **only** the data that has changed since the last update.

{% hint style="warning" %}
**Critical**: Delta updates are **strictly enforced** in production. Non-delta updates and frequent full flushes within 24-hour periods are **prohibited** as they significantly impact platform performance.
{% endhint %}

#### **Delta Update Rules**:

**DO Send**:

* Only changed availability values for specific room types and dates
* Only changed restriction values for specific room/rate combinations and dates
* Only changed rate values for specific room/rate combinations and dates

**DO NOT Send**:

* Unchanged data for any dates
* Restrictions when only availability changed
* Full date ranges when only specific dates changed
* Multiple messages for the same room/rate/date that could be bundled

**Example - Availability Change**:

For example, if a user updates the availability of a room to **4** for stay-date **2025-11-08**, please send only the availability change. Do not include restriction or rate data, and exclude any unchanged dates or room rates. While the `OTA_HotelAvailNotifRQ` message allows both availability and restrictions, updates should focus solely on the required changes.

{% tabs %}
{% tab title="Expected (Delta)" %}

```xml
<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ed8835ff-6198-4f38-b589-3058397f677c" TimeStamp="2024-07-06T15:27:41+00:00" Version="1.0">
    <POS>
        <Source>
            <RequestorID Type="22" ID="PMSCODE"/>
        </Source>
    </POS>
    <AvailStatusMessages HotelCode="HOTEL">
        <AvailStatusMessage BookingLimit="4">
            <StatusApplicationControl Start="2025-11-08" End="2025-11-08" InvTypeCode="SUP"/>
        </AvailStatusMessage>
    </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>
```

{% endtab %}

{% tab title="Not Expected (Full Flush)" %}

```xml
<OTA_HotelAvailNotifRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ed8835ff-6198-4f38-b589-3058397f677c" TimeStamp="2024-07-06T15:27:41+00:00" Version="1.0">
    <POS>
        <Source>
            <RequestorID Type="22" ID="PMSCODE"/>
        </Source>
    </POS>
    <AvailStatusMessages HotelCode="HOTEL">
        <!-- Includes availability change -->
        <AvailStatusMessage BookingLimit="4">
            <StatusApplicationControl Start="2025-11-08" End="2025-11-08" InvTypeCode="SUP"/>
        </AvailStatusMessage>
        <!-- Incorrectly includes unchanged restrictions -->
        <AvailStatusMessage>
            <StatusApplicationControl Start="2025-11-08" End="2025-11-08" InvTypeCode="SUP" RatePlanCode="GLD"/>
            <LengthsOfStay>
                <LengthOfStay MinMaxMessageType="SetMinLOS" Time="2"/>
                <LengthOfStay MinMaxMessageType="SetMaxLOS" Time="5"/>
            </LengthsOfStay>
            <RestrictionStatus Status="Close"/>
        </AvailStatusMessage>
        <!-- More unchanged data omitted for brevity -->
    </AvailStatusMessages>
</OTA_HotelAvailNotifRQ>
```

{% endtab %}
{% endtabs %}

### Message Bundling

**Definition**: Combine updates for consecutive dates with the same values into a single date range.

#### **Bundling Best Practices**:

* Include only one room code (availability) or room/rate combination (restrictions/rates) per request
* Bundle all changed dates for that room or room/rate combination
* Use Start/End attributes for consecutive dates with same values
* Use day-of-week flags for pattern-based updates
* Avoid sending multiple small requests for individual dates

{% hint style="warning" %}
**Important**: Date ranges within a single message must not overlap for the same room (availability) or room/rate combination (restrictions/rates).
{% endhint %}

#### **Bundling Strategies**:

{% tabs %}
{% tab title="Consecutive Date Bundling" %}

```xml
<!-- Bundle consecutive dates with same rate -->
<RateAmountMessage>
    <StatusApplicationControl InvTypeCode="DBL" RatePlanCode="BAR"/>
    <Rates>
        <Rate Start="2025-07-01" End="2025-07-14">
            <BaseByGuestAmts>
                <BaseByGuestAmt AmountAfterTax="120.00"/>
            </BaseByGuestAmts>
        </Rate>
    </Rates>
</RateAmountMessage>
```

{% endtab %}

{% tab title="Day-of-Week Bundling" %}

```xml
<!-- Bundle using day-of-week flags within date range -->
<RateAmountMessage>
    <StatusApplicationControl InvTypeCode="DBL" RatePlanCode="BAR"/>
    <Rates>
        <!-- Weekend rate -->
        <Rate CurrencyCode="USD" Start="2025-07-01" End="2025-07-14" 
              Mon="0" Tue="0" Weds="0" Thur="0" Fri="1" Sat="1" Sun="0">
            <BaseByGuestAmts>
                <BaseByGuestAmt AmountBeforeTax="150.00"/>
            </BaseByGuestAmts>
        </Rate>
        <!-- Weekday rate -->
        <Rate CurrencyCode="USD" Start="2025-07-01" End="2025-07-14" 
              Mon="1" Tue="1" Weds="1" Thur="1" Fri="0" Sat="0" Sun="1">
            <BaseByGuestAmts>
                <BaseByGuestAmt AmountBeforeTax="130.00"/>
            </BaseByGuestAmts>
        </Rate>
    </Rates>
</RateAmountMessage>
```

{% endtab %}

{% tab title="Multiple Date Range Bundling" %}

```xml
<!-- Bundle multiple date ranges for same room/rate -->
<RateAmountMessages HotelCode="HOTEL">
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="DBL" RatePlanCode="BAR"/>
        <Rates>
            <Rate CurrencyCode="USD" Start="2025-07-01" End="2025-07-14">
                <BaseByGuestAmts>
                    <BaseByGuestAmt AmountBeforeTax="150.00"/>
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
    <RateAmountMessage>
        <StatusApplicationControl InvTypeCode="DBL" RatePlanCode="BAR"/>
        <Rates>
            <Rate CurrencyCode="USD" Start="2025-07-15" End="2025-07-31">
                <BaseByGuestAmts>
                    <BaseByGuestAmt AmountBeforeTax="170.00"/>
                </BaseByGuestAmts>
            </Rate>
        </Rates>
    </RateAmountMessage>
</RateAmountMessages>
```

{% endtab %}
{% endtabs %}

### Full Flushes (Restricted Usage)

**Definition**: Sending complete data set for a room or room/rate combination, regardless of whether data changed.

**Permitted Usage**:

* Initial property setup/synchronization only
* System recovery after confirmed data mismatch (with SiteMinder approval)
* Migration to new PMS version (one-time)

**Prohibited Usage**:

* Regular operational updates
* Multiple full flushes within 24-hour periods
* As substitute for proper delta update implementation

{% hint style="warning" %}
**Enforcement**: Frequent full flushes significantly impact SiteMinder production environment and are strictly prohibited. Violations may result in immediate interface suspension.
{% endhint %}

### **Full Flush Best Practices** (when permitted):

* Bundle as many dates as possible per request
* Send all dates with same values in single date range
* Follow the 2MB message size limit
* Optimize bundling to minimize number of messages

***

## Pre-Production Checklist

Before requesting production access, verify all requirements are met:

### Security & Configuration

* [ ] All endpoints use HTTPS with valid certificates (not self-signed)
* [ ] Authentication credentials meet strong password policy (12+ characters)
* [ ] PMS-level authentication configured (not hotel-level)
* [ ] TLS 1.2 or higher enabled
* [ ] RequestorID/PMS Code correctly configured

### Message Standards

* [ ] EchoTokens are highly unique (UUID/GUID format)
* [ ] XML output is minified (single line, no whitespace)
* [ ] TimeStamps use ISO 8601 format (UTC recommended)
* [ ] Content-Type is `text/xml; charset=utf-8`
* [ ] API Version set to `1.0` in all SOAP messages
* [ ] XML Namespace correctly declared

### Performance & Reliability

* [ ] Response times meet targets (<2 seconds typical)
* [ ] Error handling with queue and retry implemented
* [ ] Message size validation implemented (2MB limit)
* [ ] Real-time update implementation (within 2 minutes)
* [ ] Queuing mechanism for failed messages

### Functional Requirements

* [ ] Delta update logic implemented and tested
* [ ] Message bundling implemented for consecutive dates
* [ ] Full flush restricted to initial setup only
* [ ] All mandatory test scenarios passed (see [Testing and Certification](https://developer.siteminder.com/siteminder-apis/pms-rms/introduction/pmsxchange/testing-and-certification))
* [ ] Postman collections executed successfully
* [ ] Component-specific requirements met (see [API Reference](https://developer.siteminder.com/siteminder-apis/pms-rms/introduction/pmsxchange/api-reference))

{% hint style="success" icon="sparkles" %}

## Still have questions?

Use the <i class="fa-gitbook-assistant">:gitbook-assistant:</i> **Ask** button at the top of the page to chat with our AI assistant — it can help you navigate the guide, understand requirements, and troubleshoot issues.

If you need more support, visit [Integration Support](/integration-support/integration-support.md).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.siteminder.com/pmsxchange-api/guides/integration-requirements.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.