Experience the difference of "Elite".

Getting Started

Core Concepts

Overview

Bookings & Quotes

Damage Protection

Data Management

Deposits

Email Template Library

Fields

Guests

Hosted Websites

Integrations

Listing Site Integration

Messaging

My Account

Payment Processing

Privacy & Security

Properties

Property Management

Property Sharing

Quotes

Rates

Renter Agreements

Reporting

Reviews

Rules

Security Deposits

Suppressed Email Addresses

Tags

Taxes

Team Access

Technical Stuff

Travel Insurance

Verified Email Domains

Widgets

WordPress Plugin

Channel Management

Channel Management

API Integrations

Calendar Import/Export

Channel Bridge

Integrations

OwnerRez APIs

Payment Processing

Testing

Change Log

2023

2022

2021

2020

2019

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

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

Setup Requirements

For testing, you should the following:

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.

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.