Quick Start

Last updated: October 30th, 2019


“Octorate APIs” are designed to let your application create room/rates and accommodations on Octorate and fill the content for these properties.
Is made up of REST calls, and our API follow resource-oriented URLS, accept query params, and always return JSON encoded response.
It uses standard HTTP verbs on these resource like “POST” / “GET” / “PATCH” / “GET”, and so on to understand what you’re attempting to do with these resources, and replies with usually acknowledged HTTP response code, like 404 for missing resources or 200 for successfully processed content.
Following information are described using RFC 2119 microformats like MUST, MAY, SHALL, SHALL NOT, MUST NOT, so please pay attention to these terms.

Schemas and Api calls + Fast development

Small tip: If you are using postman, import this url inside Postman:

You will have the set of Octorate calls already written and you can use the Postman generated code sample to speed up the development.

Octorate supports OPENAPI (v3) format.
What does it means?
You can use our internal swagger or use your custom OpenApi generator, starting from our json that describes the API that are currently operating inside octorate.
This Json is generated dynamically everytime octorate changes, so the most update version and description of each items is reacheable through our components documentation.


First of all ensure that:

  • - You've already configured or given to octorate your OAuth redirect url (see OAuth flow)
  • - You have the "secret key" (api key) if you're using an api key based authentication and also the "public key" if you're using the oauth flow
Octorate can have any type of users interacting with the platform. These kind of users are the Affiliate, the Api Member and the User.
To be able to interact with Octorate at least the Api Member and the User are required.
Tip: You can create with your Api a new accommodation, an email with a new user will be sent to the address of the property
Tip: We suggest also to this flow, because, if your api access is marked as "Sandbox" use, this kind of requests MAY generate some mockup data

You can start with a fake property inside our application: https://api.octorate.com/connect/rest/v1
Then when you are ready to set all in production, let us know, we'll do a short certification process and we'll mark your account as production ready


-> This argument in depth <-

Quota limits

The system allows you to make 100 calls for each accommodation, in 5 minutes, so it’s RACCOMENDED to optimize the calls and prepare to the eventually that Octorate would not honor this request after.

OAuth Flow And Token based authentication

How Login works?

Our suggested authentication and authorization method is a token as OAuth.

OAuth protocol is defined by the RFC 6749 and it's a common way to obtain authorization to a resource.

Inside our APIs there are two kind of resources that you will be allowed to access
- Api Operations: For instance create a new accommodation or retrieve api configuration details
- Accommodations: And by inheritance rooms, reservations and the other related resources.

For the former, we only ask you to login inside our system. That can be done calling the api "apiLogin". For instance here is an example of the curl that you might need to call.
curl --request POST 'https://{{enviroment}}/octobook/rest/identity/apilogin' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id={{yourclient}}' \ --data-urlencode 'client_secret={{theSecretKey}}' Executing this code you will get in the json response an access_token that can be used for an hour to execute requested that not depends on access to any resource. For instance, try to create an accommodation

For the latter instead. the OAuth authorization step is necessary because you need to access to a new resource where likely you still don't the permission to handle.
In that case, the actors will be the Identity Provider (here Octorate), the client (you), the Resource Server (still Octorate) and the user.

The steps will be these:

  1. Since you don't have the permission to access the required resource you bring the user (redirect) in Octorate in https://{{enviroment}}/octobook/identity/oauth.xhtml?client_id={{your_client_id}}&redirect_uri={{https://your_redirect_uri.com}}&state={{something crypt to verify}}
  2. The user then will be asked to log in, establish a session inside octorate, and grant on Octorate the grants required on all the accommodations he is able to see.
  3. Octorate redirects the user to the redirect uri, giving you in the get params the one shot "code", that can be used to retrieve two special tokens:
    The refresh and the access token.
  4. You call Octorate Identity Repository to retrieve these tokens. Request: curl --location --request POST 'https://{{enviroment}}/octobook/rest/identity/token' \ --data-urlencode 'client_secret={{yoursecret}}' \ --data-urlencode 'client_id={{clientid}}' \ --data-urlencode 'redirect_uri={{https://your_redirect_uri.com}}' \ --data-urlencode 'grant_type=code' \ --data-urlencode 'code={{code provided}} Response: { "access_token":"token", "refresh_token":"myrefreshtoken", "expireDate": "2020-03-17T17:41:51.178Z" }
  5. The refresh token is given only the first time (so you need to have a code to retrieve the refresh token).
    Store it in your repository with your user or the same resources to be able to retrieve the access token again. Here we are, you can access your resource until the expireDate is over with the access token.
    This is the header you will need to always add to your calls. HTTP HEADER: “Authorization”: “Bearer {{access_token}}
  6. Great! You've accessed the resource. If the token expires you can still call the /identity/refresh endpoint to retrieve another access token. The refresh token doesn't expire.

Some useful information

  • If the user already agreed to give you the permission to access a resource, just call the identity provider url, and octobook will call immediately your callback, without reasking the grant to the user
  • You need to configure the redirect url with us, this url have to be whitelisted.
  • If you think your system has been hacked, contact us immediately, we can revoke immediately a list of resources or all the resources before the token expires, and let you ask the user new tokens.
  • Use of TLS (https) connection is mandatory, you should be able to expose a secure callback (redirect) url

Api Key Users(Api activated before 2020-03-17, XML Format to JSON Migration)

In order to process request we the new API, you should follow the previously mentioned method.
Contact us to get the new credentials, after you can obtain the token for your properties using the Identity->migrateApiKey method.

Be Safe! Don't share these credentials

Take care that this keys allows you or another user to access the Octorate data of your customers. Keep this key secret and you MUST NOT insert these keys in your frontend or in pages that the hackers may inspect. If you suspect that your system could have been compromised, contact us immediately, we can generate a new key for you.

Main entities

Name of the entity Description
Accommodation Physically for Octorate it represents a set of rooms localed in a specific place, locally also a generic container for rooms. You will find it as "Root ot Network" if just a reference of many other properties or as Accommodation if the former case.
Product Internally also know as Room In the most high level, It represents the basic typology of a room, or a category of a room. An example could be "The double rooms" or "4 pax dormitory". If it possible to create children product that represents different configuration of the first one. In the first case you could have the "Not refundable Double Room" that has a the same availability of the parent and a fixed 5% discount of the price
Portal It represent the service that we want to use, for instance "Airbnb"
Portal Connection When we link an accommodation to a Portal we'have configured a new Portal Connection

Accommodation & Products

How Property networks works?

The most basic entities you will find inside Octorate are the Products and the Accommodations.
A products (in the image in Blue) MAY have children in order to form a Rate or a special configuration.
An accommodation (in the image in Orange) MAY have children in order to create an “access network”.
An access network is a container for many properties where a property is entitled to see all the others. So you may have for instance a “California Rentals” container of “Palo Alto Apartment” and “L.A. Apartment”.
Only one level is possible for Accommodations. Instead many levels are possible for Products. Here's a more detailed example of how the properties can we configured in octorate How Property networks works (Detail)?

Access to Properties

Keep in mind that you're allowed to access only to the properties that have your ApiKey configured. Keep in mind also that you are NOT allowed to make modifications on existing network but only create new ones.

Portal & Portal Connections

When an accommodation sign in inside Octorate, it will have the possibility to setup different connections to many providers (Like Booking.com, Airbnb, Homeaway but also external services like keyless access,etc..).
Every accommodation MUST have his Portal Connection to be connected to a Portal that means that if you're following a multiaccount configuration, and your trying to link one external id to many different "octorate accommodations" (this configuration is available and could be used to give different level of access to different users), you will have to send the same configurations for each portal.

Multiaccount configurations

Homeaway, for instance, is a PortalConnection that due to his commercial requirements, often needs to have a lot of properties that are configured with our multiaccount structure. You will have to create then many accommodations, link them to the same network and push the same configuration or small changes in each accommodation

Content Entities

Specific field description for each item are available in our Components section under schemas section.
Accommodation Information send to portals regarding the accommodation configuration like who's in charge to invoice
Listing Information send to portals regarding a previously descripted Product
Reservation It's the configuration of a product regarding the settings of a reservation (The portal, not Octorate)
Pricing How the portal calculate the prices. (The portal, not Octorate)
Availability The information about the availability of that product
RateContent The information and the restrictions about these rate. (Applied to the portal, not in Octorate)
Fee A fee that's applied when booking the reservation
Service Service that could be applied to accommodation

Product configuration

Supported by Booking.com, Homeaway, Airbnb.com How Property networks works? *UML of the classes involved in json configuration. Readonly fields have a orange background color
Product information are retrieved on user request by the portal and wrote inside a Json that's configured the way described upper. You will not have necessary to fill all the items inside Octorate to push to a portal, and every portals has it owns configuration. If you don't already have a deep knowledge of the fields required for each portal we suggest you to push everything and check then if your content is pushable calling the push API.
See also our showcases to check how the push for each portal is done and what's required to send the content.

Typically the portals that maps each room with a lot informations, like Airbnb.com doesn't, doesn't require to send also Property Configuration. Instead portals like Booking.com that has little content inside rooms and a for instance a common description for all the hotel, needs to be configured also at property level.
The normal flow in that case would be:
  1. Create the property
  2. Connect the property to the portal *The connection on the Portal MUST exists
  3. Ask user to authenticate
  4. Fill all the content of the property using our API
  5. Send them through the API to the portal

Property configuration

Supported by Booking.com, Homeaway How Property networks works? *UML of the classes involved in json configuration. Readonly fields have a orange background color

Some portals prefer to have a common configuration that's applied to every room and only some specific information are configured on the room
In that case you will have to:

  1. Create a property / Or a network of properties
  2. Create a connection on every accommodation
  3. Ask user to authenticate if already existing.
  4. Fill all the content of the property using our API
  5. Send them through the API to portal

To remember:

- Since some portals requires approval, sending content doesn't means that is immediately visibile on their extranet. Further actions (i.e. commercial agreement between customer and portal) may be required also to get the listing online
- You can use this API to create a new connection (if the portal supports it)