Show menu
Login

KOBAS API Documentation

The KOBAS API

This documentation describes the possibilities and processes surrounding the Kobas API. This API is intended for use by technical teams working for or acting on behalf of companies who use Kobas’s hospitality management software. If you need more information about integrating with Kobas please contact us at integrations@kobas.co.uk

Definitions

  • API – Application Programming Interface, a set of defined methods that can be used to communicate with a software system.
  • HTTPS – Hyper Text Transfer Protocol Secure, the combination of SSL/TLS and HTTP resulting in a secure, stateless transfer of data over commonly used HTTP.
  • JSON – JavaScript Object Notation.
  • OAuth – OAuth 2.0 is the industry-standard protocol for authorisation.
  • RESTful – REpresentative State Transfer.

Technology

The Kobas API is RESTful and operates over HTTPS, exchanging data using JSON. No other notation or transfer protocol is supported at this time.

The API is not available over HTTP without SSL/TLS encryption.

Authorisation

Our API uses OAuth 2.0’s ‘client credential access tokens’ that have a 1 hour expiry. This allows you to use any standard OAuth library or tools like Postman to easily communicate with our API. You can request an access token by submitting a POST request to https://oauth.kobas.co.uk/access_token with the following body:

  • grant_type: client_credentials
  • client_id: [your_client_id]
  • client_secret: [your_client_secret]
  • scope: [your_scope]
  • x-kobas-company-id: [your_kobas_company_id]

This will then return you a token + expiry time, allowing you to communicate with the API.

Note: To ensure compliance with all OAuth 2 libraries and tools, “x-kobas-company-id” can also be sent as a GET variable

Making Requests

All HTTPS requests should be directed to: https://api.kobas.co.uk/v3/ with an appropriate verb and endpoint.

Endpoints

The API exposes a number of endpoints for data exchange and activity. You can all available endpoints and example output at https://api-doc.kobas.co.uk

Verbs

The API accepts the following verbs:

  • DELETE
  • GET
  • POST
  • PUT

The API will accept a PUT request that creates a new resource at the specified location. If a resource already exists at that location, it will be overwritten. A POST request must never attempt to specify a location.

Required Headers

If you have done the authorisation steps above you should have an ‘Access token’ and a ‘Kobas company id’, both of these are required headers on any requests made to https://api.kobas.co.uk/v3/

Headers:

  • Authorisation: Bearer [your_access_token]
  • x-kobas-company-id: [your_kobas_company_id]

Payload

DELETE and GET requests expect data in the query string. POST and PUT requests expect information in the request body.

Content-Type, Encoding and Compression

POST and PUT requests should be in one of the following formats, with a valid Content-Type header to match:

  • Content-Type: application/json
  • Content-Type: application/x-www-form-urlencoded

The API servers support gzip compression and customers are urged to use this where possible to minimise bandwidth usage for all concerned.