Pull (SM -> PMS)

Retrieve reservations from SiteMinder by polling at regular intervals.

API: pmsXchange · Operation: Reservations · Direction: SM → PMS · Method: Pull (PMS-initiated)

What is Reservations Pull (SM -> PMS)?

Reservations Pull (SM -> PMS) is a delivery method where the Property Management Systems (PMS) actively retrieve undelivered reservations, modifications, and cancellations from SiteMinder at regular intervals. This integration ensures that PMSs receive up-to-date booking information from various channels, maintaining consistency and reducing the risk of overbooking.

Delivery Method Configuration: The reservation delivery method (PUSH or PULL) is configured at the PMS level and applies to all properties using your integration. It is not possible to have some properties using Reservations PULL while others use Reservations PUSH. Once configured, all hotels connected to your PMS will retrieve reservations using the same method.

Integration Requirements

Understand the essential requirements for API integration, including connectivity, authentication, message formats, and security protocols.

Web Service Endpoint

SiteMinder will provide a single global endpoint for all hotels for PMS to send pull requests OTA_ReadRQ and receive reservation responses OTA_ResRetrieveRS.
Test Environment Endpoint: https://tpi-pmsx.preprod.siteminderlabs.com/webservices/{RequestorID}

Authentication

SiteMinder will provide a single username/password for all hotels (PMS Level authentication).
PMS must include authentication credentials within the SOAP Security header of each request (OTA_ReadRQ and OTA_NotifReportRQ).

Message Structure

All messages must adhere to the SOAP message format.
OTA message must be encapsulated within the SOAP Body.
Requests must include a SOAP Security Header for authentication.
Responses will be returned in a SOAP envelope with empty SOAP Header.

Content-Type

text/xml; charset=utf-8

Version

SOAP 1.1

Protocol & Security

All communication must occur over HTTPS using TLS 1.2 or higher.
Non-secure (HTTP) connections are not permitted.
Communication is synchronous request/response pairs.
Each message is atomic - processed entirely or not at all.

Message Exchange Flow

When using the pull method, your PMS requests reservations from SiteMinder at regular intervals (typically every 2-5 minutes) using a synchronous SOAP/HTTPS exchange. SiteMinder responds with any pending reservations, modifications, and cancellations that haven't been delivered yet. This process involves two request-response cycles to ensure reliable delivery and confirmation.

Pull Request (PMS to SiteMinder): OTA_ReadRQ Requests undelivered reservations, modifications, and cancellations from SiteMinder.
Reservations Response (SiteMinder to PMS): OTA_ResRetrieveRS Delivers a list of reservations (new bookings, modifications, and cancellations) in response to the pull request.
Confirmation Request (PMS to SiteMinder): OTA_NotifReportRQ Confirms successful receipt or reports processing failure of the received reservations by the PMS.
Receipt Response (SiteMinder to PMS): OTA_NotifReportRS Acknowledges the confirmation and completes the pull transaction cycle.

The PMS must send OTA_HotelAvailNotifRQ to SiteMinder with the updated availability after the reservations, modifications, and cancellations are processed on the PMS system. Refer to the Availability and Restrictions.

Security Header

The Security Header is a mandatory SOAP header that authenticates every request from your PMS to SiteMinder endpoint. It contains the username and password credentials that we provide to the PMS during integration setup.

Key Requirements:

Validation: Our endpoint will validate these credentials on every request.
Scope: One set of credentials is used for all properties in your integration.
Security: Credentials are transmitted as plain text within the HTTPS encrypted channel.
Response: Invalid credentials will return a SOAP fault with appropriate error code.

The only acceptable value for the Password @Type attribute is http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText. Plain text passwords are acceptable as all communication is done over encrypted HTTP (HTTPS).

Requests must include a SOAP Security Header for authentication.

Responses must be returned in a SOAP envelope with an empty SOAP Header.

Requests must include a SOAP Security Header for authentication.

Responses must be returned in a SOAP envelope with an empty SOAP Header.

Multiplicity

In the SOAP Specification tables M refers to the number of instances or occurrences of an element or attribute that are allowed or required in a given context. It defines how many times a particular component (element or attribute) can appear within a specific structure.

Definition

The element or attribute must be present exactly once.

0..1

The element or attribute is optional; it can be present zero or one time.

0..n

The element or attribute can be present zero or more times, with no upper limit (where n represents an infinite number of occurrences).

1..n

The element or attribute must be present at least once and can be present any number of times, with no upper limit.

n..m

Specific range, the element or attribute must be present at least n times and no more than m times (where n and m are specific numbers).

1. Pull Request

The PMS uses OTA_ReadRQ to pull reservations from SiteMinder at regular intervals between 2-5 minutes. The request frequency must be no more than every 2 minutes (e.g. not every 1 minute) and no less than every 5 minutes (e.g. not every 6 minutes).

PMS Level requests all undelivered reservations for all hotels, while Hotel Level requests all undelivered reservations only for the hotel specified in the request. The PMS must chose only one level for the full connectivity and avoid using both levels.

Returns all undelivered reservations, modifications, and cancellations for all hotels associated with PMS code: {PMSCODE}

Requirements: PMS Level authentication.

Returns all undelivered reservations, modifications, and cancellations for a specific hotel with code: {HOTELCODE}

Requirements: Either PMS Level or Hotel Level authentication.

Returns only new reservations (ResStatus="Book") for a specific hotel with code: {HOTELCODE}, excluding modifications and cancellations.

Requirements: Either PMS Level or Hotel Level authentication.

Returns only modifications (ResStatus="Modify") for a specific hotel with code: {HOTELCODE}, excluding new reservations and cancellations.

Requirements: Either PMS Level or Hotel Level authentication.

Returns only cancellations (ResStatus="Cancel") for a specific hotel with code: {HOTELCODE}, excluding new reservations and modifications.

Requirements: Either PMS Level or Hotel Level authentication.

Element / @Attribute

Type

Description

OTA_ReadRQ

Element

Root element for the request.

@xmlns

String

Defines the XML namespace for the request. Will be set to http://www.opentravel.org/OTA/2003/05

@EchoToken

String

Unique identifier for the request, used to match requests and responses. Preferred format: UUID 8-4-4-4-12.

@TimeStamp

DateTime

Time when the request was generated. TimeStamp must use ISO 8601 format.

@Version

Decimal

Specifies the API version. Must be set to 1.0.

POS / Source / RequestorID

Element

Identifies the system which is sending the request. Container for the PMS code.

@Type

Integer

Fixed at 22 (ESRP)

@ID

String

PMS Code assigned by SiteMinder. Remains the same throughout the messages.

ReadRequests

Element

ReadRequests / HotelReadRequest

Element

@HotelCode

String

0..1

Hotel code as recognised by SiteMinder. If omitted, all reservations for the PMS will be returned. Note: This attribute is only optional for central property management systems. It is mandatory for on-site systems.

SelectionCriteria

Element

@SelectionType

String

Must be "Undelivered"

@ResStatus

Enumeration

0..1

Specifies the booking status:

Book

Modify

Cancel

2. Reservations Response

OTA_ResRetrieveRS

The OTA_ResRetrieveRS message returns a list of HotelReservation elements in response to the pull request. Content varies as SiteMinder aggregates reservations from multiple booking channels, each with different formats and data structures.

Key Concepts

ReservationsList

Container element returned by SiteMinder in response to pull requests
May contain zero, one, or multiple HotelReservation elements
Empty when no pending reservations are available

HotelReservation

Represents a single booking from one channel
Multiple reservations can be returned in one ReservationsList
Each includes all associated rooms, guests, and payments

RoomStays

Container for all room bookings within each reservation
Each room type booked creates a separate RoomStay
Example: 2 Double Rooms + 1 Suite = 3 RoomStay elements

Split Stays

When a guest changes room type during their stay
Creates multiple RoomStays with different date ranges
Example: Double Room (Jan 1-3) + Suite (Jan 3-5) = 2 RoomStays

Guest Assignment

ResGuests can be linked to specific RoomStays via ResGuestRPH
Some channels provide no guest details (ResGuests may be empty)
Primary guest indicated by PrimaryIndicator="true"

Pricing Levels

Pricing data is structured across multiple levels. Different OTAs provide different levels of pricing details. SiteMinder passes through what the OTA provides to a PMS system. Always read all levels not just RoomStay Total alone.

Daily rates can be found at RoomRates.RoomRate.Rates.Rate/BaseRoomRates.RoomRate.Rates.Rate/Base - room charge per night, excluding extras
When Rate/Total exceeds Rate/Base, extra charge is included in the daily rate. Service details for this extra are not guaranteed. OTA may embed charges in the total without providing a corresponding Services element
The RoomStay Total at RoomStays.RoomStay.Total covers all daily rates and any room-stay-level extras
The ReservationTotal at ResGlobalInfo.Total is the authoritative total for the entire reservation. It includes all room stays + any services or extras applied at the reservation level. Always use this as the final amount for the reservation.

Batch Processing

Single pull request can retrieve multiple reservations
Each HotelReservation processed independently
All retrieved reservations must be confirmed via OTA_NotifReportRQ

Contains <Success/> element.
Includes <ReservationsList> with one or more reservations.
Each reservation has unique SiteMinder identifiers (e.g., ABC-1234567890, CBA-0987654321), with the corresponding message IDs (e.g., isuokfr1pyc2ntest7 and pbp6s5j08test9n0zi).

Contains <Success/> element.
No <ReservationsList> element (indicates no pending reservations).

Contains <Errors> element instead of <Success/>
Indicates business logic error (e.g., invalid hotel code, authentication failure)

Element / @Attribute

Type

Description

OTA_ResRetrieveRS

Element

Root element

@xmlns

String

Defines the XML namespace for the request. Will be set to http://www.opentravel.org/OTA/2003/05

@EchoToken

String

Unique identifier for the request, used to match requests and responses. Preferred format: UUID 8-4-4-4-12.

@TimeStamp

DateTime

Time when the response was generated. TimeStamp must use ISO 8601 format.

@Version

String

Specifies the API version. Must be set to 1.0

Success

Element

0..1

Either Success or Error element present.

Errors

Element

0..1

Contains a list of errors.

Error

Element

Single error information containing free text.

@Type

String

Type of error. Refer to Error Warning Types (EWT).

@Code

String

Code representing the error. Refer to Error Codes (ERR).

ReservationsList

Element / @Attribute

Type

Description

ReservationsList

Element

0..1

Contains a list of retrieved reservations.

HotelReservation

Element

1..n

Contains the specific reservation information.

@CreateDateTime

DateTime

Date and time when the reservation was first made. Must be set when ResStatus is Book. CreateDateTime must follow the ISO 8601 Date and Time format.

@LastModifyDateTime

DateTime

0..1

Date and time when the reservation was last modified. Must be set when ResStatus is Modify or Cancel. LastModifyDateTime must follow the ISO 8601 Date and Time format.

@ResStatus

Enumeration

Specifies the booking status:

Book

Modify

Cancel

UniqueID

Element

1..2

Unique identifier of the reservation in SiteMinder. - The first UniqueID Type="14"is the unique identifier for the entire reservation and through any subsequent modifications or cancellations. The second UniqueID Type="16" with ID_Context="MESSAGE_UNIQUE_ID" is the unique ID for this message. This identifier must be used to confirm the message once processed.

@Type

Integer

Type="14": Identifier for the reservation in SiteMinder.

Type="16": Identifier for the message transferring the reservation.

@ID

String

SiteMinder reservation ID. Refer to the HotelReservationID attribute for the booking source/channel reservation ID.

@ID_Context

String

0..1

Present for the second UniqueID and always will be "MESSAGE_UNIQUE_ID"

Source

Element / @Attribute

Type

Description

POS

Element

Contains Source details.

Source

Element

1..2

Contains BookingChannel details.

RequestorID

Element

Only present in the first Source element. Identifies the system sending the reservation.

@Type

Integer

Must be set to 22 (ESRP).

@ID

String

Always SITEMINDER

BookingChannel

Element

Contains booking channel information.

@Primary

Boolean

true for the primary booking channel in the first Source element.

false in the second Source element, if present.

@Type

Integer

Always 7 for 'Internet'.

CompanyName

Element

Name of the Booking Channel.

NOTE: This name is subject to change/variation by the Booking Channel. Use the Code attribute below to identify the booking channels.

@Code

String

0..1

Code of the booking channel. See the Booking Agent Codes Table for reference.

RoomStays

Element / @Attribute

Type

Description

RoomStays

Element

Contains details of all room stays.

RoomStay

Element

1..n

One instance of RoomStay per room type booked.

@PromotionCode

String

0..1

If configured, this is the promotion code indicating, for instance, a specific marketing campaign (not the rate code).

@MarketCode

String

0..1

A code to match a market segment for the booking.

@SourceOfBusiness

String

0..1

Specifies where the business came from e.g. radio, newspaper ad, etc.

RoomTypes

Element / @Attribute

Type

Description

RoomTypes

Element

0..1

Provides more information about the room type for this room stay.

RoomType

Element

0..1

Contains specific information about the room type.

@RoomTypeCode

String

0..1

Code of the room booked.

@NonSmoking

Boolean

0..1

Provided by the source channel.

@Configuration

String

0..1

Information about the bedding configuration.

RoomDescription

Element

0..1

Description of the room.

@Text

String

0..1

Name of the room.

AdditionalDetails

Element

0..1

Additional room information provided by the source channel.

AdditionalDetail

Element

0..n

@Type

Integer

Refer to the Additional Detail Type (ADT). Common usages are:

43 - Meal plan information 15 - Promotion information

@Code

String

0..1

Reference code provided by the source channel.

DetailDescription

Element

0..1

Contains the description Text.

@Text

String

Details provided by the source channel.

RatePlans

Element / @Attribute

Type

Description

RatePlans

Element

0..1

Provides more information about the rate plan for this room stay.

RatePlan

Element

0..n

Contains details about the specific rate plan.

@RatePlanCode

String

0..1

Code of the rate booked.

@RatePlanName

String

0..1

Name of the rate plan.

@EffectiveDate

The effective date of the RatePlan.

@ExpireDate

Date

The expire date for a RatePlan, this should be considered an exclusive date, the date for which the current rate plan information is no longer valid.

RatePlanDescription

Element

0..1

Contains the description Text.

@Text

String

0..1

Details provided about the rate plan.

AdditionalDetails

Element

0..1

Additional rate plan information provided by the source channel.

AdditionalDetail

Element

0..n

@Type

Integer

Refer to the Additional Detail Type (ADT). Common usages are:

43 - Meal plan information 15 - Promotion information

@Code

String

0..1

Reference code provided by the source channel.

DetailDescription

Element

0..1

Contains the description Text.

@Text

String

Details provided by the source channel.

RoomRates

This example shows daily rates when the same rate applies to both dates (2025-10-05 and 2025-10-06) and there are additional charges.

Element / @Attribute

Type

Description

RoomRates

Element

A RoomStay can include multiple RoomRate, each containing several rates. This occurs when a single room is booked, but different rate plans apply across the duration of the stay.

RoomRate

Element

1..n

One RoomRate per RoomStay. Multiple rates are listed under the RoomRate.

@RoomTypeCode

String

Code of the room booked.

@RatePlanCode

String

Code of the rate plan booked.

@NumberOfUnits

Integer

Always 1. Each room will be listed in it's own RoomStay element.

Rates

Element

0..1

Rate will contain a timespan for which a rate will apply for a room type. Multiple instances of Rate will be sent if rate changes apply.

Rate

Element

1..n

Contains the daily rate information which matches the entire date range specified in the RoomStay/TimeSpan element.

@UnitMultiplier

Integer

Equal to the number of days between EffectiveDate and ExpireDate. Multiply with the UnitMultiplier to get the total cost for the date span.

@RateTimeUnit

String

Always Day.

@EffectiveDate

Date

Starting date of the rate. This date is inclusive.

@ExpireDate

Date

First day after the applicable period. This date is exclusive.

Base

Element

0..1

Base/Gross per-day amount charged for the room.

@AmountBeforeTax

Decimal

0..1

The unit amount before tax.

@AmountAfterTax

Decimal

0..1

The unit amount after tax.

@CurrencyCode

String

0..1

Use ISO 4217 currency codes.

Taxes

Element

0..1

Contains details of the taxes applied.

@Amount

Decimal

0..1

The unit tax amount.

Tax

Element

0..n

Contains specific tax information.

@Code

String

Indicates the specific tax or fee that is being transferred. Refer to Fee Tax Type (FTT).

@Amount

Decimal

0..1

Tax amount applied.

@Percentage

Decimal

0..1

Tax percentage.

TaxDescription

Element

0..1

Contains the tax description Text.

@Text

String

Text description of the tax.

Total

Element

0..1

Base Rate + any additional occupants and fees/extras. If empty, assume the Base amount equals the Total amount.

NOTE: It is possible that some OTAs do not provide any form of Rate information and as such a RoomRate / Rate / Total cannot be provided in such cases. Currently Hotelbeds (HBD) is a known channel that does not always provide Rate information.

NOTE: Any extras that are to be included in the RoomRate total will be linked through the ServiceRPH node.

@AmountBeforeTax

Decimal

0..1

The total amount before tax.

@AmountAfterTax

Decimal

0..1

The total amount after tax.

@CurrencyCode

String

Use ISO 4217 currency codes.

Taxes

Element

0..1

Contains details of the total taxes applied.

@Amount

Decimal

0..1

The total tax amount.

Tax

Element

0..n

Contains specific tax information.

@Code

String

0..1

Indicates the specific tax or fee that is being transferred. Refer to Fee Tax Type (FTT).

@Amount

Decimal

0..1

Tax amount applied.

@Percentage

0..1

Tax percentage.

TaxDescription

0..1

Text description of the tax.

@Text

String

ServiceRPHs

Element

0..1

Container for the ServiceRPH elements.

ServiceRPH

Element

0..n

Links a service to the Service information at the RoomRate level.

@RPH

Integer

1..n

Links a Service to the Service information provided at the HotelReservation level (if applicable) to this RoomRate.

GuestCounts

Element / @Attribute

Type

Description

GuestCounts

Element

Total guest counts for adult, child, and infant. Adult count must always be sent.

GuestCount

Element

1..3

Represents the count for a specific age group.

@AgeQualifyingCode

Integer

10 - Adult (mandatory)

8 - Child (optional)

7 - Infant (optional)

@Count

Integer

Number of guests for this age group.

TimeSpan

Element / @Attribute

Type

Description

TimeSpan

Element

Contains the timespan for the RoomStay.

@Start

Date

Check-in date.

@End

Date

Check-out date. Must be after Start.

RoomStay Total

This total covers the room stay only. It does not include services or extras applied at the reservation level. See Reservation Total for the complete reservation amount.

Element / @Attribute

Type

Description

Total

Element

0..1

The total amount of the RoomStay.

@AmountBeforeTax

Decimal

0..1

The total amount before tax.

@AmountAfterTax

Decimal

0..1

The total amount after tax.

@CurrencyCode

String

0..1

Use ISO 4217 currency codes.

Taxes

Element

0..1

Contains details of the taxes applied.

@Amount

Decimal

0..1

The total tax amount.

Tax

Element

0..n

Contains specific tax information.

@Code

String

Indicates the specific tax or fee that is being transferred. Refer to Fee Tax Type (FTT).

@Amount

Decimal

0..1

Amount of the tax/fee transferred.

@Percentage