Enquiry API

Design

To perform a search, we must create an Enquiry.

An Enquiry on the Staylists platform is a dataset that encapsulates the criteria of your customer’s search.

Are you sure?

The API gives you more control of your user interfaces than our JS-to-iFrame solutions, but the trade-off here is the complexity of integrating an API.

The iFrame solution is not intended to be one that you can infinitely customise. Nor should it be considered a final, fixed design. Its goal is two-fold:

1. To enable you to integrate Staylists quickly with minimal friction
2. To give you new features to our platform instantly – you’ll never be behind our development curve

If you have weighed up the trade-offs and would still like to go down the API route, then please read on.

Request

Post your Enquiry data to

https://app.staylists.com/api/v3/enquiries

{
  "start_date": "23/10/2019",
  "nights": 2,
  "occupancies": [
    { "adults": 2, "children": 1, "infants": 0, "dogs": 0 }
  ]
}

A more refined Enquiry

Specific Property IDs

Sometime you might only care about the results for a specific set of properties based on what you’re displaying to your user. In cases like this, the Enquiry object accepts an array of Staylists property IDs.

We recommend using this option because calculating real-time results is expensive in terms of time. The fewer results we need to provide, the faster the response time.

{
  "property_ids": [1456, 2485, 5678, 8976],
  "start_date": "...",
}

Authentication

This request requires authentication

Response codes

If you do all the above, you should receive a 200 response code (success!) and some results for your Enquiry. We discuss the anatomy of a successful response in more detail in the following pages.

However, if you don’t receive a 200, here’s some guidance on what might be happening:

• 401 Unauthorised – you haven’t sent us an access token.
• 404 Not found – your access token is incorrect.
• 400 Bad request – you’ve been authenticated, but you’ve sent us some bad data, like a zero night stay or similar.
• 500 Error – you’ve done something so unexpected that it’s blown our server up.

Please get in touch if you’re really struggling and can’t fathom what’s going on.

Response

The response should look something like this …

{
  "enquiry": {
    "uuid": "124d833",
    "staylist": {
      "name": "Example Staylist",
      "shortname": "examplestaylist"
    },
    "results": [
      {
        "id": 4779,
        "name": "The Crab & Lobster",
        "subdomain": "thecrablobster",
        "available": false,
        "summary": "We only have Double Rooms available on this date.",
        "currency": "GBP",
        "min_price": "0.00"
      },
      {
        "id": 4905,
        "name": "The Hawk Inn",
        "subdomain": "thehawkinn",
        "available": true,
        "summary": "Available from 209.00",
        "currency": "GBP",
        "min_price": "209.00"
      }
    ]
  }
}

Anatomy of a Search Result

Each search result is an object with seven name/value pairs. We do not recommend you couple your implementation to this number, as we may add an eight or ninth at some point in the future.

{
  "id": 4905,
  "name": "The Hawk Inn",
  "subdomain": "thehawkinn",
  "available": true,
  "summary": "Available from 209.00",
  "currency": "GBP",
  "min_price": "209.00"
}