Change Log

2019

OwnerRez APIs » API for Channel Integration »

Updated 2 months ago

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
Redirect URL Formats
Reviews
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. Here is an example OwnerRez.postman_environment.json file for the staging environment -- copy this content, insert the key provided by the OwnerRez partner team, and save the file. You'll then be able to import it into Postman.

{
	"id": "811baec5-d0cf-45ac-9179-26f941698622",
	"name": "OwnerRez",
	"values": [
		{
			"key": "fastapi",
			"value": "https://faststage.ownerreservations.com",
			"type": "default",
			"enabled": true
		},
		{
			"key": "username",
			"value": "HaXmlSandbox",
			"type": "default",
			"enabled": true
		},
		{
			"key": "key",
			"value": "your key",
			"type": "secret",
			"enabled": true
		}
	],
	"_postman_variable_scope": "environment",
	"_postman_exported_at": "2022-08-09T15:58:48.113Z",
	"_postman_exported_using": "Postman/9.27.2"
}

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

Optional URL parameters:

Set createRedirectUrl to 'true' and a live bookable quote will be created and return the redirect URL (quoteResponse/quoteResponseDetails/reservationRedirectUrl) for the guest to continue the reservation

<?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

Notes:

external ID's returned for order items must be passed through on the eventual booking request so the charges can match up correctly.
You may see a redirectAfterBookingUrl element in the response if you passed the createRedirectUrl parameter. If provided, it will contain a live URL where the guest can be redirected to complete their booking.

<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
To send information about booking fees, you can use the olbMeta/serviceFee element for guest service fee and/or commission/ownerFee element for owner commission, for example:
```
<commission>
  <ownerFee currency="USD">75.00</ownerFee>
</commission>
<olbMeta>
  <serviceFee currency="USD">125.50</serviceFee>
</olbMeta>
```
These fees will be added to the booking in OwnerRez as guest service fees or host fees respectively, and each user can choose to create expenses for the host fees if they choose.

Full body example:

<?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>
			<ownerFee currency="USD">75.00</ownerFee>
		</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

The Booking Update Service returns a list of bookings changed during a date range.

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

With body:

Set assignedId to the advertiser ID
Set startDate to the minimum change date to retrieve (UTC).
endDate is optional -- the maximum change date to retrieve (UTC).

NOTE: This is not a stay date filter but a change date filter -- it will return a list of bookings changed since the date you specify.

<?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. 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>

Redirect URL formats

The redirect URL formats are used in our interface to allow users and our support staff to go directly to the listing page on your side, given the listing ID. That streamlines the support process and helps make sure there's not a wrong mapping. Here's an example from a different channel so you can see what I mean:

Clicking either of those links will take the user or support over to the listing page on the channel.

The items we need from your team are the following:

How can a user directly link to a public listing page using the channel Listing Identifier? (e.g. https://www.mychannel.com/listing/1234567)
How can a user directly link to a public listing page using the OwnerRez Listing Identifier? (e.g. https://www.mychannel.com/ownerrez/orp7a20440x)

Reviews

There's a review feed that's similar to the other feeds and it provides access to all guest entered reviews.

NOTE: Only reviews entered in the review form directly by a guest will be accessible in the review feed. Any reviews synced from other channels or imported/entered by the user will not show in the review feed.

To set up for testing reviews:

Create or log into a stage/sandbox account that's integrated with the sandbox channel
Create or access some test bookings in the account
Go to the Reviews tab of each booking and use the Request from Guest button to access the guest form and enter a review as a guest.

Once you've added some test reviews, the advertiser and reviews will show in the following feeds:

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.