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.

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": "johndoe@gmail.com",
        "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": "johndoe@gmail.com",
        "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.