ORBITAL API

Introduction

The Orbital Platforms API is based on JSON. It currently provides endpoints for authentication, fetching apartment type, rate plans mappings and updating rates, inventory and availability.

The API is IP restricted so please make sure you have contacted us with your IP to whitelist them before trying to make any calls.

The root url of the api is https://api.orbitalplatforms.com

Please send the Content-Type header when making your requests or the request will not be valid. The API currently only supports content type application/json.

HTTP

Authentication

All requests to the Orbital Platforms API require authentication via the OAuth 2 protocol https://oauth.net/2/. The only grant type allowed is client_credentials and issued tokens have a validity of 3600 seconds (1 hour).

To obtain an access_token make a POST request to the /authentication endpoint supplying the credentials we have provided you with, in the request body:

If the credentials are correct, the response from the API will include a new access token you can use for the next hour.

Please cache this token and use in subsequent requests until it expires. Once expired make another request to obtain a new short lived token.

To use the token to authenticate with the API submit it in the Authorization header of your request as a bearer token.

Example Bearer Token Header:

Authorization: Bearer 5150b644bed890eb1a125d17336de9e3acb9fad4

Example Authentication Request

POST /authentication HTTP/1.1
Host: api.orbitalplatforms.com
Content-Type: application/json

{
    "client_id": "tZnfa51q2bz7E7e1Zb1DYl1K6scg61",
    "client_secret": "Lb4qJcfB6RS7TzYoE0$O01k8@EGuri",
    "grant_type": "client_credentials"
}

Example Authentication Response

{
    "access_token": "baed9de2888abe0ce5dac0b7d9b83323b3997b8f",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": null
}

Example PHP Request

                                    test

Endpoints

Our API endpoints provide external applications access to our content.

OTA

The OTA group of endpoints provides 2 JSON RPC calls that allow external applications like channel managers to connect to us.

All requests needs to include besides the OAuth token (which gives access to the API), the property level credentials which give access to the data of a specific property.

These credentials will be provided to the property partner when setting up the connection.

Example Auth Snippet

"auth": {
    "propertyId":"337",
    "username": "95ee803959d8d98f26efbb1c2f9b07db",
    "password": "d909ccc277b58bad788bc938b325849c"
}

Mappings

This endpoint allows clients to obtain apartment types with rate plans mappings for a single property to be used for channel managers mappings.

In our system each property can have up to 13 different apartment types identified by a type code. Each of the apartment type can have a customised label that will be sent back with each request.

The property id has to be passed as a query parameter named propertyId

This call will return a list of mappings of apartment types and rate plans for that property

Possible apartment types values are :

studioApartment
1BedroomApartment
2BedroomApartment
3BedroomApartment
4BedroomApartment
otherApartment
otherApartment2
otherApartment3
otherApartment4
otherApartment5
otherApartment6
otherApartment7
otherApartment8

The value of apartment type is unique inside a property so it can be used to identify a certain apartment for a property.

Each apartment can have multiple rate plans but a rate plan will only belong to one apartment type.

Each rate plans has a label associated with it describing the contents.

Example Mappings Request

POST /v1/external/ota/mappings HTTP/1.1
Host: api.orbitalplatforms.com
Authorization: Bearer ee203ebddc94bc3f13f4eb5fb51b11e24b65318e
Content-Type: application/json

{
   "auth": {
     "propertyId":"337",
     "username": "95ee803959d8d98f26efbb1c2f9b07db",
     "password": "d909ccc277b58bad788bc938b325849c"
   }
}

Example Mappings Response

[
    {
        "apartment": {
            "type": "studioApartment",
            "label": "Studio Apartment",
            "ratePlans": [
                {
                    "id": "2806",
                    "label": "Internet Rate"
                }
            ]
        }
    },
    {
        "apartment": {
            "type": "1BedroomApartment",
            "label": "1 Bedroom Apartment",
            "ratePlans": [
                {
                    "id": "2912",
                    "label": "Other Rate Plan Test"
                }
            ]
        }
    }
]

Inventory

This endpoint allows external applications to update availability, rates and restrictions for a single property.

To be more efficient the inventory request allows clients to update availability, rates and restrictions in batch. Each of the components are optional so a request could only update restrictions or rates for example. Allocations will not show on the extranet until all 3 of the updates have been provided though.

Each of the individual components (availability, rates, restrictions) allows for batched updates so multiple apartment types and rate plan ids can be updated in a single request, but only one property can be updated at a time.

The dates should always be sent in the format YYYY-mm-dd (Year - Month - Day).

Availability updates allow the clients to set availability restrictions for the specified date range.

The client can provide the quantity of rooms available during the date period (quantity field) or the general stop sell flag (isAvailable).

If isAvailable is set to false the room will not be available for the date range even if the quantity is more than 0. In the same way if the quantity is 0 and the room is set to isAvailable=true the room is not available. Both conditions need to be met for the room to be available: quantity > 0 && isAvailable=true

Rates updates allow the clients to set the price of the room for a specific period.

Please note that the rates should be sent to us in minor units e.g. £150 = 15000 minor units.

Restrictions updates allow the clients to apply restrictions on the rooms for a period of time.

The restrictions we can apply are minimum stay (how many nights must a guest stay if they were to check in during that day), if check in is allowed during that day or if check out is allowed during that day.

If all the updates are successful the system will reply with a success message. If not, none of the updates are going to be applied.

Example Inventory Request

POST /v1/external/ota/inventory HTTP/1.1
Host: api.orbitalplatforms.com
Authorization: Bearer 1f450eb31764a6da4dd85136a577c26a1f6ba093
Content-Type: application/json

{
   "auth": {
     "propertyId":"337",
     "username": "95ee803959d8d98f26efbb1c2f9b07db",
     "password": "d909ccc277b58bad788bc938b325849c"
   },
   "availability":[
      {
         "dates":{
            "from":"2017-07-07",
            "to":"2017-07-10"
         },
         "apartmentType":"studioApartment",
         "ratePlanId":"56789",
         "quantity":3,
         "isAvailable":true
      }
   ],
   "rates":[
      {
         "dates":{
            "from":"2017-07-07",
            "to":"2017-07-10"
         },
         "apartmentType":"studioApartment",
         "ratePlanId":"56789",
         "rate":15000
      }
   ],
   "restrictions":[
      {
         "dates":{
            "from":"2017-07-07",
            "to":"2017-07-10"
         },
         "apartmentType":"studioApartment",
         "ratePlanId":"56789",
         "minimumStay":2,
         "isCheckInAllowed":true,
         "isCheckOutAllowed":true
      }
   ]
}

Example Inventory Response

{
    "success": true
}

RPC

The RPC group of endpoints provides JSON RPC access to some of the content of Habicus Group that does not fit in a REST context.

Destinations

This endpoint allows external applications to search for destinations in our system. These destinations can be used to send enquiries.

A normal use case would be to use this RPC call with AJAX to generate an autocomplete field in your form.

Accepted Parameters

Parameter	Description	Required
query	Partial or complete name of the destination Example: query=Bar will return Spain - Barcelona	Yes

Example Destinations Request

GET /v1/external/rpc/destinations?query=Chis HTTP/1.1
Host: api.orbitalplatforms.com
Authorization: Bearer a0bafb591538f001125e6e35e068c18eedfe0d08
Content-Type: application/json

Example Destinations Response

{
    "query": "Chis",
    "results": [
        "United Kingdom - London - Chiswick",
        "United Kingdom - Edinburgh - Merchiston"
    ]
}

REST

The REST group of endpoints provides JSON REST access to the content of Habicus Group. This API is not available to the general public so please get in touch if you would like to integrate with us at a content level

Enquiry

This endpoint allows external applications to create enquiries in our system.

Enquiry Object Model

Attribute	Type	Description	Required
title	string	One of : Mr Mrs Ms Miss Dr	Yes
firstname	string	The first name of the client making the enquiry	Yes
lastname	string	The last name of the client making the enquiry	Yes
email	string	The email of the client making the enquiry	Yes
telephone	string	The telephone of the client making the enquiry	Yes
destination	string	The destination of the enquiry	Yes
apartmentType	string	The apartment type the client wants to stay in. One of: Studio 1 bedroom 2 bedroom 3 bedroom 4 bedroom 4+ bedroom	Yes
dateFrom	string	Starting date of the stay. The format must be YYYY-mm-dd Example: 2019-01-01	Yes
dateTo	string	End date of the stay. The format must be YYYY-mm-dd Example: 2019-01-15	Yes
totalApartments	integer	Amount of apartments to be booked	Yes
totalAdults	integer	Amount of adults that will stay in the apartment/s	Yes
totalChildren	integer	Amount of children that will stay in the apartment/s	No
currency	string	Currency code for the budget. Example: GBP	No
budget	integer	Nightly budget for the enquiry	No
company	string	Company making the enquiry	No
comments	string	Additional comments to be considered for your enquiry	No
source	string	Unique identifier of your integration (provided during development)	Yes

Example Enquiry Request

POST /v1/external/enquiries HTTP/1.1
Host: api.orbitalplatforms.com
Authorization: Bearer a0bafb591538f001125e6e35e068c18eedfe0d08
Content-Type: application/json

{
    "title": "Mr",
    "firstname": "John",
    "lastname": "Doe ",
    "email": "[email protected]",
    "telephone": "+(020)44123465",
    "destination": "United Kindom - London - Chiswick",
    "apartmentType": "Studio",
    "dateFrom": "2019-10-10",
    "dateTo": "2019-10-10",
    "totalApartments": 1,
    "totalAdults": 1,
    "totalChildren": 0,
    "currency": "GBP",
    "budget": "200",
    "company": "Test",
    "comments": "I would like an apartment with views",
    "source": "Test"
}

Example Enquiry Response

{
    "id": "E-062620",
    "title": "Mr",
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]",
    "telephone": "+(020)44123465",
    "destination": "United Kindom - London - Chiswick",
    "apartmentType": "Studio",
    "dateFrom": "2019-10-10",
    "dateTo": "2019-10-10",
    "totalApartments": 1,
    "totalAdults": 1,
    "totalChildren": 0,
    "currency": "GBP",
    "budget": 200,
    "company": "Test",
    "comments": "I would like an apartment with views",
    "source": "Test",
    "createdOn": "2019-02-27 14:03:37",
    "_links": []
}

Property

This endpoint allows external applications to manage property content that is then displayed on all our brands.

With this endpoint information such as property availability, images, location and meta data can be obtained.

Please get in touch for more details about this endpoint

Careers

This endpoint allows external applications to obtain a list of available jobs at the Habicus Group.

Please get in touch for more details about this endpoint

Reservation

This endpoint allows external applications to create and manage reservations in our system.

Please get in touch for more details about this endpoint

Error Handling

The endpoints will return custom error messages when trying to perform actions that do not meet our validation requirements. The HTTP code will also match the error message.

The OTA endpoints will return a success message if changes have been applied successfully or an array of errors and warnings if not.

Example OTA Success Message

{
    "success": true
}

Example OTA Error Message

{
    "success": false,
    "errors": [
        {
            "status": 500,
            "message": "Server error"
        }
    ],
}

Pagination

All REST GET calls to collections are paginated and will return information regarding the current page, number of available pages, page size and total items.

Example Pagination

{
   //...
    "page": 1,
    "pageCount": 2,
    "pageSize": 25,
    "totalItems": 50
}

OTA Swagger Specification

We provide a Swagger specification for our OTA API so that external applications can generate mock servers and documentation to use for development purposes.

You can download the file accessing this link

Sandbox

We provide a Sandbox environment for development purposes. To get access please get in touch with us.

TOPICS

Introduction

Authentication

Endpoints

OTA

Mappings

Inventory

RPC

Destinations

REST

Enquiry

Enquiry Object Model

Property

Careers

Reservation

Error Handling

Pagination

OTA Swagger Specification

Sandbox