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:
-
Guest concierge requests
-
Aggregated survey metrics
-
Email delivery statistics
-
Room management
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)
-
Log in to /oauth/ with your USERNAME and PASSWORD to manage your client application.
-
Copy the CLIENT_ID and CLIENT_SECRET and store it on your server.
-
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
-
2015-07-20: Added pms_key and guest_pms keys to reservations
-
2015-06-23: Added surveys and response sets functionality
-
2014-07-23: Updated examples showing HTTP dialogue
-
2014-06-06: Added guest language functionality
-
2014-05-06: Added extra_value attribute functionality for reservations
-
2013-12-10: Added user management functionality
-
2013-11-08: Added event management functionality
-
2013-09-04: Added nightly rates collection to reservations
-
2013-07-29: Added status field to reservations
-
2013-02-08: Released 0.2 Oauth2.0 authentication added as well as pagination for results
-
2013-01-08: Released 0.1 API version primarily for reservation creation. Additional support will come for emails, surveys, requests soon.
Copyright
Guestfolio © 2015