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
- 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.comusername
: HaXmlSandboxkey
: 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
andlistingExternalId
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
andlistingExternalId
to the property 'orp' ID trackingUuid
is your unique id and will be used later for debugging questionstravelerSource
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, RECEIVEDstatus
- SUCCESS, ERRORerrorCode
- EXCEPTION, AUTHENTICATION, VALIDATION, EXTERNAL_API_EXCEPTION, INVALID_VERSION_EXCEPTION, CONFIGURATION_EXCEPTION, INTERNAL_SERVER_EXCEPTION
Rates
For rates, the body will be:
assignedSystemId
andauthorizationToken
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 usadvertiserExternalId
will be the 'ora' IDunitExternalId
andlistingExternalId
will be the property 'orp' IDlodgingRate
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
andauthorizationToken
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 usadvertiserExternalId
will be the 'ora' IDunitExternalId
andlistingExternalId
will be the property 'orp' IDunitAvailability
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.