Guestfolio API Documentation

Guestfolio API

This is a discoverable hypermedia (RESTful) API using HAL.

The API intends to allow authenticated vendors and partners to interact with Guestfolio data in a 2-way interface providing methods for realtime reservation creation and modification, extraction of Guestfolio email delivery details, guest survey responses and mobile concierge requests.

Coming soon:

Usage

Follow the resource links below to see the integration methods.

The default format is JSON, which should be specified in the URL as “.json” or via “Accepts: application/json” header.

Use the API endpoint https://guestfolio.net/api.json to traverse links available resources in hypermedia style. It is preferable to use the provided links in the API rather than constructing URLs in the client as this will make your client more resilient to updates.

Authorization

The Guestfolio API uses OAuth2 for authorization. Some definitions are useful:

USERNAME and PASSWORD are not directly part of OAuth but needed to sign in to Guestfolio to manage your client applications.

CLIENT_ID and CLIENT_SECRET Are tokens that identify your applications. These are stored on your server and are needed to request access, but not during regular API requests.

REDIRECT_URI is an optional HTTP endpoint on your server for receiving tokens.

AUTH_GRANT is used to request an ACCESS_TOKEN and REFRESH_TOKEN, it is only exchanged once at the start of the authorization flow.

ACCESS_TOKEN must be sent with each API request. This is valid for 2 hours, and then it must be refreshed.

REFRESH_TOKEN can be used when an access token is expiring to request a fresh access token. (Each new access token supplies the next valid refresh token.)

1. Registering your service

Guestfolio will provide you with a login (USERNAME and PASSWORD) where you can manage your application credentials. (guestfolio.net/oauth/applications)

  1. Log in to /oauth/ with your USERNAME and PASSWORD to manage your client application.

  2. Copy the CLIENT_ID and CLIENT_SECRET and store it on your server.

  3. Provide a REDIRECT_URI where your server will receive tokens.

To get an AUTH_GRANT, click “Authorize”. The server will send it to your REDIRECT_URI:

response

HTTP/1.1 302 Found
Location https://REDIRECT_URI?code=AUTH_GRANT

If your service doesn't provide a valid https endpoint for receiving OAuth2 tokens, use the generic out-of-band URI defined by OAuth2:

urn:ietf:wg:oauth:2.0:oob

With this, the authorization code will be shown to you instead of being redirected to your application, and you can copy it to your client manually.

The REDIRECT_URI must be provided with OAuth2 requests where shown below, even if you are using the special out-of-band URI.

These steps only need to be performed once. If your application loses track of its access token or it needed to be reset, you can re-authorize your app to get a new AUTH_GRANT.

2. Obtaining an access token & refresh token

The AUTH_GRANT is a short-lived token that your client can use to request an ACCESS_TOKEN. It can only be used once within 5 minutes of being issued.

request

POST https://guestfolio.net/oauth/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_GRANT&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI

response

{"access_token":"ACCESS_TOKEN","token_type":"bearer","expires_in":7200,"refresh_token":"REFRESH_TOKEN","scope":"all"}

The returned ACCESS_TOKEN is valid for 2 hours, and the REFRESH_TOKEN should be used to obtain further tokens after they expire.

These tokens should be stored by the client for reuse.

3. Making authenticated requests

The OAuth2 ACCESS_TOKEN must be provided with each request. Access tokens allow the operations granted by the resource owner (hotel).

request

GET https://guestfolio.net/api/
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN

{"reservation_number": "...", "etc": "..."}

response

{"_links": {"self": {"href": "https://..."}, "hotels": {"href": "https://..."}}}

4. Refreshing expired access tokens

The same ACCESS_TOKEN can continue to be used for multiple requests up to 2 hours before it expires. After this, a new one can be requested using the REFRESH_TOKEN that was issued with it. The REFRESH_TOKEN is only valid for the last issued ACCESS_TOKEN, and a new one will be issued after it is refreshed.

To refresh an expired ACCESS_TOKEN:

request

POST https://guestfolio.net/oauth/token
Accept: application/json

grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI

response

{"access_token":"ACCESS_TOKEN","token_type":"bearer","expires_in":7200,"refresh_token":"REFRESH_TOKEN","scope":"all"}

This response is the same as when exchanging an AUTH_GRANT the first time, and these tokens should be stored by the client for reuse like before.

Examples

Ruby

require 'oauth2'
client = OAuth2::Client.new(client_id, client_secret, :site => 'https://guestfolio.net')
access_token = client.auth_code.get_token(authorization_code, :redirect_uri => oauth_callback)

require 'rest-client' # (e.g.)
api = RestClient.get('https://guestfolio.net/api.json', { 'Authorization' => "Bearer #{access_token.token}" })

# subsequently, in 2.hours.from_now
access_token.refresh!
# or
AccessToken.from_hash(client, refresh_token: refresh_token).refresh!

PHP

Using adoy’s PHP-OAuth2 library.

require("Client.php");
require("GrantType/IGrantType.php");
require("GrantType/AuthorizationCode.php");
require("GrantType/RefreshToken.php");

$client = new OAuth2\Client($clientId, $clientSecret);

$auth = $client->getAccessToken( "https://guestfolio.net/oauth/token",
  OAuth2\GrantType\AuthorizationCode::GRANT_TYPE,
  array("code" => $authorizationCode, "redirect_uri" => $oauthCallback)
);

$client->setAccessToken($auth["result"]["access_token"]);
$client->setAccessTokenType(OAuth2\Client::ACCESS_TOKEN_BEARER);

$response = $client->fetch("https://guestfolio.net/api.json");

// subsequently, in time() + 7200;
$client->getAccessToken(
  "https://guestfolio.net/oauth/token",
  OAuth2\GrantType\RefreshToken::GRANT_TYPE,
  array("refresh_token" => $refreshToken)
)

Version history

Guestfolio © 2015

All Resources