API for Channel Integration - Setup & Configuration

OwnerRez offers a powerful API for Channel Integration that allows you to become a first-class integrated "channel" (like Vrbo, Booking.com, Airbnb, etc) and promotes you equally with those guys inside of OwnerRez. Here are the steps you need to follow to build a channel integration for OwnerRez.

Register and Enable the Sandbox
Setup Requirements
Postman
Bash
- Setup Variables
- cURL Command for Fast Availability
The Endpoints
Recommended Polling Schedules and Webhooks
Enumerations

Register and Enable the Sandbox

To test your integration, register for an OwnerRez account on our stage environment and turn on the "HAXML Sandbox integration"

To register, go to: https://securestage.ownerreservations.com/join. Use a fake credit card that passes verification (eg. 4111111111111111) to register. Our stage environment will not process real credit card numbers.
To enable the Sandbox channel go to: https://securestage.ownerreservations.com/settings/channels/edit?listingSiteType=HaXmlSandbox

Setup Requirements

For testing, you should the following:

root url: https://faststage.ownerreservations.com
username: HaXmlSandbox
key: please contact us for the password

In production, you should use https://fast.ownerreservations.com as the root domain. We will issue you a unique username and key for your application to use in production.

Before we enable your integration in production, we will need the following:

A logo you would like to use within OwnerRez to identify your business.
Proof of PCI compliance.
Written instructions to provide to property managers who wish to publish through your integration (This will appear on the instructions tab after the PM has enabled your channel)

Grab your advertiserExternalId , listingExternalId , and unitExternalId for configuration and testing.

Here is a screenshot of where you can find the advertiserExternalId:
Here is a screenshot showing the listingExternalId and unitExternalId:

Postman

Environment Variables

The following documentation and configuration reference Postman.

Example Postman OwnerRez configuration file (variables must be changed)
Stage Postman OwnerRez configuration file

Import Postman Configuration

Using Postman Variables

Bash

Setup variables

ownerrez_api="<api>"
ownerrez_user="<username>"
ownerrez_key="<key>"
ownerrez_account_id="<account id>"

cURL Command for Fast Availability

curl --user ${ownerrez_user}:${ownerrez_key} --location --request POST "${ownerrez_api}/haapi/haolbjson/fastavailability" \
--header 'Content-Type: application/json' \
--data-raw '{
"requestVersion": "1.0",
"systemExternalId": "SystemUniqueId",
"advertiserExternalId": "ora7ccdcde3fx",
"listingExternalId": "orp5b2abax",
"dateRange": {
"arrivalDate": "2023-03-16",
"departureDate": "2023-03-22"
},
"adults": 2,
"units": [
{
"unitExternalId": "orp5b2abax"
}
]
}'

Add --silent | jq to skip download progress messages and format the result in JSON.

The Endpoints

Example Postman

Example Bash cURL

curl --user ${ownerrez_user}:${ownerrez_key} --location --request GET "${ownerrez_api}/haapi/haxml/advertiserindex?type=${ownerrez_user}&key=${ownerrez_key}"

Add --silent | xmllint --format - to the end to format in XML.

The advertisersContentIndex => /haapi/haxml/advertiserindex?type=your username&key=your key

Postman with `advertiserAssignedId` Variable

Bash cURL with `advertiserAssignedId` Variable

Set advertiserAssignedId="<account id>"

curl --user ${ownerrez_user}:${ownerrez_key} --location --request GET "${ownerrez_api}/haapi/haxml/${advertiserAssignedId}/listingindex" --silent | xmllint --format -

advertiserListingContentIndexUrl => /haapi/haxml/advertiserAssignedId/listingindex
advertiserListingContentIndexUrl => listingUrl => /haapi/haxml/advertiserAssignedId/listing/listingExternalId
advertiserLodgingConfigurationContentIndexUrl => /haapi/haxml/advertiserAssignedId/lodgingconfigindex
advertiserLodgingRateContentIndexUrl => /haapi/haxml/advertiserAssignedId/lodgingrateindex
advertiserUnitAvailabilityContentIndexUrl => /haapi/haxml/advertiserAssignedId/availabilityindex

OLB (Real-Time Quotes & Bookings)

Checking Live Availability => /haapi/haolbjson/fastavailability
Creating Quotes => /haapi/haolb/quote?type=your username&key=your key
Creating Bookings => /haapi/haolb/createbooking?type=your username&key=your key
Booking Update Service => /haapi/haolb/advertiserAssignedId/bookingindex

Here are some examples of requests and response using cURL. Read below for how to use each of these three features.

Checking Live Availability

POST to /haapi/haolbjson/fastavailability with Basic Auth:

With body:

Set advertiserExternalId to the 'ora' ID
The unitExternalId in units is the one used -- property 'orp' ID. listingExternalId is not used.

{
  "requestVersion": "1.0",
  "systemExternalId": "SystemUniqueId",
  "advertiserExternalId": "ora7ccdce70dx",
  "listingExternalId": "orp5b914x",
  "dateRange": {
    "arrivalDate": "2019-03-16",
    "departureDate": "2019-03-22"
  },
  "adults": 2,
  "children": 2,
  "pets": 5,
  "units": [
    {
      "unitExternalId": "orp5b914x"
    }
  ]
}

Response: success

{
  "units": [
    {
      "unitExternalId": "orp5bae71d29x",
      "available": true
    }
  ]
}

Response: not available or other error with the detailed reason in errorCode

{
  "units": [
    {
      "unitExternalId": "orp5bae71d29x",
      "available": false,
      "errorCode": "PETS_NOT_ALLOWED"
    }
  ]
}

Creating Quotes

POST to /haapi/haolb/quote?type=your username&key=your key with Basic Auth:

With body:

Set advertiserExternalId to the 'ora' ID
Set unitExternalId and listingExternalId to the property 'orp' ID
trackingUuid is your unique id and will be used later for debugging questions

<?xml version="1.0" encoding="UTF-8"?>
<quoteRequest>
	<documentVersion>1.3</documentVersion>
	<quoteRequestDetails>
		<advertiserAssignedId>ora7c4bx</advertiserAssignedId>
		<listingExternalId>orp5bae71d29x</listingExternalId>
		<unitExternalId>orp5bae71d29x</unitExternalId>
		<propertyUrl>stage.homeaway.com/vacation-rental/p3173184</propertyUrl>
		<clientIPAddress>192.168.0.1</clientIPAddress>
		<reservation>
			<numberOfAdults>1</numberOfAdults>
			<numberOfChildren>0</numberOfChildren>
			<numberOfPets>0</numberOfPets>
			<reservationDates>
				<beginDate>2021-03-16</beginDate>
				<endDate>2021-03-21</endDate>
			</reservationDates>
			<reservationOriginationDate>2020-08-21T09:30:47Z</reservationOriginationDate>
		</reservation>
		<trackingUuid>1f921919-716f-4f17-8a96-87649cabdc37</trackingUuid>
	</quoteRequestDetails>
</quoteRequest>

Response: success

Note: external ID's returned for order items must be passed through on the eventual booking request so the charges can match up correctly.

<quoteResponse>
	<documentVersion>1.4</documentVersion>
	<quoteResponseDetails>
		<locale>en_US</locale>
		<orderList>
			<order>
				<currency>GBP</currency>
				<orderItemList>
					<orderItem>
						<feeType>RENTAL</feeType>
						<name>5 nights</name>
						<preTaxAmount currency="GBP">1605.00</preTaxAmount>
						<status>PENDING</status>
						<taxRate>0.000000</taxRate>
						<totalAmount currency="GBP">1605.00</totalAmount>
					</orderItem>
					<orderItem>
						<externalId>ORSUR102511617</externalId>
						<feeType>MISC</feeType>
						<name>Cleaning fee based on £150.00 per stay</name>
						<preTaxAmount currency="GBP">150.00</preTaxAmount>
						<status>PENDING</status>
						<taxRate>0.000000</taxRate>
						<totalAmount currency="GBP">150.00</totalAmount>
					</orderItem>
				</orderItemList>
				<paymentSchedule>
					<acceptedPaymentForms />
					<paymentScheduleItemList>
						<paymentScheduleItem>
							<amount currency="GBP">877.50</amount>
							<description>Booking payment: 50%</description>
							<dueDate>2020-08-21</dueDate>
							<refundable>false</refundable>
						</paymentScheduleItem>
						<paymentScheduleItem>
							<amount currency="GBP">877.50</amount>
							<description>Second payment: 21 days before arrival</description>
							<dueDate>2021-02-23</dueDate>
							<refundable>false</refundable>
						</paymentScheduleItem>
					</paymentScheduleItemList>
				</paymentSchedule>
				<reservationCancellationPolicy>
					<description>Relaxed</description>
				</reservationCancellationPolicy>
			</order>
		</orderList>
		<rentalAgreement>
			<agreementText>RENTER AGREEMENT for {PNAME} and other lipsum</agreementText>
			<externalId>ORAGG654095851</externalId>
		</rentalAgreement>
	</quoteResponseDetails>
</quoteResponse>

Response: error

<quoteResponse>
	<documentVersion>1.4</documentVersion>
	<errorList>
		<error>
			<errorType>PETS_NOT_ALLOWED</errorType>
			<message>This property does not allow pets.</message>
		</error>
	</errorList>
</quoteResponse>

Creating Bookings

POST to /haapi/haolb/createbooking?type=your username&key=your key with Basic Auth:

With body:

Set advertiserExternalId to the 'ora' ID
Set unitExternalId and listingExternalId to the property 'orp' ID
trackingUuid is your unique id and will be used later for debugging questions
travelerSource is a attribution reference that will show to the IPM on the channel tab, or can be left blank
For US addresses, addressLine4 should be the two character state code

<?xml version="1.0" encoding="UTF-8"?>
<bookingRequest>
	<documentVersion>1.3</documentVersion>
	<bookingRequestDetails>
		<advertiserAssignedId>ora7c4bx</advertiserAssignedId>
		<listingExternalId>orp5bae71d29x</listingExternalId>
		<unitExternalId>orp5bae71d29x</unitExternalId>
		<clientIPAddress>127.0.0.1</clientIPAddress>
		<message>Please provide a crib.</message>
		<inquirer locale="en_US">
			<title>Ms.</title>
			<firstName>Amy</firstName>
			<lastName>Smith</lastName>
			<emailAddress>amy@gmail.com</emailAddress>
			<phoneNumber> 5125551212</phoneNumber>
			<address rel="BILLING">
				<addressLine1>10 Main Street</addressLine1>
				<addressLine3>Austin</addressLine3>
				<addressLine4>TX</addressLine4>
				<country>US</country>
				<postalCode>12345</postalCode>
			</address>
		</inquirer>
		<commission/>
		<olbMeta>
			<serviceFee currency="USD">125.50</serviceFee>
		</olbMeta>
		<reservation>
			<numberOfAdults>2</numberOfAdults>
			<numberOfChildren>0</numberOfChildren>
			<numberOfPets>5</numberOfPets>
			<reservationDates>
				<beginDate>2021-03-16</beginDate>
				<endDate>2021-03-21</endDate>
			</reservationDates>
			<reservationOriginationDate>2020-08-21T09:30:47Z</reservationOriginationDate>
		</reservation>
		<orderItemList>
			<orderItem>
				<feeType>RENTAL</feeType>
				<name>5 nights</name>
				<preTaxAmount currency="GBP">1605.00</preTaxAmount>
				<status>PENDING</status>
				<taxRate>0.000000</taxRate>
				<totalAmount currency="GBP">1605.00</totalAmount>
			</orderItem>
			<orderItem>
				<externalId>ORSUR102511617</externalId>
				<feeType>MISC</feeType>
				<name>Cleaning fee based on £150.00 per stay</name>
				<preTaxAmount currency="GBP">150.00</preTaxAmount>
				<status>PENDING</status>
				<taxRate>0.000000</taxRate>
				<totalAmount currency="GBP">150.00</totalAmount>
			</orderItem>
		</orderItemList>
		<paymentScheduleItemList>
			<paymentScheduleItem>
				<amount currency="GBP">877.50</amount>
				<dueDate>2020-08-21</dueDate>
			</paymentScheduleItem>
			<paymentScheduleItem>
				<amount currency="GBP">877.50</amount>
				<dueDate>2021-02-17</dueDate>
			</paymentScheduleItem>
		</paymentScheduleItemList>
		<paymentForm>
			<paymentCard>
				<paymentFormType>CARD</paymentFormType>
				<billingAddress rel="BILLING">
					<addressLine1>10 Main Street</addressLine1>
					<addressLine3>Austin</addressLine3>
					<addressLine4>TX</addressLine4>
					<country>US</country>
					<postalCode>12345</postalCode>
				</billingAddress>
				<cvv>123</cvv>
				<expiration>02/2020</expiration>
				<nameOnCard>Amy Smith</nameOnCard>
				<number>4111111111111111</number>
				<paymentCardDescriptor>
					<paymentFormType>CARD</paymentFormType>
					<cardCode>VISA</cardCode>
					<cardType>CREDIT</cardType>
				</paymentCardDescriptor>
			</paymentCard>
		</paymentForm>
		<trackingUuid>20c98eb5-b596-4e1a-b74d-a391e3fd2a93</trackingUuid>
		<travelerSource>source sub site</travelerSource>
	</bookingRequestDetails>
</bookingRequest>

Response: success

<bookingResponse>
	<documentVersion>1.4</documentVersion>
	<bookingResponseDetails>
		<advertiserAssignedId>ora7c4bx</advertiserAssignedId>
		<listingExternalId>orp5bae71d29x</listingExternalId>
		<unitExternalId>orp5bae71d29x</unitExternalId>
		<externalId>ORB272210</externalId>
		<guestProfileExternalId>ORG33746</guestProfileExternalId>
		<locale>en_US</locale>
		<orderList>
			<order>
				<currency>GBP</currency>
				<orderItemList>
					<orderItem>
						<feeType>RENTAL</feeType>
						<name>Rent</name>
						<preTaxAmount currency="GBP">1605.00</preTaxAmount>
						<status>ACCEPTED</status>
						<taxRate>0.000000</taxRate>
						<totalAmount currency="GBP">1605.00</totalAmount>
					</orderItem>
					<orderItem>
						<externalId>ORSUR102511617</externalId>
						<feeType>MISC</feeType>
						<name>Cleaning fee</name>
						<preTaxAmount currency="GBP">150.00</preTaxAmount>
						<status>ACCEPTED</status>
						<taxRate>0.000000</taxRate>
						<totalAmount currency="GBP">150.00</totalAmount>
					</orderItem>
				</orderItemList>
				<paymentSchedule>
					<acceptedPaymentForms />
					<paymentScheduleItemList>
						<paymentScheduleItem>
							<amount currency="GBP">877.50</amount>
							<dueDate>2020-08-21</dueDate>
							<refundable>false</refundable>
						</paymentScheduleItem>
						<paymentScheduleItem>
							<amount currency="GBP">877.50</amount>
							<dueDate>2021-02-17</dueDate>
							<refundable>false</refundable>
						</paymentScheduleItem>
					</paymentScheduleItemList>
				</paymentSchedule>
				<reservationCancellationPolicy>
					<description>Relaxed</description>
				</reservationCancellationPolicy>
			</order>
		</orderList>
		<rentalAgreement>
			<url>http://dev.orez.io/v1/l/7f8cae9ad6c54be6828cf832bb001ea0</url>
		</rentalAgreement>
		<reservationPaymentStatus>UNPAID</reservationPaymentStatus>
		<reservation>
			<numberOfAdults>2</numberOfAdults>
			<numberOfChildren>0</numberOfChildren>
			<numberOfPets>0</numberOfPets>
			<reservationDates>
				<beginDate>2021-03-16</beginDate>
				<endDate>2021-03-21</endDate>
			</reservationDates>
			<checkinTime>15</checkinTime>
			<checkoutTime>11</checkoutTime>
			<reservationOriginationDate>2020-08-21T09:30:47Z</reservationOriginationDate>
		</reservation>
		<reservationStatus>CONFIRMED</reservationStatus>
	</bookingResponseDetails>
</bookingResponse>

Response: error

<bookingResponse>
	<documentVersion>1.4</documentVersion>
	<errorList>
		<error>
			<errorType>PETS_NOT_ALLOWED</errorType>
			<message>This property does not allow pets.</message>
		</error>
	</errorList>
</bookingResponse>

Booking Update Service

POST to /haapi/haolb/advertiserAssignedId/bookingindex with Basic Auth:

With body:

Set assignedId to the advertiser ID
Set startDate to the starting date to pull
endDate is optional

<?xml version="1.0" encoding="UTF-8"?>
<bookingContentIndexRequest>
	<documentVersion>1.4</documentVersion>
	<advertiser>
		<assignedId>ora7c4bx</assignedId>
	</advertiser>
	<startDate>2020-01-01</startDate>
</bookingContentIndexRequest>

This will return a list of booking detail URLs. For each of those URLs, you can request a GET with Basic Auth, and that will return the detail. The booking status will be on the booking detail URL, which includes other information similar to the OLB booking response. The possible booking statuses are:

UNCONFIRMED
CONFIRMED
CANCELLED_BY_OWNER
CANCELLED_BY_TRAVELER

Recommended Polling Schedules and Webhooks

This API is generally designed around a polling process to collect updates. We recommend checking for updates a couple of times per day, but no more than that -- constant polling can be a large stress on both your systems and ours.

As you process, use the last changed dates at the index level to decide to go further. Keep track of the last changed dates each time you pull. If you pull an index and the last changed date has not changed, then skip processing for the detailed item because it hasn't changed.

We also optionally provide webhook updates for rates and availability. If you'd like us to send live updates for rates and availability, set up endpoints as follows and contact us to walk through the testing and enablement process.

Create two endpoints, one for availability and one for rates. The URL's will be as follows:

Availability: <your service domain>/services/external/unitAvailabilityUpdate/haxmlListingsVersion/4.2
Rates: <your service domain>/services/external/lodgingRateUpdate/haxmlListingsVersion/4.2.1

When updates occur, we'll post an update with the following shape. You should respond either with a success response or an error response which should contain one or more error messages which will be surfaced to users so they know why the failure occurred.

For your response, the following values are allowed:

action - CREATED, UPDATED, NOOP, RECEIVED
status - SUCCESS, ERROR
errorCode - EXCEPTION, AUTHENTICATION, VALIDATION, EXTERNAL_API_EXCEPTION, INVALID_VERSION_EXCEPTION, CONFIGURATION_EXCEPTION, INTERNAL_SERVER_EXCEPTION

Rates

For rates, the body will be:

assignedSystemId and authorizationToken will be generated by us during the setup process and we'll let you know the values so that you can validate that requests are sourced from us
advertiserExternalId will be the 'ora' ID
unitExternalId and listingExternalId will be the property 'orp' ID
lodgingRate will contain the same data you receive in the lodging rates feed

<lodgingRateUpdate>
  <assignedSystemId>ACME-Channel</assignedSystemId>
  <advertiserAssignedId>ora7c4bx</advertiserAssigned>
  <authorizationToken>f6edb007-a941-4000-b138-f7a8adf9f9cf</authorizationToken>
  <listingExternalId>orp5bae71d29x</listingExternalId>
  <unitExternalId>orp5bae71d29x</unitExternalId>
  <lodgingRate>...</lodgingRate>
</lodgingRateUpdate>

Response: success

<lodgingRateUpdateResponse>
  <action>UPDATED</action>
  <advertiserAssignedId>ora7c4bx</advertiserAssigned>
  <listingExternalId>orp5bae71d29x</listingExternalId>
  <status>SUCCESS</status>
  <unitExternalId>orp5bae71d29x</unitExternalId>
</lodgingRateUpdateResponse>

Response: error

<lodgingRateUpdateResponse>
  <action>RECEIVED</action>
  <advertiserAssignedId>ora7c4bx</advertiserAssigned>
  <errors>
    <error>
      <errorCode>EXCEPTION</errorCode>
      <message>Failed to process...</message>
    </error>
  </error>
  <listingExternalId>orp5bae71d29x</listingExternalId>
  <status>ERROR</status>
  <unitExternalId>orp5bae71d29x</unitExternalId>
</lodgingRateUpdateResponse>

Availability

For availability, the body will be:

assignedSystemId and authorizationToken will be generated by us during the setup process and we'll let you know the values so that you can validate that requests are sourced from us
advertiserExternalId will be the 'ora' ID
unitExternalId and listingExternalId will be the property 'orp' ID
unitAvailability will contain the same data you receive in the unit availability feed

<unitAvailabilityUpdate>
  <assignedSystemId>ACME-Channel</assignedSystemId>
  <advertiserAssignedId>ora7c4bx</advertiserAssigned>
  <authorizationToken>f6edb007-a941-4000-b138-f7a8adf9f9cf</authorizationToken>
  <listingExternalId>orp5bae71d29x</listingExternalId>
  <unitExternalId>orp5bae71d29x</unitExternalId>
  <unitAvailability>...</unitAvailability>
</unitAvailabilityUpdate>

Response: success

<unitAvailabilityUpdateResponse>
  <action>UPDATED</action>
  <advertiserAssignedId>ora7c4bx</advertiserAssigned>
  <listingExternalId>orp5bae71d29x</listingExternalId>
  <status>SUCCESS</status>
  <unitExternalId>orp5bae71d29x</unitExternalId>
</unitAvailabilityUpdateResponse>

Response: error

<unitAvailabilityUpdateResponse>
  <action>RECEIVED</action>
  <advertiserAssignedId>ora7c4bx</advertiserAssigned>
  <errors>
    <error>
      <errorCode>EXCEPTION</errorCode>
      <message>Failed to process...</message>
    </error>
  </error>
  <listingExternalId>orp5bae71d29x</listingExternalId>
  <status>ERROR</status>
  <unitExternalId>orp5bae71d29x</unitExternalId>
</unitAvailabilityUpdateResponse>

Enumerations

There are many enumerations (ie. reference values) that are used throughout these API support articles, particularly within the amenities, locations, and content areas. To understand these enumerations, read our list of types and enumerations support article.