API Documentation

The HospoIQ API is currently in beta and may change. Please send feedback to .

Authentication & Authorization

Please get in touch if you wish to connect to our API, describing the purpose of your application and the data you wish to access.

The server is built on Identity Server. Please see the terminology documentation for terms and other documentation that may be useful.

OData

The API supports the OData protocol in a read-only manner. This allows a standard set of URLs to be applied to each endpoint for paging, filtering and sorting. Due to resource limitations, not all fields will be filterable or sortable. These will be documented in each specific endpoint.

The OData metadata endpoint can be found at /api/$metadata.

For more details see the OData entity documentation.

Further tools and documentation on OData can be found at odata.org.

Account Registration and Details

Create User and Site

The API provides the ability to create new users who wish to connect their POS data and hospoIQ.

The request body must consist of the follow parameters:

FirstName: The users first name
LastName: The users last name
Email: The users email
Region: The region where the users business resides in. Currently, we support the following regions:
- Auckland
- Canterbury
- Otago
- Northland
- Tasman
- Hawke's Bay
- Wellington
- Queensland
- Perth
- Northern Territory
- New South Wales
- Victoria
PosType: the POS provider which the users business uses. Currently, we support the following POS's:
- MenuMate
- SwiftPOS
- IdealPOS
- ProTouch
- WizBang
- Bepoz
- Epos
- Kounta
- Tevalis
Password: The password the user will enter to access our reports.
SiteName: The business name of the users company

This will return all account details including a unique download link to install the hospoIQ gateway.

Alternatively, if the POS provider is cloud-based, then the response will also return a URL to the POS provider. Navigating to this URL will present an authorization screen to allow hospoIQ to access POS data via the cloud.

POST: https://api.hospoiq.com/account/register
Body: 
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johnDoe@email.com",
  "createEmail": "true",
  "region": "Auckland",
  "posType": "MenuMate",
  "password": "P@ssWord",
  "siteName": "Johns Business",
}

Result: 
{
  "user": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "johndoe@hospoiq.com",
    "suppliedEmail": "johndoe@email.com"
  },
  "sites": [
    {
      "siteID": 123456,
      "siteName": "Johns Business",
      "gateways": [
        {
          "gatewayID": 0,
          "gatewayCode": "XYZ123",
          "posName": "MenuMate",
          "posStatus": "Not downloaded",
          "posConnectUrl": "https://cloudpos.com/authorize?redirect_uri=https%3a%2f%2fapp.hospoiq.com%2fAuthorize",
          "installerUrl": "https://app.hospoiq.com/download?code=XYZ123",
          "installerUrlExpiry": "2019-10-24T02:19:18+00:00",
          "lastRetrospective": "2019-10-16T18:00:00+00:00",
          "lastRefresh": "2019-10-16T02:19:18+00:00",
        }
      ]
    }
  ]
}

Get User Token

To access resources for your recently created account, you need to request an access token.

The request body must be JSON encoded and consist of the following parameters:

Username: The hospoIQ email address returned from the register endpoint.
Password: The password set in the register endpoint

This will return an access token and refresh token.

POST: https://api.hospoiq.com/token
JSON parameters: 
username = johndoe@hospoiq.com
password = P@ssWord

Result: 
{
  "accessToken": "ey07e4b5...4498",
  "expiresIn" : 3600,
  "tokenType" : "Bearer"
}

Get User and Site Details

The API provides the ability to get Users and all the sites that they own. This request must be authenticated with an access token.

GET: https://api.hospoiq.com/account
Result: 
{
  "user": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "johndoe@hospoiq.com",
    "suppliedEmail": "johndoe@email.com"
  },
  "sites": [
    {
      "siteID": 123456,
      "siteName": "Johns Business",
      "gateways": [
        {
          "gatewayID": 0,
          "gatewayCode": "XYZ123",
          "posName": "MenuMate",
          "posStatus": "Not downloaded",
          "posConnectUrl": "https://cloudpos.com/authorize?redirect_uri=https%3a%2f%2fapp.hospoiq.com%2fAuthorize",
          "installerUrl": "https://app.hospoiq.com/download?code=XYZ123",
          "installerUrlExpiry": "2019-10-16T02:19:18+00:00"
          "lastRetrospective": "2019-10-16T18:00:00+00:00",
          "lastRefresh": "2019-10-16T02:19:18+00:00",
        }
      ]
    },
    {
      "siteID": 234567,
      "siteName": "Johns Business 2",
      "gateways": [
        {
          "gatewayID": 0,
          "gatewayCode": "XYZ234",
          "posName": "MenuMate",
          "posStatus": "Running",
          "posConnectUrl": "https://cloudpos.com/authorize?redirect_uri=https%3a%2f%2fapp.hospoiq.com%2fAuthorize",
          "installerUrl": "https://app.hospoiq.com/download?code=XYZ234",
          "installerUrlExpiry": "2019-10-16T02:19:18+00:00"
          "lastRetrospective": "2019-10-16T18:00:00+00:00",
          "lastRefresh": "2019-10-16T02:19:18+00:00",
        },
        {
          "gatewayID": 1,
          "gatewayCode": "XYZ235",
          "posName": "MenuMate",
          "posStatus": "Running",
          "posConnectUrl": "https://cloudpos.com/authorize?redirect_uri=https%3a%2f%2fapp.hospoiq.com%2fAuthorize",
          "installerUrl": "https://app.hospoiq.com/download?code=XYZ235",
          "installerUrlExpiry": "2019-10-16T02:19:18+00:00"
          "lastRetrospective": "2019-10-16T18:00:00+00:00",
          "lastRefresh": "2019-10-16T02:19:18+00:00",
        }
      ]
    }
  ]
}