NAV Navbar
shell

Introduction

Guestonline_api


The Guestonline API is organized around REST.
We use built-in HTTP features, like HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret API key in any public website's client-side code)
JSON will be returned in all responses from the API, including errors.

To make the Guestonline API as explorable as possible , all examples are generated with an example token.

Authentication

To authorize, use this code:
With shell, you can just pass the correct header with each request
EXAMPLE REQUEST :

$ curl https://api.guestonline.fr/v1/ \
  -H "X-Token: your_token"

Make sure to replace your_token with your API key.
Your token will be provided by the team TableOnline.

You authenticate to the Guestonline API by providing your API keys in the request.
Your API key carries many privileges, so be sure to keep it secret!
You do not need to provide a password.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.
Your token will be provided by the team TableOnline.

Errors

Guestonline uses conventional HTTP response codes to indicate success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error coming from Guestonline's servers. However, all errors are not cleanly mapped to HTTP response codes. When a method call is not allowed, we return a 405 error code.

Error response

Message type description
message present A human-readable message giving more details about the error
object optional describe class of object for request
code optional error code for this request
status optional html code response

Capture Payment error response

On PendingBooking#commit a charge can be captured. If the capture failed specific code are returned

Code description
authentication_required 3D Secure error. User need to authenticate in order to validate the payment
capture_failed Capture failed for another reason detailed in the #message property

Confirm payment data

If authentication is required, payment information are requested to trigger the authentication on the client side. Theses elements are available under the payment_data property of the error

Name type description
client_secret String Client secret to use
payment_method_id String Payment method id
stripe_key String Stripe public key
{
 "error": {
   "code": "authentication_required",
   "payment_data": {
     "client_secret": "xxxx",
     "payment_method_id": "pm_yyy",
     "stripe_key": "..."
   }
 }
}

HTTP Status Code Summary

Code State Description
200 OK Everything worked as expected
400 Bad Request Often missing a required parameter
401 Unauthorized No valid API key provided
402 Request Failed Parameters were valid but request failed
403 Forbidden Access forbidden
404 Not Found The requested item doesn't exist
5XX Server errors Something went wrong on Guestonline's end

Versionning

EXAMPLE REQUEST :

$ curl "https://api.guestonline.fr/v1"  \
-H "X-Token: 8xyDktY8QoUdHPVm3Z7H"

When we make backwards-incompatible changes to the API, we release new dated versions.
The current version is v1.

Pagination

EXAMPLE REQUEST :

$ curl -X GET "https://api.guestonline.fr/v1/contacts" \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d page=2 \
  -d max_results=1

Guestonline utilizes cursor-based pagination, using the parameter page and max_results.

Pagination Arguments

JSON RESPONSE :

  {
    "object":"list",
    "total_count":624,
    "num_pages":624,
    "current_page":2,
    "contacts":
    [
      {
      "object":"contact",
      "id":33173,
      "lastname":"Cabarrou",
      "firstname":"Céline",
      "email":"boute65@guestonline.zaza",
      "birthday":null,
      "gender":null,
      "fixed_phone":"33678027666",
      "mobile_phone":"33678027666",
      "address":"",
      "extra_address":"",
      "postcode":"",
      "city":"",
      "company":null,
      "country":"",
      "accept_email_spam":true,
      "accept_sms_spam":true,
      "note":"Autrgfjghcgjf",
      "warning":false,
      "accept_partners_spam":false,
      "bookings_count":20,
      "last_booking_date":"2014-02-26",
      "country_code":null,
      "status":"valid",
      "restaurant_id":479
      }
    ]
  }
key Constraints Default Description
page 1 to ... 1 page that you want
max_results 1 to 100 40 maximum instances of object per page

Expanding

EXAMPLE REQUEST :

$ curl -X GET "http://api.guestonline.fr/v1/bookings/38765" \
 -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
 -d "expands[]=contact"

JSON RESPONSE :

{
  "object":"booking",
  "id":38765,
  "booking_state":"validated",
  "booked_persons_number":2,
  "present_persons_number":2,
  "cancel_actor":null,
  "cancel_reason":"",
  "booking_type":"restaurant",
  "note":"Terrasse",
  "period":"lunch",
  "booking_date":"2014-10-10",
  "booking_time":"2014-10-10T12:30:00+02:00",
  "email":"duhar.laurent@guestonline.fr",
  "bookings_count":1,
  "firstname":"Laurent",
  "lastname":"Duhar",
  "entity_type":"bookings",
  "contact_id":33454,
  "contact":
  {
    "object":"contact",
    "id":33454,
    "lastname":"Duhar",
    "firstname":"Laurent",
    "email":"duhar.laurent@guestonline.fr",
    "birthday":"1981-02-08",
    "gender":null,
    "fixed_phone":"33622093666",
    "mobile_phone":"33622093666",
    "address":"",
    "extra_address":"",
    "postcode":"",
    "city":"",
    "company":null,
    "country":"",
    "accept_email_spam":true,
    "accept_sms_spam":true,
    "note":"",
    "warning":false,
    "accept_partners_spam":false,
    "bookings_count":1,
    "last_booking_date":"2013-10-31",
    "country_code":null,
    "status":"valid",
    "restaurant_id":479
  }
}

Many objects contain the id of another object in their response properties.
These objects can be expanded inline with the expand request parameter.
Objects that can be expanded are noted in this documentation.

These parameters are available for some API requests, and apply to the response of these requests only.
You can expand multiple things at once by sending an array.

Booking can be expanded with multiple informations :

Key Description
booking_attachments This parameter allows you to retrieve attachments that are associated with the booking
booking_messages This parameter allows you to retrieve messages that are associated with the booking
booking_info This parameter allows you to retrieve extra information associated with the booking
charge This parameter allows you to retrieve the charge associated to the booking
contact This parameter is used to retrieve the contact that is associated with the booking
table_occupation This parameter is used to retrieve the tables that are associated with the booking
upsale_items This parameter allows you to retrieve upsale items attached to the booking
vouchers This parameter allows you to retrieve the vouchers associated with the booking

Restaurant can be expanded with :

Key Description
first_bookable_hours This parameter allows you to retrieve an array of bookable hours for the first bookable service

Period can be expanded with :

Key Description
bookings_detail This parameter allows you to retrieve messages set on restaurant or service
bookable_area_ids This parameter allows you to retrieve all bookable_area_ids for Period

RuntimeService can be expanded with :

Key Description
table_availabilities This parameter allows you to retrieve details on available table types per service

Metadata

EXAMPLE REQUEST :

$ curl -X POST https://api.guestonline.fr/bookings \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "metadata={key: value}"

JSON RESPONSE :

{
  "object":"booking",
  "id":38765,
  "booking_state":"validated",
  "booked_persons_number":2,
  "present_persons_number":2,
  "cancel_actor":null,
  "cancel_reason":"",
  "booking_type":"restaurant",
  "note":"Terrasse",
  "period":"lunch",
  "booking_date":"2014-10-10",
  "booking_time":"2014-10-10T12:30:00+02:00",
  "email":"duhar.laurent@guestonline.fr",
  "bookings_count":1,
  "firstname":"Laurent",
  "lastname":"Duhar",
  "entity_type":"bookings",
  "contact_id":33454, 
  "metadata":
  {
    "key":value
  }
}

Guestonline API allows you to record information on our objects using the metadata parameter.
You can use the metadata parameter to attach key-value data.
This is useful for storing additional structured information about an object.
Metadata you specify is returned in API responses.

Push

Guestonline is able to send push notitifications to a given endpoint. The push consists in sending the entity that has been updated / created on Guestonline.

Here are the entities that can be pushed : RuntimeService, Booking, Contact, Commercial, Opinion

The RuntimeService will have the table_availabilities appended.

DailyAvailabilities

The DailyAvailability object


JSON Example :

{
  "object": "daily_availability",
    "status": "available",
    "date": "2021-10-28",
    "engine_mode": "capacitive"
}

The DailyAvailabilities Web service has been designed in order to be able to quickly query the availability of a restaurant over a whole month (or more).

Key Type Description
date Date date
status Enumerate [available, unavailable, full, waiting, closed, out_of_bookable_range]
engine_mode Enumerate [capacitive, table]

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/daily_availabilities"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "persons=4" \
  -d "restaurant_id=12" \
  -d  "start_date=2021-10-28" \
  -d  "end_date=2021-10-31" \

JSON RESPONSE :

{
    "daily_availabilities": [
        {
            "object": "daily_availability",
            "status": "full",
            "date": "2021-10-28",
            "engine_mode": "capacitive"
        },
        {
            "object": "daily_availability",
            "status": "available",
            "date": "2021-10-29",
            "engine_mode": "table"
        },
        {
            "object": "daily_availability",
            "status": "waiting",
            "date": "2021-10-30",
            "engine_mode": "table"
        },
        {
            "object": "daily_availability",
            "status": "closed",
            "date": "2021-10-31",
        }
    ]
}

6 different statuses

Status Description
available The restaurant is bookable for the selected criteria.
unavailable The restaurant is not bookable for the selected criteria.
full It either means there is not a single seat/table left OR that the restaurant owner either manually marked this date/service as 'full'.
waiting The restaurant is unavailable or full, but the waiting list is enabled for this date/service.
closed The restaurant is closed.
out_of_bookable_range The date is either in the past or too far in the future.

Arguments

Key Status Type Description
restaurant_id Mandatory Integer restaurant id
persons Mandatory Integer persons number
start_date Mandatory Date start date
end_date Mandatory Date end date
commercial_ids Optional Array This parameter is optional and can be used to request availabilities with these commercial_ids
period Optional String This parameter is optional and can be used to request availabilities for a specific period
area_id Optional Integer This parameter is optional and can be used to request availabilities for a specific area_id. Please note that passing an area_id when the restaurant is in capacitive (engine mode) will always result in an "unavailable" status.

Periods

Period represents the online bookable hours of the restaurant.

The period object


JSON Example :

{
  "object": "period",
  "restaurant_id": 479,
  "restaurant_name": "wasabi",
  "period": "lunch",
  "date": "2014-11-06",
  "persons": 2,
  "total_left_seats": 25,
  "hours": 
    [
      {
          "object": "hour",
          "time": "12:00"
      },
      {...},
      ...
    ]  
  "bookings_details": 
    [
      {
          "object": "bookings_detail",
          "note": {
              "en": "please check the menu",
              "fr": "..."
            }
      },
      {...},
      ...
    ]  
}

Key Type Description
restaurant_id Int restaurant id
restaurant_name String restaurant name
period Enumerate [lunch, dinner, afternoon, breakfast]
date Date Date
persons Int persons number requested
total_left_seats Int total number of seats available during the period
hours Array Array of hour objects
bookings_detail Array Array of booking_detail objects

The hour object

Key Type Description
time String format hh:mm (h=hour, m = minute)
booking_state String [validated, initialized, waiting]
bookable_area_ids Array List of bookable_area_ids (displayed if asked in expands)

The BookingDetail object


JSON Example :

{
  "object": "bookings_detail",
  "note": {
      "en": "please check the menu",
      "fr": "..."
    }
}

Key Type Description
note Hash key: locale, value: message

List periods with params

EXAMPLE REQUEST: bookable_area_ids expand

  $ curl -X GET "https://api.guestonline.fr/v1/periods"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H"
  -d date=2020-03-20
  -d persons=4
  -d period=lunch
  -d "expands[]=bookable_area_ids"

JSON RESPONSE :

{
  "periods": [
    {
      "object": "period",
      "restaurant_id": 479,
      "restaurant_name": "Wasabi (Demo)",
      "period": "lunch",
      "date": "2020-03-20",
      "persons": 4,
      "total_left_seats": 50,
      "hours": [
        {
          "object": "hour",
          "time": "12:00",
          "booking_state": "validated",
          "bookable_area_ids": [
            1,
            2,
            3
          ]
        },
        {...},
        {
          "object": "hour",
          "time": "14:00",
          "booking_state": "validated",
          "bookable_area_ids": [
            3
          ]
        }
      ]
    },
    {...},
    ...
  ]
}

EXAMPLE REQUEST: bookings_detail expand

  $ curl -X GET "https://api.guestonline.fr/v1/periods"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H"
  -d date=2014-11-6
  -d persons=2
  -d period=lunch
  -d "expands[]=bookings_detail"

JSON RESPONSE :

{
  "object": "list",
  "periods": 
    [
      {
        "object": "offer",
        "id": 162,
        "name": "a name",
        "description": "My period",
        "start_date": "2014-11-06",
        "end_date": "2014-11-06",
        "permanent": false,
        "bookable": false,
        "minimum_dishes": 1,
        "maximum_dishes": null,
        "restaurant_id": 479
      },
      {...},
      ...
    ]
}

JSON RESPONSE WHEN NO PERIODS FOUND:

{
  "object": "list",
  "periods": [],
  "next_available_date": '2014-11-07'
}

Guestonline Api provides a way to retrieve a list of periods.
All these parameters can be used to refine your search.

Arguments

Key Status Description warning
date Mandatory Date for request
persons Mandatory persons number for request
restaurant_id Dependant This parameter is optional if your token manages a single restaurant. In case you token can manage more than one restaurant, you must provide it .
area_id Optional This parameter is optional and can be used to request periods for a specific area_id
period Optional use to filter to a specific period period must be in [lunch, dinner, afternoon, breakfast]
expands Optional This parameter is optional see Expanding

PendingBooking

The PendingBooking object


JSON Example :

{
  "object": "pending_booking",
  "id": "55cc4c049089c76870000001",
  "date": "2015-08-25",
  "hour": "13:30",
  "opening_id": "54e7809af5cb5c1dcb000ff5",
  "persons": 4,
  "restaurant_id": 479,
  "user_locale": "fr",
  "optional": false,
  "booking_state": "validated",
  "area_id": null,
  "commitable": false,
  "metadata": null,
  "contact_info": {
    "object": "contact_info",
    "firstname": null,
    "lastname": null,
    "email": null,
    "mobile_phone": null,
    "country_code": null,
    "message": null,
    "gender": null,
    "birthday": null,
    "company": null
  },
  "available_commercials": [
    {
      "object": "offer",
      "id": 469,
      "name": "Test",
      "description": "tez ef dsf fefdf dfs",
      "start_date": "2015-08-22",
      "end_date": "2015-08-31",
      "permanent": false,
      "bookable": null,
      "minimum_dishes": 1,
      "maximum_dishes": null,
      "restaurant_id": 479,
      "has_prepayment": true
    },
    ...
  ],
  "available_menus": [
    {
        "object": "menu",
        "id": 3459,
        "name": "Menu degustation",
        "description": "starter\r\n*\r\nMain\r\n*\r\nDesserts\r\n",
        "start_date": null,
        "end_date": null,
        "permanent": true,
        "bookable": null,
        "minimum_dishes": 1,
        "maximum_dishes": null,
        "restaurant_id": 479,
        ....
    },
    ...
    ],  
  "selected_menus": [
    {
        "object": "menu",
        "id": 3459,
        "name": "Menu degustation",
        "quantity": 2,
    },
    ...
    ],  
  "menu_selection_requested": false,
  "voucher_infos": null,
  "bookings_detail": "Please make sure you inform us of any special dietary requirements when you make your reservation",
  "prepayment": null
}

A pending booking represents a booking during the online reservation process. It holds the seats during the booking process. It allows to finalize the process (fillings contact fields or payment). A pending booking is valid for a maximum of 7 minutes, since the creation or the last update. After this time it is destroyed and the seats are released.

In order to be transformed into a Booking, the PendingBooking must be committed. The commitable property shows if the PendingBooking is commitable or not.

Key Type Description
id String pending_booking id
date Date pending_booking date
hour DateTime pending_booking hour
persons Int number of persons for pending_booking
restaurant_id Int restaurant id
commitable Boolean true if pending booking can be saved as booking
contact_info ContactInfo contact info for pending_booking
available_commercials Commercial Commercials available for this pending_booking
available_menus Commercial Menus available for this pending_booking
selected_menus SelectedMenu Menus selected with this pending_booking
menu_selection_requested Boolean true if a menu must be picked up for this service
offer CommercialLight selected offer
prepayment Prepayment if pending_booking needs prepayment
metadata Hash metadata added on pending booking creation
optional Boolean if true, the PendingBooking has to be validated
booking_state String booking state in ["initialized", "waiting", "validated", "canceled"]

ContactInfo

Parameter Status Description
lastname String contact's lastname
firstname String contact's firstname
mobile_phone String contact's mobile phone
country_code String contact's country code
email String contact's email address
message String contact message
gender Integer contact's gender (1: male, 2: female)
birthday String contact's birthday
company String contact's company

Prepayment

Parameter Status Description
kind String Kind of prepayment (by seats or booking)
amount Int in cents
stripe_key String stripe key to be able to create a stripe_token
payment_kind String kind of payment (guarantee or down_payment)

CommercialLight

Parameter Status Description
commercial_id Int commercial's id

SelectedMenu

Parameter Status Description
id String menu's id
name String menu's name
quantity Int selected quantity

Create pending_booking

EXAMPLE REQUEST :

  $ curl -X POST "https://api.guestonline.fr/v1/pending_bookings"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "restaurant_id=479" \
  -d "date=2014-11-27" \
  -d "hour=13:30" \
  -d "persons=4" \
  -d "metadata[biz_metric1]=val1"
  -d "metadata[biz_metric2]=val2"

JSON RESPONSE :

{
  "object": "pending_booking",
  "id": "55cc4c049089c76870000001",
  "date": "2015-08-25",
  "hour": "13:30",
  "opening_id": "54e7809af5cb5c1dcb000ff5",
  "persons": 4,
  "restaurant_id": 479,
  "user_locale": "fr",
  "optional": false,
  "booking_state": "validated",
  "commitable": false,
  "area_id": null,
  "contact_info": {
    "object": "contact_info",
    "firstname": null,
    "lastname": null,
    "email": null,
    "mobile_phone": null,
    "country_code": null
    "message": null,
    "gender": null,
    "birthday": null,
    "company": null
  },
  "available_commercials": [
    {
      "object": "offer",
      "id": 469,
      "name": "Special Offer",
      "description": "special offer for all our clients",
      "start_date": "2015-08-22",
      "end_date": "2015-08-31",
      "permanent": false,
      "bookable": null,
      "minimum_dishes": 1,
      "maximum_dishes": null,
      "restaurant_id": 479,
      "has_prepayment": true
    }
  ],
  "voucher_infos": null,
  "bookings_detail": "Please make sure you inform us of any special dietary requirements when you make your reservation",
  "prepayment": null,
  "metadata": {
    "biz_metric1"= "val1",
    "biz_metric2"= "val2"
  }
}

GuestOnline Api provides a way to create a pending booking.

Arguments

Parameter Status Description
date Mandatory you must provide it .
hour Mandatory you must provide it .
restaurant_id Mandatory you must provide it .
persons Mandatory you must provide it .
area_id Optional you can request a specific area_id as long as it belongs to the restaurant list of bookable areas.
contact_info Optional you can provide it on pending booking update .
metadata Optional hash of extra data to store

Update pending booking

EXAMPLE REQUEST :

  $ curl -X PUT "https://api.guestonline.fr/v1/pending_bookings/55cc4c049089c76870000001"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "selected_offer=469" \
  -d "contact_info[lastname]=Doe" \
  -d "contact_info[firstname]=John" \
  -d "contact_info[mobile_phone]=0692550398" \
  -d "contact_info[country_code]=FR" \
  -d "contact_info[email]=j.doe@example.com" \

JSON RESPONSE :

{
  "object": "pending_booking",
  "id": "55cc4ddf9089c76870000002",
  "date": "2015-08-25",
  "hour": "13:30",
  "opening_id": "54e7809af5cb5c1dcb000ff5",
  "persons": 4,
  "restaurant_id": 479,
  "user_locale": "fr",
  "optional": false,
  "booking_state": "validated",
  "commitable": true,
  "area_id": null,
  "contact_info": {
    "object": "contact_info",
    "firstname": "John",
    "lastname": "Doe",
    "email": "j.doe@example.com",
    "mobile_phone": "33692550398",
    "country_code": "FR"
    "message": null,
    "gender": null,
    "birthday": null,
    "company": null
  },
  "offer": {
    "object": "offer",
    "commercial_id": 469
  },
  "voucher_infos": null,
  "bookings_detail": "Please make sure you inform us of any special dietary requirements when you make your reservation",
  "prepayment": {
    "kind": "seats",
    "amount": 4000,
    "stripe_key": "pk_test_abs9s8CTCdDT2B7D8q9j5DAH"
  }
}

JSON RESPONSE WITH CONTACT INFO ERRORS:

{
  "error": {
    "contact_info": {
      "lastname": [
          "Must not leave blank"
      ],
      "email": [
          "Is incorrect"
      ],
      "mobile_phone": [
          "is an invalid number"
      ]
    }
  }
}

GuestOnline Api provides a way to add contact/voucher info on a pending booking, and/or select an offer.

Arguments

Arguments Status Description
selected_offer Optional the selected offer id (from available_commercials)
contact_info Optional the contact_info to add or update in the pending_booking
voucher_infos Optional the voucher_infos to add or update in the pending_booking

ContactInfo to provide if not provided at creation

Parameter Status Description
contact_info[lastname] Mandatory you must provide it .
contact_info[firstname] Mandatory you must provide it .
contact_info[mobile_phone] Mandatory you must provide it .
contact_info[country_code] Mandatory you must provide it .
contact_info[email] Mandatory you must provide it .

VoucherInfo to provide if a voucher need to be linked to the pending_booking

Parameter Status Description
voucher_infos[code] Mandatory voucher code, you must provide it .
voucher_infos[description] Mandatory voucher description, you must provide it .
voucher_infos[voucher_type] Mandatory voucher partner from which came the voucher, you must provide it .
voucher_infos[amount] Optional float, amount include in the voucher .
voucher_infos[name] Optional name of the voucher .

Returns

Returns the modified pending_booking object, adding the Prepayment if needed (+ the stripe public key to allow you to use strip api for the payment) and the commercial_id of selected_offer.

If contact_info is not valid, a detailed error is reported: see JSON RESPONSE WITH CONTACT INFO ERRORS

Pick a menu

EXAMPLE REQUEST :

  $ curl -X PUT "https://api.guestonline.fr/v1/pending_bookings/55cc4c049089c76870000001/pick_menu"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "menu_id=3459" \
  -d "quantity=2" \

JSON RESPONSE :

{
  "object": "booking",
  "id": 1094518,
  "booking_state": "validated",
  "booked_persons_number": 4,
  "present_persons_number": 4,
  "cancel_actor": null,
  "cancel_reason": null,
  "booking_type": "website",
  "note": null,
  "period": "lunch",
  "booking_date": "2015-08-25",
  "booking_time": "2015-08-25T13:30:00+02:00",
  "email": "j.doe@example.com",
  "firstname": "John",
  "lastname": "Doe",
  "entity_type": "bookings",
  "contact_id": 435833,
  "send_reminders": false,
  "user_locale": "fr",
  "metadata": null,
  "booking_token": "a-booking-token"
  ...
  "selected_menus": [{
    "object": "menu",
    "name": "Menu degustation",
    "commercial_id": "3459",
    "quantity": 2
   }
  ]
}

GuestOnline Api provides a way to pick a menu

Arguments

Arguments Status Description
menu_id Int menu's id
quantity Int quantity to pick

Returns

Returns the pending booking.

Remove a menu

EXAMPLE REQUEST :

  $ curl -X PUT "https://api.guestonline.fr/v1/pending_bookings/55cc4c049089c76870000001/remove_menu"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "menu_id=3459" \

JSON RESPONSE :

{
  "object": "booking",
  "id": 1094518,
  "booking_state": "validated",
  "booked_persons_number": 4,
  "present_persons_number": 4,
  "cancel_actor": null,
  "cancel_reason": null,
  "booking_type": "website",
  "note": null,
  "period": "lunch",
  "booking_date": "2015-08-25",
  "booking_time": "2015-08-25T13:30:00+02:00",
  "email": "j.doe@example.com",
  "firstname": "John",
  "lastname": "Doe",
  "entity_type": "bookings",
  "contact_id": 435833,
  "send_reminders": false,
  "user_locale": "fr",
  "metadata": null,
  "booking_token": "a-booking-token"
  ...
  "selected_menus": []
}

GuestOnline Api provides a way to remove a selected menu from the selection

Arguments

Arguments Status Description
menu_id Int menu's id

Returns

Returns the pending booking

Commit the pending_booking and create the booking

EXAMPLE REQUEST :

  $ curl -X PUT "https://api.guestonline.fr/v1/pending_bookings/55cc4c049089c76870000001/commit"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "stripe_token=tok_16YuLg4QnRLJ9Q2EYXevGsFv" \

JSON RESPONSE :

{
  "object": "booking",
  "id": 1094518,
  "booking_state": "validated",
  "booked_persons_number": 4,
  "present_persons_number": 4,
  "cancel_actor": null,
  "cancel_reason": null,
  "booking_type": "website",
  "note": null,
  "period": "lunch",
  "booking_date": "2015-08-25",
  "booking_time": "2015-08-25T13:30:00+02:00",
  "email": "j.doe@example.com",
  "firstname": "John",
  "lastname": "Doe",
  "entity_type": "bookings",
  "contact_id": 435833,
  "send_reminders": false,
  "user_locale": "fr",
  "metadata": null,
  "booking_token": "a-booking-token"
}

GuestOnline Api provides a way to create the booking from the pending_booking .

Arguments

Arguments Status Description
stripe_token Mandatory mandatory only if pending_booking has prepayment (https://stripe.com/docs/tutorials/forms), for you to generate using stripe key provided in the last response.

Returns

Returns the created booking or a CaptureError

Commit after payment authentication

EXAMPLE REQUEST :

  $ curl -X PUT "https://api.guestonline.fr/v1/pending_bookings/55cc4c049089c76870000001/payment_confirmed"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" 

JSON RESPONSE :

{
  "object": "booking",
  "id": 1094518,
  "booking_state": "validated",
  "booked_persons_number": 4,
  "present_persons_number": 4,
  "cancel_actor": null,
  "cancel_reason": null,
  "booking_type": "website",
  "note": null,
  "period": "lunch",
  "booking_date": "2015-08-25",
  "booking_time": "2015-08-25T13:30:00+02:00",
  "email": "j.doe@example.com",
  "firstname": "John",
  "lastname": "Doe",
  "entity_type": "bookings",
  "contact_id": 435833,
  "send_reminders": false,
  "user_locale": "fr",
  "metadata": null,
  "booking_token": "a-booking-token"
}

Guestonline Api provides a way to commit the pending booking after authorization_required error. Indeed once the authorization_require error is raised, on the commit, the authorisation must be done on the client side. Once done the pending booking can be commited with payment_confirmed.

Returns

Returns the created booking

Cancel the pending_booking

EXAMPLE REQUEST :

  $ curl -X DELETE "https://api.guestonline.fr/v1/pending_bookings/55cc4c049089c76870000001"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "stripe_token=tok_16YuLg4QnRLJ9Q2EYXevGsFv" \

JSON RESPONSE :

{
}

GuestOnline Api provides a way to cancel / destroy the pending booking to release the seats.

Arguments

Arguments Status Description
ID Mandatory pending booking ID

Returns

Returns the created booking.

Bookings

The booking object

JSON Example :

{
  "object": "bookings",
  "id": 577988,
  "booking_state": "validated",
  "booked_persons_number": 2,
  "present_persons_number": 2,
  "cancel_actor": null,
  "cancel_reason": null,
  "booking_type": "restaurant",
  "note": null,
  "period": "dinner",
  "booking_date": "2014-09-05",
  "booking_time": "2014-09-05T20:00:00+02:00",
  "email": "nelle@heller.uk",
  "firstname": "Mazie",
  "lastname": "Hegmann",
  "send_reminders": true,
  "user_locale": "Fr",
  "metadata": {
      "data1": "val",
      "data2": 3
   },
  "contact_id": 622360,
  "restaurant_id": 479
}
Key Type Description
id Int booking if
object String define type of object booking
booking_state String status of booking in [initialized, validated, canceled, fully_faked, partially_faked, honored]
booked_persons_number Int expected number of people (maximum 11 digits)
present_persons_number Int number of people present (maximum 11 digits)
cancel_actor String cancel actor of booking in [commercial, restaurateur, user, admin]
cancel_reason Text booking cancel reason (maximum 65535 characters)
booking_type String type of booking in [restaurant, tableonline, website, external, facebook, lafourchette]
note Text booking note (maximum 65535 characters)
period String booking period in [breakfast, brunch, lunch, afternoon, dinner, no_service]
booking_date Date booking date
booking_time Datetime booking time
email String contact's email for booking (maximum 300 characters)
firstname String contact's firstname for booking (maximum 50 characters)
lastname Int contact's lastname for booking (maximum 50 characters)
send_reminders Bool true if reminders are sent to customer
user_locale String locale used or requested by the customer on booking creation
metadata Hash extra properties associated to the booking with the api
booking_token String token returned on booking creation. It can be requested for specific operation
contact_id Int id of contact for booking (maximum 11 characters)
restaurant_id Int restaurant id for booking (maximum 11 digits)

List bookings with params

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/bookings"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H"

JSON RESPONSE :

{
  "object":"list",
  "total_count":930,
  "num_pages":24,
  "current_page":1,
  "bookings":
  [
    {
      "object":"booking",
      "id":577988,
      "booking_state":"validated",
      "booked_persons_number":2,
      "present_persons_number":2,
      "cancel_actor":null,
      "cancel_reason":null,
      "booking_type":"restaurant",
      "note":null,
      "period":"dinner",
      "booking_date":"2014-09-05",
      "booking_time":"2014-09-05T20:00:00+02:00",
      "email":"nelle@heller.uk",
      "firstname":"Mazie",
      "lastname":"Hegmann",

      "contact_id":622360,
      "restaurant_id" => 479
    },
    {...},
    ...
  ]
}

Guestonline Api provides a way to retrieve a restaurant list of bookings with severals arguments.
All these parameters can be used to refine your search.

Arguments

Parameter Status Description
restaurant_id Dependant This parameter is optional if your token manages a single restaurant. In case your token manages more than one restaurant, you must provide it.
period Optional period of booking
booking_state Optional booking state of booking
booking_date Optional booking date of booking
created_at Optional return all bookings created since param format / (YYYY-MM-DD HH:MM:SS +0200)
updated_since Optional return all bookings which have been updated since param format / (YYYY-MM-DD HH:MM:SS +0200)

Retrieve an existing booking

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/bookings/577988"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" 

JSON RESPONSE :

{
  "object":"booking",
  "id":577988,
  "booking_state":"validated",
  "booked_persons_number":2,
  "present_persons_number":2,
  "cancel_actor":null,
  "cancel_reason":null,
  "booking_type":"restaurant",
  "note":null,
  "period":"dinner",
  "booking_date":"2014-09-05",
  "booking_time":"2014-09-05T20:00:00+02:00",
  "email":"nelle@heller.uk",
  "firstname":"Mazie",
  "lastname":"Hegmann",
  "contact_id":622360,
  "restaurant_id" => 479
}

You can also retrieve a specific booking from our id.

Arguments

Arguments Status Description
id Mandatory booking id

Returns

Returns the booking object.

Creating a new booking with contact id

EXAMPLE REQUEST :

  $ curl -X POST "http://api.guestonline.fr/v1/bookings"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "booking[note]=my booking from api" \
  -d "booking[booking_time]=2014-11-06T20:00:00+02:00" \
  -d "booking[booking_date]=2014-11-06" \
  -d "booking[booked_persons_number]=15" \
  -d "booking[contact_id]=622360" \
  -d "booking[send_reminders]=true" \
  -d "booking[user_locale]=fr" \
  -d "booking[restaurant_id]=479"

JSON RESPONSE :

{
  "object":"booking",
  "id":577989,
  "booking_state":"initialized",
  "booked_persons_number":15,
  "present_persons_number":15,
  "cancel_actor":null,
  "cancel_reason":null,
  "booking_type":"restaurant",
  "note":"my booking from api",
  "period":"dinner",
  "booking_date":"2014-11-06",
  "booking_time":"2014-11-06T20:00:00+01:00",
  "email":"nelle@heller.uk",
  "firstname":"Mazie",
  "lastname":"Hegmann",
  "contact_id":622360,
  "restaurant_id": 479
}

All arguments define in booking parameter.

Arguments

Arguments Status Description
booking[booking_date] Mandatory booking date
booking[booking_time] Mandatory booking time
booking[booked_persons_number] Mandatory booked persons number
booking[contact_id] Mandatory id of booking contact
booking[restaurant_id] Dependant id of the restaurant which is attached to the booking
booking[send_reminders] Optional send booking reminders
booking[user_locale] Optional booking user locale
booking[note] Optional booking note

Returns

Returns the booking object.

Creating a new booking with new contact

EXAMPLE REQUEST :

  $ curl -X POST "http://api.guestonline.fr/v1/bookings"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "booking[note]=my booking from api" \
  -d "booking[booking_time]=2014-11-06T20:00:00+02:00" \
  -d "booking[booking_date]=2014-11-06" \
  -d "booking[booked_persons_number]=15" \
  -d "booking[send_reminders]=true" \
  -d "booking[user_locale]=fr" \
  -d "booking[restaurant_id]=479" \
  -d "booking[contact][lastname]=GuestOnline" \
  -d "booking[contact][firstname]=Api" \
  -d "booking[contact][email]=api@guestonline.fr" \
  -d "booking[contact][mobile_phone]=33612233445" \
  -d "booking[contact][accept_email_spam]=true" \
  -d "booking[contact][accept_sms_spam]=true" \
  -d "booking[contact][country_code]=fr"

JSON RESPONSE :

{
  "object":"booking",
  "id":577990,
  "booking_state":"initialized",
  "booked_persons_number":15,
  "present_persons_number":15,
  "cancel_actor":null,
  "cancel_reason":null,
  "booking_type":"restaurant",
  "note":"my booking from api",
  "period":"dinner",
  "booking_date":"2014-11-06",
  "booking_time":"2014-11-06T20:00:00+01:00",
  "email":"api@guestonline.fr",
  "firstname":"Api",
  "lastname":"GuestOnline",
  "contact_id":622361,
  "restaurant_id": 479
}

All arguments define in booking parameter.

Arguments for booking

Arguments Status Description
booking[booking_time] Mandatory booking time
booking[booking_date] Mandatory booking date
booking[booked_persons_number] Mandatory number of persons for booking
booking[contact] Mandatory contact of booking
booking[restaurant_id] Dependant id of the restaurant which is attached to the booking
booking[note] Optional note of booking
booking[send_reminders] Optional send reminders of booking
booking[user_locale] Optional user locale of booking
You specify your new contact with following arguments:

Arguments for contact

Arguments Description Warning
contact[lastname] contact's lastname
contact[firstname] contact's firstname
contact[email] email of contact this parameter must have a valid email (example: "guestonline@api.fr")
contact[mobile_phone] mobile phone of contact this parameter must have a valid phone number (example: 33 6 12 23 34 45)
contact[accept_email_spam] true if contact accepts email campaigns
contact[accept_sms_spam] true if contact accepts sms campaigns
contact[country_code] contact's country code (example: "fr")

Returns

Returns the booking object.

Updating existing booking

EXAMPLE REQUEST :

  $ curl -X PUT "http://api.guestonline.fr/v1/bookings/577990"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "booking[booked_persons_number]=14" 

JSON RESPONSE :

{ 
  "object":"booking",
  "id":577990,
  "booking_state":"initialized",
  "booked_persons_number":14,
  "present_persons_number":15,
  "cancel_actor":null,
  "cancel_reason":null,
  "booking_type":"restaurant",
  "note":"my booking from api",
  "period":"dinner",
  "booking_date":"2014-11-06",
  "booking_time":"2014-11-06T20:00:00+01:00",
  "email":"api@guestonline.fr",
  "firstname":"Api",
  "lastname":"GuestOnline",
  "contact_id":622361,
  "restaurant_id": 479
}

You can update a specific booking with id.

Arguments

Arguments Status Description
id Mandatory The ID of the booking to be retrieved.
booking[upsale_items] Optional array of upsale item
booking[voucher_codes] Optional array of voucher codes to attach to the booking. Only valid codes will be added

Returns

Returns the booking object.

Cancel an existing booking

EXAMPLE REQUEST :

  $ curl -X PUT "http://api.guestonline.fr/v1/bookings/577990/cancel"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \ 

JSON RESPONSE :

{
  "object": "booking",
  "id": 577990,
  "booking_state": "canceled",
  "booked_persons_number": 14,
  "present_persons_number": 0,
  "cancel_actor": "restaurateur",
  "cancel_reason": "Bonjour,<br/>Nous sommes contraint d'annuler votre réservation et nous le regrettons.<br/>N'hésitez pas à réserver à une autre date.<br/>Nous sommes navrés de la gêne occasionnée.",
  "booking_type": "restaurant",
  "note": "my booking from api",
  "period": "no_service",
  "booking_date": "2014-11-06",
  "booking_time": "2014-11-06T20:00:00+01:00",
  "email": "api@guestonline.fr",
  "firstname": "Api",
  "lastname": "GuestOnline",
  "contact_id": 622361,
  "restaurant_id": 479
}

You can cancel a booking by specifying its id.

Arguments

Arguments Status Description
id Mandatory The ID of the booking to be canceled.

Returns

Returns the booking object.

Cancel an existing booking for a user

EXAMPLE REQUEST :

  $ curl -X PUT "http://api.guestonline.fr/v1/bookings/577990/user_cancel"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \ 
  -d "booking_token=the-booking-token" \
  -d "cancel_reason=i am sick"\

JSON RESPONSE :

{
  "object": "booking",
  "id": 577990,
  "booking_state": "canceled",
  "booked_persons_number": 14,
  "present_persons_number": 0,
  "cancel_actor": "client",
  "cancel_reason": "I am sick, sorry!",
  "booking_type": "website",
  "note": "my booking from api",
  "period": "no_service",
  "booking_date": "2014-11-06",
  "booking_time": "2014-11-06T20:00:00+01:00",
  "email": "api@guestonline.fr",
  "firstname": "Api",
  "lastname": "GuestOnline",
  "contact_id": 622361,
  "restaurant_id": 479
}

You can cancel a specific booking in place of the customer with id, and booking_token.

Arguments

Arguments Status Description
id Mandatory The ID of the booking to be canceled.
booking_token Mandatory The booking_token of the booking
cancel_reason Mandatory The reason to give to the restaurant

Returns

Returns the booking object.

Confirm an existing booking

EXAMPLE REQUEST :

  $ curl -X PUT "http://api.guestonline.fr/v1/bookings/577990/confirm"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \ 

JSON RESPONSE :

{
  "object": "booking",
  "id": 577990,
  "booking_state": "validated",
  "booked_persons_number": 14,
  "present_persons_number": 15,
  "cancel_actor": null,
  "cancel_reason": null,
  "booking_type": "restaurant",
  "note": "my booking from api",
  "period": "dinner",
  "booking_date": "2014-11-06",
  "booking_time": "2014-11-06T20:00:00+01:00",
  "email": "api@guestonline.fr",
  "firstname": "Api",
  "lastname": "GuestOnline",
  "contact_id": 622361,
  "restaurant_id": 479
}

You can confirm a booking by specifying its id.

Arguments

Arguments Status Description
id Mandatory booking ID

Returns

Returns the booking object.

honore an existing booking

EXAMPLE REQUEST :

  $ curl -X PUT "http://api.guestonline.fr/v1/bookings/577990/honore"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \ 

JSON RESPONSE :

{
  "object": "booking",
  "id": 577990,
  "booking_state": "honored",
  "booked_persons_number": 14,
  "present_persons_number": 14,
  "cancel_actor": null,
  "cancel_reason": null,
  "booking_type": "restaurant",
  "note": "my booking from api",
  "period": "dinner",
  "booking_date": "2014-11-06",
  "booking_time": "2014-11-06T20:00:00+01:00",
  "email": "api@guestonline.fr",
  "firstname": "Api",
  "lastname": "GuestOnline",
  "contact_id": 622361,
  "restaurant_id": 479
}

You can honor a booking by specifying its id.

Arguments

Arguments Status Description
id Mandatory ID of booking
present_persons_number Optional number of persons present. If not supplied, the booked_persons_number will be used

Returns

Returns the booking object.

fake an existing booking

EXAMPLE REQUEST :

  $ curl -X PUT "http://api.guestonline.fr/v1/bookings/577990/fake"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \ 

JSON RESPONSE :

{
  "object": "booking",
  "id": 577990,
  "booking_state": "fully_faked",
  "booked_persons_number": 14,
  "present_persons_number": 0,
  "cancel_actor": null,
  "cancel_reason": null,
  "booking_type": "restaurant",
  "note": "my booking from api",
  "period": "dinner",
  "booking_date": "2014-11-06",
  "booking_time": "2014-11-06T20:00:00+01:00",
  "email": "api@guestonline.fr",
  "firstname": "Api",
  "lastname": "GuestOnline",
  "contact_id": 622361,
  "restaurant_id": 479
}

You can specify that a specific booking is fully fake.

Arguments

Arguments Status Description
id Mandatory ID of booking

Returns

Returns the booking object.

Releasing the table

EXAMPLE REQUEST :

  $ curl -X PUT "http://api.guestonline.fr/v1/bookings/577990/release_table"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "booking_info[amount]=10000" 
  -d "booking_info[currency]=EUR" 

JSON RESPONSE :

{ 
  "object":"booking",
  "id":577990,
  "booking_state":"validated",
  "booked_persons_number":14,
  "present_persons_number":15,
  "cancel_actor":null,
  "cancel_reason":null,
  "booking_type":"restaurant",
  "note":"my booking from api",
  "period":"dinner",
  "booking_date":"2014-11-06",
  "booking_time":"2014-11-06T20:00:00+01:00",
  "email":"api@guestonline.fr",
  "firstname":"Api",
  "lastname":"GuestOnline",
  "contact_id":622361,
  "restaurant_id": 479,
  "booking_info": {
      "object": "booking_info",
      "amount": 10000,
      "currency": "EUR"
  }
}

You can add extra info to a booking when releasing its table.

Arguments

All properties of the Booking Info can be updated. They

Arguments Status Description
booking_info[amount] Mandatory The amount of the bill
booking_info[currency] Mandatory The currency of the bill
...

Returns

Returns the booking object with booking info expanded. The release table process is also triggered.

Invite friends

EXAMPLE REQUEST :

  $ curl -X PUT "http://api.guestonline.fr/v1/bookings/577990/invite_friends"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "emails[]=j.doe@example.com" 
  -d "emails[]=p.smith@example.com" 
  -d "message=See you there."

JSON RESPONSE :

{ 
  "object":"booking",
  "id":577990,
  "booking_state":"validated",
  "booked_persons_number":14,
  "present_persons_number":15,
  "cancel_actor":null,
  "cancel_reason":null,
  "booking_type":"restaurant",
  "note":"my booking from api",
  "period":"dinner",
  "booking_date":"2014-11-06",
  "booking_time":"2014-11-06T20:00:00+01:00",
  "email":"api@guestonline.fr",
  "firstname":"Api",
  "lastname":"GuestOnline",
  "contact_id":622361,
  "restaurant_id": 479,
  "booking_info": {
      "object": "booking_info",
      "amount": 10000,
      "currency": "EUR"
  }
}

Sends a message by email to given email addresses with booking information and specific message.

Arguments

Arguments Status Description
emails Mandatory Array of email addresses
message Mandatory Message to send

Returns

Returns the booking object.

Restaurants

The Restaurant object


JSON Example :

{
  "object": "restaurant",
  "id": 1,
  "name": "Wasabi",
  "address": "2, Av de lombez",
  "city": "Toulouse",
  "postcode": "31300",
  "phone": "335612555555",
  "country_code": "FR",
  "time_zone": "Europe/Paris",
  "capacity": 50,
  "created_at": "2014-02-11T07:54:08+01:00",
  "updated_at": "2014-11-24T09:11:23+01:00"
}
Key Type Description
id Int Restaurant id
name String Restaurant name
address String Restaurant address
city String Restaurant city
postcode String Restaurant post code
country String Restaurant country
phone String Restaurant phone
country_code String Restaurant country_code
time_zone String Restaurant timezone
created_at Datetime Restaurant creation datetime
update_at Datetime Last update

List managed restaurants

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/restaurants"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \

JSON RESPONSE :

{
    "object": "list",
    "total_count": 20,
    "num_pages": 2,
    "current_page": 1,
    "restaurants": [
      {
        "object": "restaurant",
        "id": 1,
        "name": "Wasabi",
        "address": "2, Av de lombez",
        "city": "Toulouse",
        "postcode": "31300",
        "phone": "335612555555",
        "country_code": "FR",
        "time_zone": "Europe/Paris",
        "capacity": 50,
        "created_at": "2014-02-11T07:54:08+01:00",
        "updated_at": "2014-11-24T09:11:23+01:00"
      },
      {...}
      ]
}

GuestOnline Api provides a way to retrieve the list of managed restaurant.

Arguments

No argument is required. Pagination is supported for this query.

Parameter Status Description
date Mandatory you must provide it .

List restaurants available for booking

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/restaurants/bookable"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "date=2015-01-27" \
  -d "persons_number=3" \
  -d "period=lunch" \
  -d "expands[]"="first_bookable_hours"

JSON RESPONSE :

{
    "object": "list",
    "total_count": 2,
    "num_pages": 1,
    "current_page": 1,
    "restaurants": [
      {
        "object": "restaurant",
        "id": 1,
        "first_bookable_hours": 
        [
          {
              "object": "hour",
              "time": "12:00"
          },
          {...},
          ...
        ]
      },
      {...}
      ]
}

GuestOnline Api provides a way to get the restaurants available for booking.

Arguments

Arguments Status Description
date Mandatory booking date
persons_number Mandatory number of people
restaurant_ids Optional Array of restaurant ids. Leave empty to check all authorized restaurants
period Optional booking period [lunch, afternoon, dinner...]
expands Optional This parameter is optional see Expanding

Returns

Returns a paginated list of restaurants available for this booking.

Areas

The Area object


JSON Example :

{
  "object": "area",
  "id": 1,
  "bookable_online": false,
  "translations": [
      {
          "object": "area_translation",
          "locale": "en",
          "name": "bar"
      }
  ]
}

An area is a logical group of tables in a restaurant. If a restaurant has at least 1 area, only the ones with the flag "bookable_online" set to true will be available for online booking.

Key Type Description
id Integer area id
bookable_online Boolean true if area bookable online
translations Array Array of translation

Area Translation Object

Key Type Description
locale String locale ISO code (fr, en, ...)
name String Name of the area

List areas with param

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/areas"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H"

JSON RESPONSE :

{
  "object": "list",
  "areas": [
    {
      "object": "area",
      "id": 1,
      "name": "terrace",
      "bookable_online": false,
      "translations": [
    {
          "object": "area_translation",
          "locale": "en",
          "name": "Terrace"
        },
    {
          "object": "area_translation",
          "locale": "fr",
          "name": "Terrasse"
    }
      ]
    },
    {
      "object": "area",
      "id": 2,
      "bookable_online": true,
      "translations": [
    {
          "object": "area_translation",
          "locale": "en",
          "name": "Inside"
        },
    {
          "object": "area_translation",
          "locale": "fr",
          "name": "Interieur"
    }
      ]
    }
  ]
}      

Guestonline Api provides a way to retrieve a restaurant list of areas with an optional argument.
This parameter can be used to refine your search.

Argument

Parameter Status Description
bookable_online optional optional boolean parameter which can be used to filter the list of areas in a restaurant

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/areas"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H"
  -d "bookable_online=true"

JSON RESPONSE :

{
  "object": "list",
  "areas": [
    {
      "object": "area",
      "id": 2,
      "bookable_online": true,
      "translations": [
    {
          "object": "area_translation",
          "locale": "en",
          "name": "Inside"
        },
    {
          "object": "area_translation",
          "locale": "fr",
          "name": "Interieur"
    }
      ]
    }
  ]
}      

RuntimeService

The runtime service object


JSON Example :

{
  "object": "runtime_service",
  "id": "54525943f5cb5c39aa000741",
  "left_seats": 47,
  "min_persons": 1,
  "max_persons": 25,
  "last_booking": "2014-11-27T10:00:00+02:00",
  "period": "lunch",
  "start_time": "12:00",
  "end_time": "14:00",
  "date": "2014-11-27",
  "restaurant_id": 479,
  "parent_id": "53f438c9f5cb5c1411000467",
  "table_availabilities": [
    {
        "object": "table_availability",
        "table_type": "1_16",
        "min": 1,
        "max": 16,
        "quantity": 1
    },
    {...}
  ]
}
Key Type Description
id Int runtime_service id
date Date date of this runtime_service
left_seats Int seats available for this runtime_service
closed Boolean true if service is closed
min_persons Int Minimum number of persons for online booking
max_persons Int Maximum number of persons for online booking
last_booking date time after which online booking is impossible
period String period of this runtime_service
start_time Date start time of this runtime_service
end_time Date end time of this runtime service
restaurant_id Int restaurant id
parent_id Int runtime_opening id
table_availabilities Array Array of TableAvailabilities (expanded on demand)

The Table Availability object


JSON Example :

{
    "object": "table_availability",
    "table_type": "1_16",
    "min": 1,
    "max": 16,
    "quantity": 1
}

TableAvailabilities are used to detail tables available per kind. It can be appended to RuntimeService object with the table_availabilities expand parameter

Key Type Description
table_type String type of table (mix max concatenation)
min Int min seats of the table
max Int max seats of the table
quantity Int number of tables left

List runtime_services with params

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/runtime_services"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "date=2014-11-27" \
  -d "periods[]=lunch" \
  -d "periods[]=dinner" \

JSON RESPONSE :

{
  "object": "list",
  "runtime_services": [
    {
      "object": "runtime_service",
      "id": "54525943f5cb5c39aa000741",
      "left_seats": 47,
      "min_persons": 1,
      "max_persons": 25,
      "last_booking": "2014-11-27T10:00:00+02:00",
      "start_time": "12:00",
      "end_time": "14:00",
      "date": "2014-11-27",
      "restaurant_id": 479,
      "parent_id": "53f438c9f5cb5c1411000467"
    },
    {....}
  ]
}

GuestOnline Api provides a way to retrieve list of runtime services.

Arguments

Parameter Status Description
date Mandatory you must provide it .
restaurant_id Optional id of restaurant
periods Optional use to filter a list of periods.

Modify left_seats of a existing runtime_services

EXAMPLE REQUEST :

  $ curl -X PUT "https://api.guestonline.fr/v1/runtime_services"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "date=2014-11-27" \
  -d "id=54525943f5cb5c39aa000741" \
  -d "left_seats=14" \

JSON RESPONSE :

{
  "object": "runtime_service",
  "id": "54525943f5cb5c39aa000741",
  "left_seats": 14,
  "start_time": "12:00",
  "end_time": "14:00",
  "date": "2014-11-27",
  "restaurant_id": 479,
  "parent_id": "53f438c9f5cb5c1411000467"
}

GuestOnline Api provides a way to change the number of available seats for a given runtime service.

Arguments

Arguments Status Description
date Mandatory service date
id Mandatory service id
left_seats Mandatory new left_seats number

Returns

Returns the modified runtime service object. ```

Close a runtime service

EXAMPLE REQUEST :

  $ curl -X PUT "https://api.guestonline.fr/v1/runtime_services/close"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "date=2014-11-27" \
  -d "id=54525943f5cb5c39aa000741" \

JSON RESPONSE :

{
  "object": "runtime_service",
  "id": "54525943f5cb5c39aa000741",
  "closed": true,
  "left_seats": 14,
  "start_time": "12:00",
  "end_time": "14:00",
  "date": "2014-11-27",
  "restaurant_id": 479,
  "parent_id": "53f438c9f5cb5c1411000467"
}

GuestOnline Api provides a way to close a runtime service, in order to prevent new bookings even if the seats are still available.

Arguments

Arguments Status Description
date Mandatory service date
id Mandatory service id

Returns

Returns the runtime service object. ```

Open a runtime service

EXAMPLE REQUEST :

  $ curl -X PUT "https://api.guestonline.fr/v1/runtime_services/open"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "date=2014-11-27" \
  -d "id=54525943f5cb5c39aa000741" \

JSON RESPONSE :

{
  "object": "runtime_service",
  "id": "54525943f5cb5c39aa000741",
  "closed": false,
  "left_seats": 14,
  "start_time": "12:00",
  "end_time": "14:00",
  "date": "2014-11-27",
  "restaurant_id": 479,
  "parent_id": "53f438c9f5cb5c1411000467"
}

GuestOnline Api provides a way to open a runtime service.

Arguments

Arguments Status Description
date Mandatory service date
id Mandatory service id

Returns

Returns the Runtime Service object.

Contacts

The contact object


JSON Example :

{
  "id":622359,
  "lastname":"Koch",
  "firstname":"Skyla",
  "email":"adolph@schamberger.us",
  "birthday":"1980-01-01",
  "gender":2,
  "fixed_phone":"33520506100",
  "mobile_phone":"33620506100",
  "address":"8 rue des restaurants",
  "extra_address":"allée des gastronomes",
  "postcode":"31000",
  "city":"TOULOUSE",
  "company":"TableOnline",
  "country":"France",
  "accept_email_spam":true,
  "accept_sms_spam":true,
  "note":"lactose",
  "warning":true,
  "country_code":"FR",
  "restaurant_id":479
}
Key Type Description
id Int id of contact
lastname String contact's lastname (maximum 50 characters)
firstname String contact's firstname (maximum 50 characters)
email String contact's email (maximum 300 characters)
birthday Date contact's birthday
gender Int contact's gender (1: male, 2: female)
fixed_phone String contact's fixed phone number (maximum 25 characters)
mobile_phone String contact's mobile phone number (maximum 25 characters)
address String contact's address (maximum 200 characters)
extra_address String contact's extra address (maximum 200 characters)
postcode String contact's postcode (maximum 5 characters)
city String contact's city (maximum 50 characters)
company String contact's company (maximum 100 characters)
country String contact's country (maximum 100 characters)
accept_email_spam Boolean true if contact accepts email campaigns
accept_sms_spam Boolean true if contact accepts sms campaigns
note String contact note (maximum 65535 characters)
warning Boolean contact warning (more details on note)
country_code String contact's country code (maximum 3 characters)
restaurant_id Int restaurant id for contact

List contacts with params

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/contacts"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H"

JSON RESPONSE :

{
  "object":"list",
  "total_count":624,
  "num_pages":16,
  "current_page":1,
  "contacts":
  [
    {
      "object":"contact",
      "id":622359,
      "lastname":"Koch",
      "firstname":"Skyla",
      "email":"adolph@schamberger.us",
      "birthday":"1980-01-01",
      "gender":2,
      "fixed_phone":"33520506100",
      "mobile_phone":"33620506100",
      "address":"8 rue des restaurants",
      "extra_address":"allée des gastronomes",
      "postcode":"31000",
      "city":"TOULOUSE",
      "company":"TableOnline",
      "country":"France",
      "accept_email_spam":true,
      "accept_sms_spam":true,
      "note":"lactose",
      "warning":true,
      "country_code":"FR",
      "restaurant_id":479
    },
    {...},
    ...
  ]
}

Guestonline Api provides a way to retrieve a restaurant list of contacts with severals arguments.
All these parameters can be used to refine your search.

Arguments

Parameter Status Description
restaurant_id Dependant This parameter is optional if your token manages a single restaurant. In case your token can manage more than one restaurant, you must provide it .
email Optional email address
mobile_phone Optional mobile phone
lastname Optional lastname of contact

Retrieve an existing contact

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/contacts/622359"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" 

JSON RESPONSE :

{
  "object":"contact",
  "id":622359,
  "lastname":"Koch",
  "firstname":"Skyla",
  "email":"adolph@schamberger.us",
  "birthday":"1980-01-01",
  "gender":2,
  "fixed_phone":"33520506100",
  "mobile_phone":"33620506100",
  "address":"8 rue des restaurants",
  "extra_address":"allée des gastronomes",
  "postcode":"31000",
  "city":"TOULOUSE",
  "company":"TableOnline",
  "country":"France",
  "accept_email_spam":true,
  "accept_sms_spam":true,
  "note":"lactose",
  "warning":true,
  "country_code":"FR",
  "restaurant_id":479
}

You can also retrieve a specific contact.

Arguments

Arguments Status Description
id Mandatory contact ID.

Returns

Returns the Contact object.

Creating a new contact

EXAMPLE REQUEST :

  $ curl -X POST "http://api.guestonline.fr/v1/contacts"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "contact[lastname]=Cabarrou"

JSON RESPONSE :

{ 
  "object":"contact",
  "id":622356,
  "lastname":"Cabarrou",
  "firstname":null,
  "email":null,
  "birthday":null,
  "gender":null,
  "fixed_phone":null,
  "mobile_phone":null,
  "address":null,
  "extra_address":null,
  "postcode":null,
  "city":null,
  "company":null,
  "country":null,
  "accept_email_spam":false,
  "accept_sms_spam":false,
  "note":null,
  "warning":false,
  "country_code":"FR",
  "restaurant_id":479
}

All arguments related to Contact object.

Arguments

Arguments Status Description Warning
contact[lastname] Mandatory contact's lastname is mandatory
contact[firstname] Optional contact's firstname
contact[email] Optional contact's email address must be valid (ex: "guestonline@api.fr")
contact[birthday] Optional birthday of contact
contact[gender] Optional gender of contact
contact[fixed_phone] Optional contact's landline number must be valid (ex: 33 5 12 23 34 45)
contact[mobile_phone] Optional contact's mobile phone must be valid (ex: 33 6 12 23 34 45)
contact[address] Optional contact's address
contact[extra_address] Optional contact's extra address
contact[postcode] Optional contact's postcode
contact[city] Optional contact's city
contact[company] Optional contact's company
contact[country] Optional contact's country
contact[accept_email_spam] Dependant defined if contact accepts email campaigns from guestonline to set this paramater, you need to provide a valid email
contact[accept_sms_spam] Dependant defined if contact accepts SMS campaigns from guestonline to set this paramater, you need to provide a valid mobile phone
contact[note] Optional contact note
contact[warning] Optional contact warning
contact[country_code] Optional contact's country code
contact[restaurant_id] Dependant id of the restaurant which is attached to the contact this parameter is mandatory if your token manages more than one restaurant

Returns

Returns the Contact object.

Updating existing contact

EXAMPLE REQUEST :

  $ curl -X PUT "http://api.guestonline.fr/v1/contacts/622356"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H" \
  -d "contact[firstname]=Magalie"

JSON RESPONSE :

{ 
  "object":"contact",
  "id":622356,
  "lastname":"Cabarrou",
  "firstname":"Magalie",
  "email":null,
  "birthday":null,
  "gender":null,
  "fixed_phone":null,
  "mobile_phone":null,
  "address":null,
  "extra_address":null,
  "postcode":null,
  "city":null,
  "company":null,
  "country":null,
  "accept_email_spam":false,
  "accept_sms_spam":false,
  "note":null,
  "warning":false,
  "country_code":"FR",
  "restaurant_id":479
}

You can update any attribute of a contact.

Arguments Status Description
contact[lastname] Optional contact's lastname

Returns

Returns the Contact object.

Opinions

The opinion object

JSON Example :


"opinions": [
    {
        "object": "opinion",
        "id": "54a3b2c7c29387595a00003b",
        "opinion_items": [
            {
                "object": "opinion_item",
                "kind": "rate",
                "key": "atmosphere",
                "value": "1"
            },
            ...
        ],
        "booking": {
            "object": "booking",
            "id": 654636,
            "booking_state": "validated",
            "booking_date": "2014-10-31",
            "booking_time": "2014-10-31T20:00:00+01:00"
        },
        "contact": {
            "object": "contact",
            "lastname": "Kreiger",
            "firstname": "Quinn"
        }
    }
]

Key Type Description
id Int id of opinion
booking booking a simplified instance booking
contact contact a simplified instance contact
opinion_items Array array of opinion items

Booking Object

Key Type Description
id Int id of opinion
booking_state String booking state
booking_date Date booking date
booking_time DateTime booking time

Contact Object

Key Type Description
lastname String contact's lastname
firstname String contact's firstname

Opinion Item Object

Key Type Description
kind String rate or text
key String defines the category that requires a scoring
value String score or comment

List opinions with params

EXAMPLE REQUEST :

  $ curl -X GET "http://api.guestonline.fr/v1/opinions" \
  -H "X-Token: S8zUPVsQ3ouL6WzUV87V"
  -d "updated_at=2014-12-31"

JSON RESPONSE :

{
    "object": "list",
    "total_count": 1,
    "num_pages": 1,
    "current_page": 1,
    "opinions": [
        {
            "object": "opinion",
            "id": "54a3b2c7c29387595a00003b",
            "opinion_items": [
                {
                    "object": "opinion_item",
                    "kind": "rate",
                    "key": "atmosphere",
                    "value": "1"
                },
                ...
            ],
            "booking": {
                "object": "booking",
                "id": 654636,
                "booking_state": "validated",
                "booking_date": "2014-10-31",
                "booking_time": "2014-10-31T20:00:00+01:00"
            },
            "contact": {
                "object": "contact",
                "lastname": "Kreiger",
                "firstname": "Quinn"
            }
        }
    ]
}

Guestonline Api provides a way to retrieve a paginated list of opinions.

Arguments

Parameter Status Type Description
updated_at Optional Date it allows to retrieve opinions since this date.
restaurant_id Optional Int In case your token can manage more than one restaurant, this allows you to filter a specific restaurant. By default all commercials of your managed restaurants will be listed.

Table Occupation


Represents tables associated to a Booking.

The Table Occupation object

JSON Example :

  {
    "object":"table_occupation",
    "start_time": "2018-09-29T19:30:00+02:00",
    "end_time": "2018-09-29T21:30:00+02:00",
    "status": "busy",
    "table_names": "11, 12",
    "frozen": true
  }
key Type Description
start_time Datetime booking time
end_time Datetime realease time
status String table occupation status [ busy, still, occupied, free, released ]
table_names String Names of the tables used
frozen Boolean true if the tables cannot be changed

Booking Info


Extra data can be attached to a booking. These are stored in the BookingInfo element.

Pagination Arguments

JSON RESPONSE :

  {
    "object":"booking_info",
    "amount":10000,
    "currency":"EUR",
  }
key Type Description
amount Int Bill amount in cents
currency String 3 letter ISO code for currency

Upsale Item

Represent a item ordered or purchased with the booking

JSON RESPONSE :

  {
    "object": "upsale_item",
    "title": "Birthday cake",
    "quantity": 2,
    "price": 2600,
    "currency": "EUR"
  }
key Type Description
title String description of the item
quantity Int quantity ordered
amount Int unit price in cents
currency String 3 letter ISO code for currency

Voucher

Guestonline handles two kind of vouchers Warrant or Gift

Warrant Voucher

Warrant voucher represents a set of goods that the customer will enjoy whitin the booking

JSON RESPONSE :

{
    "object": "warrant_voucher",
    "name": "Chef Selection : 7 courses",
    "description": "7 Courses<br>...",
    "voucher_type": "<voucher_partner>",
    "status": "used",
}
key Type Description
name String name of the voucher
description String description of the voucher
status string status of the voucher depends on partner (used, valid, pending, expired, ...)
currency String 3 letter ISO code for currency

Gift Voucher

Gift voucher represents a amount of money that the customer can use within the booking

JSON RESPONSE :

{
    "object": "gift_voucher",
    "voucher_type": "<voucher_partner>",
    "amount": 200.0,
    "status": "valid",
    "currency", "eur"
}
key Type Description
name String name of the voucher can be blank
description String description of the voucher can be blank
status string status of the voucher depends on partner (valid, used)
amount Int total price of the gift
currency String 3 letter ISO code for currency

Commercials

The commercial object

JSON Example :

  {
    "object": "offer",
    "id": 162,
    "name": "a name",
    "description": "My commercial",
    "start_date": "2014-11-05",
    "end_date": "2014-11-05",
    "permanent": false,
    "bookable": false,
    "minimum_dishes": 1,
    "maximum_dishes": null,
    "restaurant_id": 479,
    "translations": [
      {
        "object": "commercial_translation",
        "locale": "fr",
        "name": "Happy Hour",
        "description": "Free glass of white wine with your meal"
      },
      {
        "object": "commercial_translation",
        "locale": "en",
        "name": "Happy Hour",
        "description": "Free glass of white wine with your meal"
      }
     ],
    "commercial_recurrencies": [
      {
        "object": "commercial_recurrency",
        "week_day": 4,
        "month_week": 0,
        "start_hour": "19:00",
        "end_hour": "20:30"
      }
  }
Key Type Description
id Int commercial id
object String type in [offer, event, menu]
name String name of commercial
description Text description of commercial
permanent Boolean permanent of commercial
start_date Date start date of commercial
end_date Date end date of commercial
bookable Boolean bookable of commercial
minimum_dishes Int minimum dishes required for this
maximum_dishes Int maximum dishes required for this
restaurant_id Int restaurant id
has_prepayment Boolean True if prepayment is requested for this commercial
translations Array Array of translation
commercial_recurrencies Array Array of Commercial Recurrency

Commercial translation Object

Key Type Description
locale String locale ISO code (fr, en, ...)
name String Name of the commercial
description String Description of the commercial

Commercial Recurrency Object

Key Type Description
week_day Int day of the week
month_week Int week in the month 0 -> 5 0 means every week
start_hour String start hour in the restaurant timezone (format 19:00)
end_hour String end hour in the restaurant timezone (format 19:00)

Retrieve an existing commercial

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/commercials/162"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H"

JSON RESPONSE :

{
  "object": "offer",
  "id": 162,
  "name": "a name",
  "description": "My commercial",
  "start_date": "2014-11-05",
  "end_date": "2014-11-05",
  "permanent": false,
  "bookable": false,
  "minimum_dishes": 1,
  "maximum_dishes": null,
  "restaurant_id": 479
}

GuestOnline Api provides a way to retrieve one commercial.

Arguments

Parameter Status Description
restaurant_id Dependant This parameter is optional if your token manages a single restaurant. In case your token can manage more than one restaurant, you must provide it .

List commercials with params

EXAMPLE REQUEST :

  $ curl -X GET "https://api.guestonline.fr/v1/commercials"  \
  -H "X-Token: 8xyDktY8QoUdHPVm3Z7H"
  -d "date=2014-11-05"
  -d "permanent=false"

JSON RESPONSE :

{
  "object": "list",
  "total_count":2,
  "num_pages":1,
  "current_page":1,
  "commercials": 
    [
      {
        "object": "offer",
        "id": 162,
        "name": "a name",
        "description": "My commercial",
        "start_date": "2014-11-05",
        "end_date": "2014-11-05",
        "permanent": false,
        "bookable": false,
        "minimum_dishes": 1,
        "maximum_dishes": null,
        "restaurant_id": 479,
        "translations": [
          {
            "object": "commercial_translation",
            "locale": "fr",
            "name": "Happy Hour",
            "description": "Free glass of white wine with your meal"
          },
          {
            "object": "commercial_translation",
            "locale": "en",
            "name": "Happy Hour",
            "description": "Free glass of white wine with your meal"
          }
         ],
        "commercial_recurrencies": [
          {
            "object": "commercial_recurrency",
            "week_day": 4,
            "month_week": 0,
            "start_hour": "19:00",
            "end_hour": "20:30"
          }
      ]
      },
      {...},
      ...
    ]
}

GuestOnline Api provides a way to retrieve a paginated list of commercials.

Arguments

Parameter Status Type Description
permanent Optional Bool Commercial#permanent field filter
date Optional Date if set, limit the search to Commercials available on given date
restaurant_id Optional Int In case your token can manage more than one restaurant, this allows you to filter a specific restaurant. By default all commercials of your managed restaurants will be listed