API Toolkit

Guesty’s open API allows you to easily integrate external tools, services, and systems with your account. Users can easily generate multiple access tokens directly from the Guesty App by themselves, for use with the vendors and tools that they use.

User Guide: For Developers

  • The Guesty API is organized with the REST protocol.
  • We use regular HTTP response codes to indicate errors.
  • Authentication is done with headers or https parameters.
  • Response is usually in the JSON format.

API usage requires an easy authentication. You should ask your users to provide you with a Guesty access token. They can create these tokens on the Guesty app, and share with you one. Then, you should use the credentials with an HTTP Basic Auth method (API key is the username and the API secret is the password).

Note: Please do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

User Guide: For Guesty Users 

We can connect to your Guesty account using the Guesty API (a simple way in which two pieces of software can communicate with each other). The same way that you login to Guesty with a username and a password, our software will need a username and password in the form of an access token. The jargon is a little different but is exactly the same - an API key is same as a username and an API secret as the password.

API token types:

  • Internal API token - has full access to all of the listings and account settings and is the same as the "Account Admin" permission level. This is why you should never expose your secret internal API key in any public website's client-side code. You can use the Internal API key to download information from your dashboard, connect your own website to the dashboard, etc.
  • Marketplace API token - a 3rd party service dedicated token. Marketplace API tokens don't provide full access to Guesty like internal API tokens. Each 3rd party service has its own permissions based on its type. These tokens are generated individually for each service via the integration page.

How to generate an internal API token?

Inside your Guesty Dashboard you have the ability to create multiple internal API tokens:

  1. Go to Account -> System settings -> General
  2. In the API Tokens box click on "Generate a key"
  3. In the new window, give a name to the generated key. This way, it will be easier for you to keep track over which key you are using for each integration.
  4. Copy the Key and Secret and send them to the developer or service provider you work with.

Note: Be sure to create a different token for every service, tool, or system you integrate.  Remember: Granting access through the internal API token will allow the person or software with those credentials a full control over your account. Hence, it is important to make sure that you assign a specific token to each service so you’ll be able to track its behavior in your Dashboard.

How to generate a Marketplace API token?

  1. Go to Account -> Integrations -> Marketplace
  2. Click 'Connect' on the relevant's 3rd party service
  3. In the API token generation page click 'Generate new key', you can copy the API token to the clipboard by clicking on the dedicated button
  4. Paste the API token in the service provider’s website or software

upload.png

 

Common Use Cases

Connecting to the Guesty Dashboard through the API allows you to both download data (read) and make changes to reservations and listings (write). To see the full list of capabilities you are welcome to go over the full API documentation here.

  • Connect your own website directly to your Guesty Dashboard using  the internal API - use your existing website to stream reservations directly into Guesty and make sure that the calendars are always synced. You can use the API to receive inquiries, block calendars, update the pricing, and manage your reservations.
  • Download information from your Guesty Dashboard using the internal API - if you are already using an external reporting system, you can add to it the information gathered inside of the Guesty Dashboard. For example, if you are using an external software to calculate your employees salaries, you can download the tasks they completed and the actual date and duration they worked.
  • Give access to external tools using the marketplace API or internal API - be it home automation tools, dynamic pricing, or smart locks, you can easily integrate other tools into your Dashboard. Many companies have already developed API integration with Guesty and are available for connection via the marketplace. If you work with a provider that doesn't have an integration with us, you can share with them the API documentation and see if they are able to connect. The initial integration process can be done within a couple of hours. For more information, you can contact our support team at support@guesty.com.

Code samples

Here is a real-world example of usage of the internal API. The following code was written in Node.js. This sample uses two external node libraries: Axios and CSV.

Import reservations from excel sheet.

var fs = require('fs');
var axios = require('axios');
var CSV = require('csv');

var guestyAPI = 'http://api.guesty.com/api/v2/reservations';

// 1. Get file location from env variables & make sure it exists.
var fileLocation = process.argv[2];
if(!fileLocation || !fs.existsSync(fileLocation)){
  console.log('Path is not viable');
  process.exit(1);
}

// 2. Parse the CSV file using 'CSV'
CSV.parse(fs.readFileSync(fileLocation), function(err, output){
  if(err){
     console.error(err);
     process.exit(1);
  }

  var titles = output[0];
  var data = output.slice(1);

  // 3. Move raw data to more process-comfortable collection
  var dataAsObjects = data.reduce(function(accu, row){
     var dataRow = {}
     titles.forEach(function(title, index){
        dataRow[title] = row[index];
     });
     return (accu || []).concat(dataRow);
  }, []);

  // 4. Map the data entries into Guesty Reservation object
  var reservationsArray = dataAsObjects.reduce(function(accu, row){
     var reservation = {
        checkIn: row["CHECK IN"],
        checkOut: row["CHECK OUT"],
        confirmationCode: row["CONFIRMATION CODE"],
        listingId: row["LISTING\'S ID"],
        guestId: row["GUEST\'S ID"]
     };
     return (accu || []).concat(reservation);
  }, []);

  // 5. Get Guesty token from here: https://app.guesty.com/account/system/general
  var key = 'Copy_your_Guesty_API_key';
  var secret = 'Copy_your_Guesty_API_secret';

  function postReservation(reservation){
     return axios({
        method: 'POST',
        url: guestyAPI,
        auth: {
           username: key,
           password: secret
        },
        data: reservation
     });
  }

  // 6. Pipe the data to the server so we can resolve as bulk
  var promises = reservationsArray.map(function(reservation){
     return postReservation(reservation);
  });

  // 7. Call as bulk
  axios.all(promises).then(function(response){
     console.log('Operation done!');
  }).catch(function(err){
     console.log('Something went wrong');
     console.error(err);
     process.exit(1);
  });
});

 

Was this article helpful?
0 out of 0 found this helpful