API docs by Redocly

Rental Escapes Partner API (1.0.0)

Download OpenAPI specification:openapi.json

Rental Escapes partner support: support@rentalescapes.com

Catalog, rates, availability, locations and inquiries for Rental Escapes partners.

Getting started

  1. Get a test key. Email partner support for a key starting re_test_. It reads the real catalog, rates and availability, and lets you send inquiries that are checked but never created, so nobody is contacted while you build.

  2. Make a first call. Send the key in the X-RE-API-TOKEN header:

    curl -H "X-RE-API-TOKEN: re_test_..." "https://api.rentalescapes.com/v2/properties?per_page=5"

  3. Load the catalog once. Page through GET /properties (up to 200 per page, follow pagination.next). For each property, fetch what you need: GET /properties/{id} for content, /rates, /availability and /images. Store each property's updated times.

  4. Stay in sync. At most hourly, call GET /properties/changes?since=<start of your previous run>. Re-fetch only the areas whose time moved, and drop properties reported as removed.

  5. Price and send leads. GET /properties/{id}/quote prices a stay. POST /inquiries hands a guest to a reservations agent; with a test key the response says "test": true and nothing is created.

  6. Go live. Ask for a live key (starts re_live_) and swap it in. Nothing else changes: same URL, same responses.

Prefer a client? Import the OpenAPI document into your tools, or use the Postman collection with its test and live environments.

Authentication

Every request carries the X-RE-API-TOKEN header. Keys have scopes: properties:read and locations:read allow GET, inquiries:write allows POST /inquiries. A key may be limited to an allow-list of properties; everything outside it behaves as if it did not exist (404, or an unknown-property error on inquiries). Keep keys on your servers, never in a browser or mobile app.

Test mode. Keys starting re_test_ use the same URL and see the real catalog, rates and availability, but POST /inquiries only validates: it returns the normal response with "test": true and creates nothing. Every response to a partner key carries X-RE-Mode: test or X-RE-Mode: live.

Errors

Every error has the same body:

{ "error": { "code": "validation_failed", "message": "Invalid inquiry.",
             "validation": { "stay.checkin": "Must not be in the past." },
             "request_id": "req_7f3a9c11e2b04d5a6c8e9f01" } }

Branch on code, which is stable: validation_failed, invalid_request, unauthorized, forbidden, not_found, method_not_allowed, rate_limited, internal_error. message is for people and may change. Every response carries an X-Request-Id header; send your own (8-64 of A-Za-z0-9._-) to have it reused, and quote it when you contact us.

Rate limits

Per key, test and live alike: about 600 requests a minute and 10,000 an hour, and about 60 POST /inquiries per 10 minutes. Over a limit you get 429 with code: rate_limited and a Retry-After header: wait that long, then retry. A 429 never creates anything, so retrying an inquiry is safe. After the first full load, sync with GET /properties/changes rather than re-reading the catalog.

Versioning

The version is in the path (/v2). Within a version we only make additive changes:

  • new endpoints, new optional query parameters and new optional request fields;
  • new fields in responses;
  • new values in enums, such as a new fee type.

Build your client to ignore fields it does not know and to handle unknown enum values gracefully.

Breaking changes (removing or renaming a field, changing a type, making a parameter required, changing authentication) only ship in a new version. We announce a new version at least 90 days ahead by email to every partner, and keep the previous version running for at least 6 months after it launches.

Changelog

1.0.0 (October 2026). First release: property catalog and detail, rates, availability, photos, quotes, the change feed, the location catalog, property and general inquiries, and test-mode keys.

Properties

Catalog, per-property detail, rates, availability and photos.

List properties

Paginated catalog of live properties (limited to the allow-list for restricted keys). Poll with updated_since for incremental sync.

Authorizations:
apiKey
query Parameters
page
integer >= 1
Default: 1

Page number, from 1.

per_page
integer [ 1 .. 200 ]
Default: 50

Page size.

updated_since
string <date-time>

Only properties changed at or after this instant (ISO 8601).

location
integer

Location id from GET /locations; matches the location and every descendant.

sort
string
Default: "id"
Enum: "id" "-id" "bedrooms" "-bedrooms" "sleeps" "-sleeps" "updated" "-updated"

Sort field; prefix with - for descending.

checkin
string <date>

With checkout: only properties free for the whole stay.

checkout
string <date>

With checkin.

guests
integer >= 1

Minimum sleeps.

rooms
integer >= 1

Minimum bedrooms.

Responses

Response Schema: application/json
required
Array of objects (PropertySummary)
required
object (Pagination)

Response samples

Content type
application/json
{}

List property changes

Lightweight change log for incremental sync. Without since, every live property with its area change times. With since, only live properties that changed in some area at or after it, plus properties that left the catalog after it (status: removed) so you can drop them. Refreshed hourly: poll no more often than that and pass the time of your previous run as since.

Authorizations:
apiKey
query Parameters
since
string <date-time>

Only changes at or after this instant (ISO 8601).

page
integer >= 1
Default: 1

Page number, from 1.

per_page
integer [ 1 .. 1000 ]
Default: 500

Page size.

Responses

Response Schema: application/json
required
Array of objects or objects (PropertyChange)
required
object (Pagination)

Response samples

Content type
application/json
{
  • "changes": [
    • {
      }
    ],
  • "pagination": {
    • "page": 1,
    • "per_page": 50,
    • "total": 3970,
    • "total_pages": 80,
    • "next": "/properties?per_page=50&page=2"
    }
}

Get a property

Everything shown on the property page: the catalog summary (the same shape as GET /properties) plus descriptions, rooms and beds, amenities, policies and reviews. Rates, availability and photos have their own endpoints. Re-fetch when updated.content changes.

Authorizations:
apiKey
path Parameters
id
required
integer >= 1
Example: 553

Property id from the catalog.

Responses

Response Schema: application/json
id
required
integer
name
required
string
type
required
string
url
required
string <uri>

Public page on rentalescapes.com.

updated_at
required
string <date-time>

Last change of any kind, UTC. Use with updated_since; see updated for which area changed.

required
object (AreaUpdates)

Last change to each area of the property, UTC, refreshed hourly. Re-fetch only the areas that moved: content → GET /properties/{id}, rates → /rates, availability → /availability, images → /images. Null means no change has been recorded for that area.

bedrooms
required
integer
bathrooms
required
integer
sleeps
required
integer
rating
required
number or null

Average review rating out of 5, one decimal.

latitude
required
number or null
longitude
required
number or null
required
object (LocationRef)
required
object or null

Cover photo, or null when none is uploaded.

description
required
string or null

HTML.

location_description
required
string or null
required
Array of objects
amenity_notes
required
string or null

HTML.

staff
required
Array of strings
inclusions
required
string or null
house_rules
required
string or null
required
object
required
object

null when the owner has not said.

required
object
required
Array of objects

Approved guest reviews, newest first.

Response samples

Content type
application/json
{}

Get rates, fees and taxes

Seasonal rate periods, the default rate, fees, taxes and rate notes: the inputs to a quote.

Authorizations:
apiKey
path Parameters
id
required
integer >= 1
Example: 553

Property id from the catalog.

query Parameters
from
string <date>

Exclude periods ending before this date. Default today.

to
string <date>

Exclude periods starting after this date. Default open.

Responses

Response Schema: application/json
property_id
required
integer
required
object
from
required
string <date>

Start of the window returned.

to
required
string or null <date>

End of the window returned, or null when open-ended.

required
Array of objects

Seasonal periods. Several periods can share dates for different bedroom counts; use the smallest rooms at least the bedrooms needed.

required
object or null

Fallback when no period covers a date. No dates.

required
Array of objects
required
Array of objects
notes
required
string or null

Free-text rate notes; may contain HTML.

Response samples

Content type
application/json
{
  • "property_id": 553,
  • "currency": {
    • "code": "USD",
    • "symbol": "$"
    },
  • "from": "2026-10-05",
  • "to": null,
  • "rates": [
    • {
      }
    ],
  • "default_rate": {
    • "id": 90400,
    • "name": "Default",
    • "rooms": 9,
    • "nightly": 4250,
    • "weekly": null,
    • "monthly": null,
    • "min_stay": 5,
    • "balance_days": 60,
    • "currency": "USD"
    },
  • "fees": [
    • {
      }
    ],
  • "taxes": [
    • {
      }
    ],
  • "notes": "Holiday weeks (Dec 20 - Jan 5) require a 7-night minimum."
}

Get booked dates

GET /properties/{id}/availability — booked date ranges for one property.

Authorizations:
apiKey
path Parameters
id
required
integer >= 1
Example: 553

Property id from the catalog.

query Parameters
from
string <date>

Window start. Default today.

to
string <date>

Window end. Default from + 2 years.

Responses

Response Schema: application/json
property_id
required
integer
from
required
string <date>

Start of the window returned.

to
required
string <date>

End of the window returned.

required
Array of objects

Each range blocks the nights from checkin up to, not including, checkout. Ranges straddling the window are included whole.

Response samples

Content type
application/json
{
  • "property_id": 553,
  • "from": "2026-10-05",
  • "to": "2028-10-05",
  • "booked": [
    • {
      }
    ]
}

Get the photo gallery

GET /properties/{id}/images — full photo gallery for one property.

Authorizations:
apiKey
path Parameters
id
required
integer >= 1
Example: 553

Property id from the catalog.

Responses

Response Schema: application/json
property_id
required
integer
required
Array of objects

In display order; the first is the cover.

Response samples

Price a stay

Authoritative total for a specific stay, including fees, taxes and discounts.

Authorizations:
apiKey
path Parameters
id
required
integer >= 1
Example: 553

Property id from the catalog.

query Parameters
checkin
required
string <date>

Today or later.

checkout
required
string <date>

After checkin.

adults
integer [ 1 .. 50 ]
Default: 2

Adults in the party. Used for capacity and for per-adult and per-guest fees.

children
integer [ 0 .. 50 ]
Default: 0

Children in the party. They count toward capacity and per-guest fees, and per-child fees use this number.

bedrooms
integer [ 1 .. 50 ]

Bedrooms to price; raised to fit the guests at two per room.

Responses

Response Schema: application/json
property_id
required
integer
required
object
price_on_request
required
boolean
required
object
required
object or null
average_nightly_rate
required
number or null
tax_rate
required
number or null

Combined tax percentage.

accuracy
required
string or null
Enum: "exact" "estimated" "incomplete" null

exact: every night has a published rate. estimated: some nights use the prior year's rate. incomplete: some nights have no rate and are excluded from the total; ask an agent.

required
object or null

Response samples

Content type
application/json
{
  • "property_id": 553,
  • "currency": {
    • "code": "USD",
    • "symbol": "$"
    },
  • "price_on_request": false,
  • "stay": {
    • "checkin": "2026-12-20",
    • "checkout": "2026-12-27",
    • "nights": 7,
    • "guests": {
      },
    • "bedrooms": 3
    },
  • "totals": {
    • "rate": 26901,
    • "discounts": 0,
    • "fees": 299,
    • "taxes": 2690.1,
    • "total": 29890.1,
    • "refundable_deposits": 0,
    • "total_payable": 29890.1
    },
  • "average_nightly_rate": 3843,
  • "tax_rate": 10,
  • "accuracy": "exact",
  • "rate_range": {
    • "min": 2853,
    • "max": 4250
    }
}

Locations

Destination catalog with ids.

List locations

Flat catalog of every location with live properties beneath it (counted within the allow-list for restricted keys). About 800 rows; refresh daily. Needs locations:read.

Authorizations:
apiKey

Responses

Response Schema: application/json
required
Array of objects

Every location with live properties beneath it, ordered by path so a parent precedes its children.

Response samples

Content type
application/json
{}

Inquiries

Stay requests handed to a reservations agent.

Submit an inquiry

Hands a stay request for the guest in contact to a reservations agent, who follows up by email. The inquiry is tagged with your partner source and, if your key has one, credited to your travel advisor, which carries to the booking. Needs inquiries:write. Property rules the agent enforces, such as a minimum stay or maximum guests, return 400 with a plain message and no field map.

Authorizations:
apiKey
Request Body schema: application/json
required
property_id
integer

A live property from the catalog.

object

General inquiry: a catalog location id, free text, or both (the text is kept as a note).

required
object
object

Nightly budget, general inquiries only.

required
object

The traveller the stay is for, not the advisor. A returning guest is recognised by email. The inquiry is attributed to your organisation through your API key; put the advisor handling the trip in message.

message
string <= 5000 characters

Requests, and anything the agent should know, such as the advisor handling the trip.

reference
string <= 255 characters

Your own id for this lead; stored and echoed back.

Responses

Response Schema: application/json
id
required
integer
status
required
string
Value: "new"

Always new on creation; a reservations agent takes it from there.

test
required
boolean

True when sent with a re_test_ key: the inquiry was validated and answered but not created, and nobody was notified. Test ids start at 900000000.

created_at
required
string <date-time>
reference
required
string or null

Your reference, echoed back.

required
object or null
required
object or null

id and path are null for a free-text destination.

required
object or null
required
object
required
object
required
object

The Rental Escapes reservations agent who owns the lead.

Request samples

Content type
application/json
{
  • "property_id": 553,
  • "destination": {
    • "id": 144,
    • "name": "west coast, near Sandy Lane"
    },
  • "stay": {
    • "checkin": "2026-12-20",
    • "checkout": "2026-12-27",
    • "guests": {
      },
    • "bedrooms": 3
    },
  • "budget": {
    • "min": 1500,
    • "max": 4000
    },
  • "contact": {
    • "first_name": "Ada",
    • "last_name": "Lovelace",
    • "email": "ada@example.com",
    • "phone": "+1 514 555 0100"
    },
  • "message": "Celebrating an anniversary; private chef for two dinners. Advisor: Jane Smith, jane@agency.example",
  • "reference": "trip-991"
}

Response samples

Content type
application/json
{
  • "id": 221345,
  • "status": "new",
  • "test": false,
  • "created_at": "2026-10-05T14:02:11Z",
  • "reference": "trip-991",
  • "property": {},
  • "destination": {
    • "id": 144,
    • "name": "St. James",
    • "path": [
      ]
    },
  • "budget": {
    • "min": 1500,
    • "max": 4000
    },
  • "stay": {
    • "checkin": "2026-12-20",
    • "checkout": "2026-12-27",
    • "nights": 7,
    • "guests": {
      },
    • "bedrooms": 3
    },
  • "contact": {
    • "first_name": "Ada",
    • "last_name": "Lovelace",
    • "email": "ada@example.com"
    },
  • "agent": {
    • "first_name": "Maria",
    • "last_name": "Lopez",
    • "email": "maria@rentalescapes.com",
    • "phone": "1-800-208-5097",
    • "extension": "826"
    }
}