NAV
Examples

HotSchedules IoT Platform

Restaurant operators need access to data and we are here to help you deliver it. The HotSchedules IoT Platform can help you work more productively and efficiently through a set of software modules that collect data from virtually any source in real-time and then deliver select data that is relevant, timely and actionable.

Whether you work for a restaurant, a software company or for yourself - wherever you are, whatever you do - The HotSchedules IoT Platform gives you the power to innovate faster and cheaper than ever before.

IoT Platform APIServer Overview

The HotSchedules IoT Platform APIServer is a set of secure REST APIs that are used to store your data.

The foundation for this document is the Mongo DB reference located at http://docs.mongodb.org/manual/reference/operator/.

Users may be unfamiliar with the REST query syntax. Those familiar with SQL should note that the same types of SQL query operations are possible using the REST API. Users wishing to understand the mapping between SQL queries (SELECT statements) and the Query syntax - should refer to the following document: http://docs.mongodb.org/manual/reference/sql-comparison/.

HotSchedules API Documentation

This documentation is intended for those wanting to integrate into the HotSchedules IoT (Internet of Things) Platform.

Accounts in the IoT Platform are called a namespace. A namespace is a secured HotSchedules cloud storage location for your business. Your namespace is uniquely named based on your organization name. When you sign up through the HotSchedules IoT Platform Portal, you will have the ability to create both a namespace and users to access that namespace.

The HotSchedules IoT Platform Portal has an easy sign up process to help you get started developing your application for the IoT Platform. In just a few short clicks, your IoT platform application development can begin.

Access To The Cloud API

To access the HotSchedules Cloud API, you will need to login with your user and password which is provided by HotSchedules. The IoT Cloud API is available at this location: https://api.hotschedules.io/apidocs/index.html.

If you enter your credentials (username and password) and click Explore, you will see a list of APIs which you can access for your namespace. The Cloud APIs are REST APIs which returns JSON for all responses.

The Cloud API has examples and an opportunity to Try it out!. You can add data using our provided types or create your own types.

NOTE: Should you create your own type, the new type will be available in the API Methods for your namespace.

Logging In To The Cloud API

Exploring The Cloud API

Once logged into the Cloud API, you can both explore the provided types and their respective restful verbs: GET, PUT, DELETE, PATCH. The Cloud API is much more than API Documentation, it is a powerful interactive tool that allows the developer and/or administrator to create, update, delete data as well as manage the schema for their organization.

Getting Started

The HotSchedules IoT Platform (Bodhi) REST API allows you to query meta-data about your stores, labor, sales, and HotSchedules Agents running in your stores. You can also do some fancy things like get social information, upload files, send push notifications and emails, and even make payments.

The REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

IDM - Creating Your Global Profile

Identity Management, or IDM, allows you to sign in to multiple HotSchedules modules with one username and password. With IDM, you’ll have one place to go, and one username and password to access all things HotSchedules.

Please note: With that said, this tool is in its early stages, and does not yet cover ALL HotSchedules modules. The plan is to incorporate all tools by mid-2018.

For more details on IDM, please click HERE.

IDM How to Programatically Retrieve JWT Tokens

Before you can retrieve your token, follow these simple setup steps before proceeding.

Step 1: Create your global profile.
Step 2: Obtain your API credentials from HotSchedules if you have not already done so.
Step 3: Login into the Account Manager
Step 4: In the upper right corner, select the wrench icon, then keychain, then your namespace.
Step 5: Enter your API credentials as provided by hotSchedules and click save.
Step 6: Continue with the example below to retrieve your token.

What are JSON Web Tokens?

JSON Web Tokens (JWT), pronounced “jot”, are a standard since the information they carry is transmitted via JSON.

JSON Web Tokens work across different programming languages: JWTs work in .NET, Python, Node.js, Java, PHP, Ruby, Go, JavaScript, and Haskell. So you can see that these can be used in many different scenarios.

JWTs are self-contained: They will carry all the information necessary within itself. This means that a JWT will be able to transmit basic information about itself, a payload (usually user information), and a signature.

JWTs can be passed around easily: Since JWTs are self-contained, they are perfectly used inside an HTTP header when authenticating an API. You can also pass it through the URL.

Endpoint

Dev: https://login.bodhi-dev.io/auth/realms/hotschedules/protocol/openid-connect/token

Prod: https://login.hotschedules.io/auth/realms/hotschedules/protocol/openid-connect/token

Header

Params

Return

Sample Call (Postman)

Note: Postman is the free tool used to generate these examples. Download Postman.

alt text

Sample Call (Curl)

curl -X POST \

  https://login.bodhi-dev.io/auth/realms/hotschedules/protocol/openid-connect/token \

  -H 'cache-control: no-cache' \

  -H 'content-type: application/x-www-form-urlencoded' \

  -d 'grant_type=password&client_id=urn%3Amace%3Aoidc%3Ahotschedules.com&username=username&password=password'

Sample Call (Node)

var request = require("request");

var options = { method: 'POST',

  url: 'https://login.bodhi-dev.io/auth/realms/hotschedules/protocol/openid-connect/token',

  headers: 

   { 'cache-control': 'no-cache',

     'content-type': 'application/x-www-form-urlencoded' },

  form: 

   { grant_type: 'password',

     client_id: 'urn:mace:oidc:hotschedules.com',

     username: 'username',

     password: 'password' } };

request(options, function (error, response, body) {

  if (error) throw new Error(error);

  console.log(body);

});

Sample Results

{

    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiI3NmM1YjIyMC03NjQxLTRhYzctYTA5NS02ZjU4NWY0ZGE1MzIiLCJleHAiOjE1MDM0NzU3MzYsIm5iZiI6MCwiaWF0IjoxNTAzMzY3NzM2LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI4YjdkNTc2Ny04MTYyLTQyMTgtODVmNi1hMzRjYTY5ZDVkNGQiLCJhY3IiOiIxIiwiY2xpZW50X3Nlc3Npb24iOiIwYzVlMDc3Zi0yNzBjLTQ0YWUtOTllNS00ZmQwMzkyOTM4YjciLCJhbGxvd2VkLW9yaWdpbnMiOltdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiYWRtaW4iLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm1hbmFnZS11c2VycyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX0sInByZWZlcnJlZF91c2VybmFtZSI6InRyYXZpc2pvaG5zb25teGRldiJ9.U7YARFPbRJVHzPdQfXIvsUneZe44AQdBcR5JR8rqC8h2lFO1LkGfsO-yrLGYsnjzroJg3cJ8XD9yJOY7sLNSTAKX3FTKpBViQ2LrOlcyR4eNQrl3dfM6hVSQHAgwItJ3wSsTQk2feCj0jIj69JmT63mjkOGsBCfhO8lRvWGmVUHm3eXw4F1_h-KATKEGi4xjLgD5GoRn30FZ1BYn-7GQBgU-sAxge_dr0IQe2f8PjIqNSEKfv01NMmn4LpKjNRUiTZbb-pe1AK0j7yy6mf0reduKUTXp0S51QGuaG2Qe9uokYyfLhHuu6bja7OQ7ax8uYlpwVTF8xKpNhosDBmHw2A",

    "expires_in": 108000,

    "refresh_expires_in": 1800,

    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiJhYzcxOWI1Ny04OTA2LTRkMDYtYmU5My1mNDM3ZjM4M2M2M2IiLCJleHAiOjE1MDMzNjk1MzYsIm5iZiI6MCwiaWF0IjoxNTAzMzY3NzM2LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoidXJuOm1hY2U6b2lkYzpob3RzY2hlZHVsZXMuY29tIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiOGI3ZDU3NjctODE2Mi00MjE4LTg1ZjYtYTM0Y2E2OWQ1ZDRkIiwiY2xpZW50X3Nlc3Npb24iOiIwYzVlMDc3Zi0yNzBjLTQ0YWUtOTllNS00ZmQwMzkyOTM4YjciLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiYWRtaW4iLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm1hbmFnZS11c2VycyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19.VPD0wzTwpyXoqVoax0FWT53PznjDLsARUPyBKsqR7e5PAv5_hpMKdPVYqVQh0bKJWpV5XDSgISyJjg4lbvW7Zb-jG7Q-bAS3vT5jfp_WE_JoPqKzgdp-oq463hVPD_vPL_UzpXH5uX1gN2x2rgt7IOU7_uYFK0preUCOsBGG_ioDLyHLZ9_0BizNc59Tzdjv5gQHammDF2jbHG2g3XurLqVbGtEjGEwkO5Zax02YfslOaOHuff_litJsw9QlN7MIFEMDRpwPT3H2hQkVpQw7Du_Sd6XZxU0BQmK599wb5D7zn2O7wlpNQcxGl1U1CA7Dqnrqn6YoVpOske8nz-qpmg",

    "token_type": "bearer",

    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiJjMTNkYzk4My1kZjQ1LTQ1MjgtYWEwMi1hZTIzZGUzYzhkNzYiLCJleHAiOjE1MDM0NzU3MzYsIm5iZiI6MCwiaWF0IjoxNTAzMzY3NzM2LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJJRCIsImF6cCI6InVybjptYWNlOm9pZGM6aG90c2NoZWR1bGVzLmNvbSIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjhiN2Q1NzY3LTgxNjItNDIxOC04NWY2LWEzNGNhNjlkNWQ0ZCIsImFjciI6IjEiLCJvdGhlckNsYWltcyI6eyJib2RoaWFwaSI6InRyYXZpc2pvaG5zb25teGRldiJ9LCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ0cmF2aXNqb2huc29ubXhkZXYifQ.jMRuuajwcXKdPV1NR-Ba38PWs55ES0Ff-LmMdEsVhC3ftD8__uIKOY1lBlT7ZS_b7P92h4yHTGzx6_RBS2GXEX6qSocltbY8ETVpS0uVPNShQD4EenKBXSgWtvkCvYASKUooOCfO_D7UgwdsXqojgsTR6j9fS10rA3FO_ewQGvimYvUwqpdQr844TSpPGvxmMZj4lvXPGXD77R8GyuZxOyKM2kM5vj2DFO8YZeI7dO0o3XKp2ccRnDSq0SI38sVO9mBcRcdfm6Z8gaiACS__39w3YtP6JfZMALUxfIDdYPG9Ttz264vUwrKGa25ckbzCDqUYJ4zazVrneglC6FzysA",

    "not-before-policy": 0,

    "session_state": "8b7d5767-8162-4218-85f6-a34ca69d5d4d"

}

IDM How to Refresh JWT Tokens

Endpoint

Dev: https://login.bodhi-dev.io/auth/realms/hotschedules/protocol/openid-connect/token

Prod: https://login.hotschedules.io/auth/realms/hotschedules/protocol/openid-connect/token

Header

Params

Return

Sample Call (Postman)

alt text

Sample Call (Curl)

curl -X POST \
  https://login.bodhi-dev.io/auth/realms/hotschedules/protocol/openid-connect/token \
  -H 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiJmNGQwNjQyOC1jNzIzLTQ0YWYtOTRmYS00MGI2MGQ3MWQxMmQiLCJleHAiOjE1MDMzNzA4MzQsIm5iZiI6MCwiaWF0IjoxNTAzMzY5MDM0LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoidXJuOm1hY2U6b2lkYzpob3RzY2hlZHVsZXMuY29tIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMGE4MTQzYjktNmMzNC00ZTcxLWI4YWMtZjkyNDRjZjJhZjgyIiwiY2xpZW50X3Nlc3Npb24iOiJlMDgxNDBkNi1lODVlLTQzOGQtYmZjYi03ODY2YmFkZTlkODMiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiYWRtaW4iLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm1hbmFnZS11c2VycyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19.QifLXuXYanmKlh8fDpLqurhb1S3hpEVwObUWcfMvv-_M0PCWyXJ4lKZHHhWVQAD9dhTc9Eqqpy9jdrTjTR76P67wFzP4me6CVXI9tVRC1xb82ccPg4RsRu-UfEu0B87sg6pcjc4k6fp9_2YV02dLhA52rnP-19gCEPkF5SYTex2wWxzdoHwXgAaHxO4HWc4Mru_x4Pu5iLLGJ6c13Nq_t3YbsrTuAb11FV5F2IlHDBmIcqJKf0PanrWVuORyQyZuOgRaspgVsHr8nQNzHf81DiB5Fy4sa9MubRzEZvo_HEd-KcnTlo0_-WhI5gComAR-fM9hIKc5zZvLd9CO84asSg' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id=urn%3Amace%3Aoidc%3Ahotschedules.com&refresh_token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiJmNGQwNjQyOC1jNzIzLTQ0YWYtOTRmYS00MGI2MGQ3MWQxMmQiLCJleHAiOjE1MDMzNzA4MzQsIm5iZiI6MCwiaWF0IjoxNTAzMzY5MDM0LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoidXJuOm1hY2U6b2lkYzpob3RzY2hlZHVsZXMuY29tIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMGE4MTQzYjktNmMzNC00ZTcxLWI4YWMtZjkyNDRjZjJhZjgyIiwiY2xpZW50X3Nlc3Npb24iOiJlMDgxNDBkNi1lODVlLTQzOGQtYmZjYi03ODY2YmFkZTlkODMiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiYWRtaW4iLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm1hbmFnZS11c2VycyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19.QifLXuXYanmKlh8fDpLqurhb1S3hpEVwObUWcfMvv-_M0PCWyXJ4lKZHHhWVQAD9dhTc9Eqqpy9jdrTjTR76P67wFzP4me6CVXI9tVRC1xb82ccPg4RsRu-UfEu0B87sg6pcjc4k6fp9_2YV02dLhA52rnP-19gCEPkF5SYTex2wWxzdoHwXgAaHxO4HWc4Mru_x4Pu5iLLGJ6c13Nq_t3YbsrTuAb11FV5F2IlHDBmIcqJKf0PanrWVuORyQyZuOgRaspgVsHr8nQNzHf81DiB5Fy4sa9MubRzEZvo_HEd-KcnTlo0_-WhI5gComAR-fM9hIKc5zZvLd9CO84asSg'

Sample Call (Node)

var request = require("request");

var options = { method: 'POST',
  url: 'https://login.bodhi-dev.io/auth/realms/hotschedules/protocol/openid-connect/token',
  headers: 
   { 'postman-token': '3759ed14-04f9-cc9d-9863-c8c9938c9f18',
     'cache-control': 'no-cache',
     'content-type': 'application/x-www-form-urlencoded',
     authorization: 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiJmNGQwNjQyOC1jNzIzLTQ0YWYtOTRmYS00MGI2MGQ3MWQxMmQiLCJleHAiOjE1MDMzNzA4MzQsIm5iZiI6MCwiaWF0IjoxNTAzMzY5MDM0LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoidXJuOm1hY2U6b2lkYzpob3RzY2hlZHVsZXMuY29tIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMGE4MTQzYjktNmMzNC00ZTcxLWI4YWMtZjkyNDRjZjJhZjgyIiwiY2xpZW50X3Nlc3Npb24iOiJlMDgxNDBkNi1lODVlLTQzOGQtYmZjYi03ODY2YmFkZTlkODMiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiYWRtaW4iLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm1hbmFnZS11c2VycyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19.QifLXuXYanmKlh8fDpLqurhb1S3hpEVwObUWcfMvv-_M0PCWyXJ4lKZHHhWVQAD9dhTc9Eqqpy9jdrTjTR76P67wFzP4me6CVXI9tVRC1xb82ccPg4RsRu-UfEu0B87sg6pcjc4k6fp9_2YV02dLhA52rnP-19gCEPkF5SYTex2wWxzdoHwXgAaHxO4HWc4Mru_x4Pu5iLLGJ6c13Nq_t3YbsrTuAb11FV5F2IlHDBmIcqJKf0PanrWVuORyQyZuOgRaspgVsHr8nQNzHf81DiB5Fy4sa9MubRzEZvo_HEd-KcnTlo0_-WhI5gComAR-fM9hIKc5zZvLd9CO84asSg' },
  form: 
   { grant_type: 'refresh_token',
     client_id: 'urn:mace:oidc:hotschedules.com',
     refresh_token: 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiJmNGQwNjQyOC1jNzIzLTQ0YWYtOTRmYS00MGI2MGQ3MWQxMmQiLCJleHAiOjE1MDMzNzA4MzQsIm5iZiI6MCwiaWF0IjoxNTAzMzY5MDM0LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoidXJuOm1hY2U6b2lkYzpob3RzY2hlZHVsZXMuY29tIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMGE4MTQzYjktNmMzNC00ZTcxLWI4YWMtZjkyNDRjZjJhZjgyIiwiY2xpZW50X3Nlc3Npb24iOiJlMDgxNDBkNi1lODVlLTQzOGQtYmZjYi03ODY2YmFkZTlkODMiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiYWRtaW4iLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm1hbmFnZS11c2VycyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19.QifLXuXYanmKlh8fDpLqurhb1S3hpEVwObUWcfMvv-_M0PCWyXJ4lKZHHhWVQAD9dhTc9Eqqpy9jdrTjTR76P67wFzP4me6CVXI9tVRC1xb82ccPg4RsRu-UfEu0B87sg6pcjc4k6fp9_2YV02dLhA52rnP-19gCEPkF5SYTex2wWxzdoHwXgAaHxO4HWc4Mru_x4Pu5iLLGJ6c13Nq_t3YbsrTuAb11FV5F2IlHDBmIcqJKf0PanrWVuORyQyZuOgRaspgVsHr8nQNzHf81DiB5Fy4sa9MubRzEZvo_HEd-KcnTlo0_-WhI5gComAR-fM9hIKc5zZvLd9CO84asSg' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Sample Results

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiI3NmM1YjIyMC03NjQxLTRhYzctYTA5NS02ZjU4NWY0ZGE1MzIiLCJleHAiOjE1MDM0NzU3MzYsIm5iZiI6MCwiaWF0IjoxNTAzMzY3NzM2LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiI4YjdkNTc2Ny04MTYyLTQyMTgtODVmNi1hMzRjYTY5ZDVkNGQiLCJhY3IiOiIxIiwiY2xpZW50X3Nlc3Npb24iOiIwYzVlMDc3Zi0yNzBjLTQ0YWUtOTllNS00ZmQwMzkyOTM4YjciLCJhbGxvd2VkLW9yaWdpbnMiOltdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiYWRtaW4iLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm1hbmFnZS11c2VycyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX0sInByZWZlcnJlZF91c2VybmFtZSI6InRyYXZpc2pvaG5zb25teGRldiJ9.U7YARFPbRJVHzPdQfXIvsUneZe44AQdBcR5JR8rqC8h2lFO1LkGfsO-yrLGYsnjzroJg3cJ8XD9yJOY7sLNSTAKX3FTKpBViQ2LrOlcyR4eNQrl3dfM6hVSQHAgwItJ3wSsTQk2feCj0jIj69JmT63mjkOGsBCfhO8lRvWGmVUHm3eXw4F1_h-KATKEGi4xjLgD5GoRn30FZ1BYn-7GQBgU-sAxge_dr0IQe2f8PjIqNSEKfv01NMmn4LpKjNRUiTZbb-pe1AK0j7yy6mf0reduKUTXp0S51QGuaG2Qe9uokYyfLhHuu6bja7OQ7ax8uYlpwVTF8xKpNhosDBmHw2A",
    "expires_in": 108000,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiJhYzcxOWI1Ny04OTA2LTRkMDYtYmU5My1mNDM3ZjM4M2M2M2IiLCJleHAiOjE1MDMzNjk1MzYsIm5iZiI6MCwiaWF0IjoxNTAzMzY3NzM2LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoidXJuOm1hY2U6b2lkYzpob3RzY2hlZHVsZXMuY29tIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiOGI3ZDU3NjctODE2Mi00MjE4LTg1ZjYtYTM0Y2E2OWQ1ZDRkIiwiY2xpZW50X3Nlc3Npb24iOiIwYzVlMDc3Zi0yNzBjLTQ0YWUtOTllNS00ZmQwMzkyOTM4YjciLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiYWRtaW4iLCJ1bWFfYXV0aG9yaXphdGlvbiIsInVzZXIiXX0sInJlc291cmNlX2FjY2VzcyI6eyJyZWFsbS1tYW5hZ2VtZW50Ijp7InJvbGVzIjpbIm1hbmFnZS11c2VycyJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsInZpZXctcHJvZmlsZSJdfX19.VPD0wzTwpyXoqVoax0FWT53PznjDLsARUPyBKsqR7e5PAv5_hpMKdPVYqVQh0bKJWpV5XDSgISyJjg4lbvW7Zb-jG7Q-bAS3vT5jfp_WE_JoPqKzgdp-oq463hVPD_vPL_UzpXH5uX1gN2x2rgt7IOU7_uYFK0preUCOsBGG_ioDLyHLZ9_0BizNc59Tzdjv5gQHammDF2jbHG2g3XurLqVbGtEjGEwkO5Zax02YfslOaOHuff_litJsw9QlN7MIFEMDRpwPT3H2hQkVpQw7Du_Sd6XZxU0BQmK599wb5D7zn2O7wlpNQcxGl1U1CA7Dqnrqn6YoVpOske8nz-qpmg",
    "token_type": "bearer",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWnRINE56ejBGZURjMU1FSkIyU2lIeHhGS0xuLXQtVm1DUHBHeUVnS09BIn0.eyJqdGkiOiJjMTNkYzk4My1kZjQ1LTQ1MjgtYWEwMi1hZTIzZGUzYzhkNzYiLCJleHAiOjE1MDM0NzU3MzYsIm5iZiI6MCwiaWF0IjoxNTAzMzY3NzM2LCJpc3MiOiJodHRwczovL2xvZ2luLmJvZGhpLWRldi5pby9hdXRoL3JlYWxtcy9ob3RzY2hlZHVsZXMiLCJhdWQiOiJ1cm46bWFjZTpvaWRjOmhvdHNjaGVkdWxlcy5jb20iLCJzdWIiOiI3NDE4MjRhYy0zMjlkLTQ4OTAtYTRmNi0zMmJmMTBiNjJhMjEiLCJ0eXAiOiJJRCIsImF6cCI6InVybjptYWNlOm9pZGM6aG90c2NoZWR1bGVzLmNvbSIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjhiN2Q1NzY3LTgxNjItNDIxOC04NWY2LWEzNGNhNjlkNWQ0ZCIsImFjciI6IjEiLCJvdGhlckNsYWltcyI6eyJib2RoaWFwaSI6InRyYXZpc2pvaG5zb25teGRldiJ9LCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ0cmF2aXNqb2huc29ubXhkZXYifQ.jMRuuajwcXKdPV1NR-Ba38PWs55ES0Ff-LmMdEsVhC3ftD8__uIKOY1lBlT7ZS_b7P92h4yHTGzx6_RBS2GXEX6qSocltbY8ETVpS0uVPNShQD4EenKBXSgWtvkCvYASKUooOCfO_D7UgwdsXqojgsTR6j9fS10rA3FO_ewQGvimYvUwqpdQr844TSpPGvxmMZj4lvXPGXD77R8GyuZxOyKM2kM5vj2DFO8YZeI7dO0o3XKp2ccRnDSq0SI38sVO9mBcRcdfm6Z8gaiACS__39w3YtP6JfZMALUxfIDdYPG9Ttz264vUwrKGa25ckbzCDqUYJ4zazVrneglC6FzysA",
    "not-before-policy": 0,
    "session_state": "8b7d5767-8162-4218-85f6-a34ca69d5d4d"
}

Working with HotSchedules data

Making a call

Note: If your namespace has been created under the new IDM model, you will not have the ability to make calls using api.hotschedules.io. Please refer to the section on using Postman to make a call. You will need to have retrieved your JWT Token before you can use this method.


The HotSchedules REST API supports all the standard REST verbs.

GET
POST
PUT
PATCH
DELETE

You can access these verbs for each of the types in the HotSchedules system. When an organization is created in the HotSchedules Platform, the organization automatically gets 32 ‘types’ that will store standard information and data about your organization. Those 'types’ can be viewed and reviewed at https://api.hotschedules.io/apidocs/index.html

GET

As an example, let’s do a GET on a store via CURL curl -ik --cookie "RUSK=8a6f98bb1033055fc04d644c0006789335f96c2b-username=platform" -X GET https://api.hotschedules.io/bodhi-social/resources/Store

This call will return the information about a store that’s been created for the bodhi-social organization

[{"sys_version":1,"image_url":"https://upload.wikimedia.org/wikipedia/commons/5/54/Golden_Gate_Bridge_0002.jpg","sys_type_version":12,"address":{"street_address":"555 Mission","extended_address":"","locality":"San Francisco","region":"CA","postal_code":"94111","country":"US"},"store_hours":[{"days":[7,1],"start":"0500","end":"0000"},{"days":[1,2],"start":"1200","end":"0200"},{"days":[2,3],"start":"1200","end":"0200"},{"days":[3,4],"start":"1200","end":"0200"},{"days":[4,5],"start":"1200","end":"0200"},{"days":[5,6],"start":"1200","end":"0200"},{"days":[6,7],"start":"0500","end":"0000"}],"sys_created_by":"admin__bodhi-social","sys_created_at":"2016-05-21T15:37:15.560Z","name":"platformstore","store_number":"1","display_name":"Platform Store","sys_id":"574080abb9a19e2dadee775b"}]

You can also get the JSON payload by navigating directly to this URL https://api.hotschedules.io/bodhi-social/resources/Store

You can create your own store for your organization either by executing a POST command (see below) to https://api.hotschedules.io/<organization_name>/resources/Store or using our free store manager tool at https://hotschedules.io/store-manager . Either way, a store is a critical anchor for information in the Platform.

Next let’s look up a sale for our store in bodhi-social

curl -ik --cookie "RUSK=8a6f98bb1033055fc04d644c0006789335f96c2b-username=platform" -X GET https://api.hotschedules.io/bodhi-social/resources/SalesTransaction

RESULT:

[{"order_number":10184,"item_count":1,"store_id":"574080abb9a19e2dadee775b","employee":{"id":"5151","name":"Ted Morrison"},"business_day":"2016-05-20","revenue_center":{"id":"2","name":"Restaraunt"},"type":{"id":"4","name":"1"},"timestamp":"2016-05-21T03:34:00.000Z","transaction_id":"557605fc4c32e071180a46042016-05-2010184","net_total":{"value":325,"code":"USD","scale":2},"discount_total":{"value":0,"code":"USD","scale":2},"tax_total":{"value":23,"code":"USD","scale":2},"gross_total":{"value":348,"code":"USD","scale":2},"tender_total":{"value":348,"code":"USD","scale":2},"order_opened_at":"2016-05-21T03:33:00.000Z","order_closed_at":"2016-05-21T03:34:00.000Z","guest_count":1,"sys_version":1,"sys_created_at":"2016-05-21T16:02:30.800Z","sys_created_by":"admin__bodhi-social","sys_type_version":12,"sys_id":"574086965eacd06aa3db036b"}]

We can also look up our Store using query parameters in our URL

curl --cookie "RUSK=8a6f98bb1033055fc04d644c0006789335f96c2b-username=platform" 'https://api.hotschedules.io.io/bodhi-social/resources/SalesTransaction?where=%7Bbusiness_day:"2016-05-20"%7D&fields=business_day'

OR alternatively:

curl -g --cookie "RUSK=8a6f98bb1033055fc04d644c0006789335f96c2b-username=platform" 'https://api.hotschedules.io/bodhi-social/resources/SalesTransaction?where={business_day:"2016-05-20"}&fields=business_day'

RESULT:
[{"order_number":10184,"item_count":1,"store_id":"574080abb9a19e2dadee775b","employee":{"id":"5151","name":"Ted Morrison"},"business_day":"2016-05-20","revenue_center":{"id":"2","name":"Restaraunt"},"type":{"id":"4","name":"1"},"timestamp":"2016-05-21T03:34:00.000Z","transaction_id":"557605fc4c32e071180a46042016-05-2010184","net_total":{"value":325,"code":"USD","scale":2},"discount_total":{"value":0,"code":"USD","scale":2},"tax_total":{"value":23,"code":"USD","scale":2},"gross_total":{"value":348,"code":"USD","scale":2},"tender_total":{"value":348,"code":"USD","scale":2},"order_opened_at":"2016-05-21T03:33:00.000Z","order_closed_at":"2016-05-21T03:34:00.000Z","guest_count":1,"sys_version":1,"sys_created_at":"2016-05-21T16:02:30.800Z","sys_created_by":"admin__bodhi-social","sys_type_version":12,"sys_id":"574086965eacd06aa3db036b"}]

So https://api.hotschedules.io/bodhi-social/resources/SalesTransaction?where={%27business_day%27:%272016-05-20%27} would return all SalesTransaction’s for the business day of 2016-05-20. The URL https://api.hotschedules.io/bodhi-social/resources/SalesTransaction?where={%27store_id%27:%27574080abb9a19e2dadee775b%27} would return all SalesTransaction’s for the store 574080abb9a19e2dadee775b (our Platform test store).

All Types can be queried by any parameter within the type using a ?where={} clause. It’s EXTREMELY important for efficiency and performance to query using indexes on your types. You can review the Types for your organization as well as the Indexes and Parameters by using our free Type Tool located at https://tools.hotschedules.io/types or by inspecting https://api.hotschedules.io/<organization_name>/resources/BodhiType

POST

To POST to a type you need to add the the header: 'Content-Type: application/json’ to your cURL Command

curl -ik -H 'Content-Type: application/json' --cookie "RUSK=8a6f98bb1033055fc04d644c0006789335f96c2b-username=foo" -X POST -d '{ "store_id": "l8zeL", "business_day": "2016-05-13", "timestamp": "2016-05-12T05:58:31.296Z", "transaction_id": "FGHG012", "tender_total": { "code": "USD", "scale": 2, "value": 620 } }' https://api.hotschedules.io/<organization_name>/resources/SalesTransaction

That command will post the json object to the SalesTransaction type. You can now GET on this type either using cURL or the free query tools available at https://tools.hotschedules.io/query

Bulk Post

All bulk operations are accessible through https://api.hotschedules.io
The size limitation for the body is 17MB

Syntax:

POST /<organization_name>/bulk with json body
{ "config": { "op": "insert" or "update" or "upsert" or "invite", * see below "report": true, <- optional, need a report? (default false) "target": "target_name” <- the name of the type (not for invite) }, "payload": [{ "the_field": "my first thing to insert or upsert or invite", "other_field": "the_other_field" }, { "the_field": "my second thing to insert or upsert", "other_field": "the_other_field2" }] }

The payload varies depending on the type of operation and Returns 202 with header bulk_id:<the bulk id>

The result of a report, if requested, is accessible as soon as the processing is done on:

GET /<organization_name>/bulk/<bulk_id>

RESPONSE:
returns 200 with a json array body where the order of the cells matches the order of the payload. The report can be accessed only once.
returns 204 if the report is not ready yet
returns 404 if no report was found with that id

Example:

{ "config": { "op": "insert", "report": true, "target": "BulkTest" }, "payload": [{ "name": "leo", "other_field": "mauris non" }, { "name": "orci", "other_field": "sit amet justo" }, { "name": "nulla", "other_field": "pulvinar sed nisl nunc rhoncus" }, { "name": "nulla", "other_field": "diam cras" }, { "name": "est", "other_field": "dui nec nisi volutpat" }, { "name": "lorem", "other_field": "cursus id" }, { "name": "molestie", "other_field": "potenti nullam porttitor lacus at" }, { "name": "sapien", "other_field": "ultrices aliquet maecenas leo" }, { "name": "nibh", "other_field": "consectetuer eget rutrum at" }, { "name": "luctus", "other_field": "nisl nunc" }] }

PUT

The HTTP verb PUT can be used on any type as long as there’s a unique index on the field or fields. You can always PUT on sys_id

As an example, in the above SalesTransaction example, the sys_id is 574086965eacd06aa3db036b, a PUT to the SalesTransaction based on sys_id would be as follows:

curl -ik -H 'Content-Type: application/json' --cookie "RUSK=8a6f98bb1033055fc04d644c0006789335f96c2b-username=foo" -X PUT -d '{ "store_id": "l8zeL", "business_day": "2016-05-13", "timestamp": "2016-05-12T05:58:31.296Z", "transaction_id": "FGHG012", "tender_total": { "code": "USD", "scale": 2, "value": 620 } }' https://api.hotschedules.io/tutorial/resources/SalesTransaction/574086965eacd06aa3db036b

PUT Upsert

Upsert is a safe way to replace an existing record, or POST a record if the entry does not currently exist.

You can upsert by appending your URL with ?upsert=true

As an example, the above PUT example can be changed to a replace by appending the ?upsert=true to the cURL command:

curl -ik -H 'Content-Type: application/json' --cookie "RUSK=8a6f98bb1033055fc04d644c0006789335f96c2b-username=foo" -X PUT -d '{ "store_id": "l8zeL", "business_day": "2016-05-13", "timestamp": "2016-05-12T05:58:31.296Z", "transaction_id": "FGHG012", "tender_total": { "code": "USD", "scale": 2, "value": 620 } }' https://api.hotschedules.io/tutorial/resources/SalesTransaction/574086965eacd06aa3db036b?upsert=true

PATCH

the HTTP verb PATCH will allow you to alter single parameters or fields within a record in your type. Patch commands follow the following sytax: [ { “op”: “replace”, “path”: “/baz”, “value”: “boo” }, { “op”: “add”, “path”: “/hello”, “value”: [“world”] }, { “op”: “remove”, “path”: “/foo”} ]

The HTTP verb PATCH can be used on any type as long as there’s a unique index on the field or fields. You can always PATCH on sys_id

DELETE

the HTTP verb DELETE will allow you to remove a record in your type. To delete multiple records, include a ?where={} in your URL to narrow or expand then number of records removed.

File Upload

The Platform BodhiFileUpload endpoints are special types that allow a user to upload and download any file (like a dbf file from your store’s POS).

Metadata of your file is posted to type BodhiFileUpload on successful upload

BodhiFileUpload example record:
{ "namespace": "bodhi", "original_name": "profile_pic5.jpg", "sys_version": 1, "location": "bodhi/profile_pic5.jpg", "uploaded_at": "2015-09-10T19:42:48+0000", "sys_created_by": "admin__bodhi", "sys_created_at": "2015-09-10T19:42:49+0000", "name": "profile_pic5.jpg", "media_type": "image/jpeg", "sys_id": "55f1dd39b9b5904f64c8212f" }

Examples:
The following are curl examples of how to specify file location in your upload/download/delete commands. Everything after “upload/” or “download/” in the url is used as the destination. Note that filename is always specified in the url.

curl -X POST -u <username>:<password> https://api.hotschedules.io/<organization_name>/controllers/vertx/upload/recipes/food/BurritoRecipe.txt -F "upload1=@THE_FILE"

curl -X PUT -u <username>:<password> https://api.hotschedules.io/<organization_name>/controllers/vertx/upload/recipes/food/BurritoRecipe.txt -F "upload1=@THE_FILE"

Download by path:
curl -X GET -u <username>:<password> https://api.hotschedules.io/<organization_name>/controllers/vertx/download/recipes/food/BurritoRecipe.txt

Download by sys_id:
curl -X GET -u <username>:<password> https://api.hotschedules.io/<organization_name>/controllers/vertx/download/56f9c2b4fa92ec27934a76ae

Delete a file:
curl -X DELETE -u <username>:<password> https://api.hotschedules.io/<organization_name>/controllers/vertx/upload/recipes/food/BurritoRecipe.txt

Using Postman To Make a Call

Postman makes API development faster, easier, and better. Postman is the most complete toolchain for API development. The most-used REST client worldwide. Designed from the ground up to support the API developer. Intuitive user interface to send requests, save responses, add tests, and create workflows Read the docs.

You can make calls using both Basic Authentication using your HotSchedules IoT Platform account credentials (username and password) and the JWT Token method.

We have created a Postman collection to enable you with making calls to the REST API.

Basic Authentication Example: Let’s do a Basic Authentication call to getEmpInfo. This method takes in a concept ID and a store ID and returns an array of wsEmpInfo objects. It is meant to get a list of all employees for that store.


1. Create a new Request in Postman and name it 'Get Employee Info’.

alt text

2. Set the request type to 'GET’ and enter the following URL. https://api.hotschedules.io/YOURNAMESPACE/controllers/vertx/hotschedules/YOURCONCEPTID/YOURSTORENUMBER/getEmpInfo?active_only=true

alt text

3. Select 'Basic Auth’ in the Authorization section and enter your username and password.

alt text alt text

4. Push the 'Send’ button to make the call and review the response in the 'Body’ section.

alt text

5. Save the request so you can refer back and make repetitive calls to update the response.



NOTE: Completing the step of retrieving your JWT Token is required before you can utilize the following example to make a call to the API with your JWT Token.

JWT Token Example: To perform a call using this method, follow the same steps as the Basic Authentication method with the exception of Step 3. Select 'Bearer Token’ as the Authorization type and enter the bearer token you received when you performed the 'Retrieve JWT Token’ call.

alt text

Available REST API Methods

The HotSchedules REST API provides a user-friendly way to obtain HS Data.

Please ensure that API access has been enabled for your HotSchedules account. Contact customer service 1-866-753-3853 for access or questions.

The url path can look like any of the following, depending on which type is being queried:


../hotschedules/<concept_id>/<store_id>/<type_method>?
../hotschedules/<concept_id>/<type_method>?
../hotschedules/<type_method>?

Note: Results are currently cached with a TTL of 60 minutes.

What is TTL? Time to live or hop limit is a mechanism that limits the lifespan or lifetime of data in a computer or network

getConcepts

This method returns a list of concepts for a company.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/getConcepts"

Sample JSON response:

[
    {
        "extId": 3714,
        "name": "HotSchedules"
    }
]
Key Type Description
extId Number Concept external ID
name String Concept Name

getDriversByInterval

This method will take a concept ID, store number, start and end dates, volume type, and data type and return a list of total driver amount for each interval in the date range requested for that concept, store and labor type.

Intervals are configured during initial setup for the customer and are typically 30 minutes or 15 minutes.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept
startDate hsSimpleDate Start date for the range of data requested
endDate hsSimpleDate End date for the range of data requested
volumeType driverClass Classification of driver requested. Allowed types would be all of the classifications supported from API, HSC, or FTP integration. “Guests”, “Tables”, “Entrees”, “Deliveries”, “Transactions” and “Products”
dataType driverType Type of driver requested. Allowed types are “ACTUAL”, “ADJ_FORECASTED”, and “PRE_ADJ_FORECASTED”

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getDriversByInterval?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016&volume_type=TABLE&data_type=ACTUAL"

Sample JSON response:

[
    {
        "companyExtRef": 264319,
        "conceptExtRef": 3714,
        "driverAmount": 0,
        "driverClass": "TABLE",
        "driverType": "ACTUAL",
        "intervalEndDate": {
            "day": 1,
            "month": 10,
            "year": 2017
        },
        "intervalEndTime": {
            "hours": 0,
            "militaryTime": true,
            "minutes": 30,
            "seconds": 0
        },
        "intervalStartDate": {
            "day": 1,
            "month": 10,
            "year": 2017
        },
        "intervalStartTime": {
            "hours": 0,
            "militaryTime": true,
            "minutes": 0,
            "seconds": 0
        },
        "storeExtRef": 98
    }
]
Key Type Description
driverAmount Number Quantity of driver for interval expressed in the record
driverClass String Description of driver type supplied for the interval expressed in the record
intervalStartTime Object The hour, minutes, and seconds corresponding to the start of the interval expressed in the record. Interval times are local to the store’s time zone
intervalEndTime Object The hour, minutes, and seconds corresponding to the end of the interval expressed in the record. Interval times are local to the store’s time zone
intervalStartDate Object The date corresponding to the start of the interval expressed in the record
intervalEndDate Object The date corresponding to the end of the interval expressed in the record
conceptExtRef Number The concept ID configured by HotSchedules for the concept of the store owning the data of the record., contact HotSchedules if Concept IDs need to be defined or configured
storeExtRef Number The store ID configured within HotSchedules for the store owning the data of the record., contact HotSchedules if Store IDs need to be defined or configured
companyExtRef Number The company ID defined by HotSchedules for the store owning the data of the record., contact HotSchedules if the Company ID needs to be defined. This ID cannot be customized or configured
driverType String Type of driver requested. Allowed types are: “ACTUAL” - Corresponds to the actual values produced by the store. “ADJ_FORECASTED”- Corresponds to the final forecasted driver amount that the schedules were based off from for the driver. “PRE_ADJ_FORECASTED”- Corresponds to the original forecasted driver amount previous to any forecast adjustments

getEmpAvailability

This method takes in a concept ID and a store ID and returns an array of wsEmpAvailability objects. It is meant to get a list of all employee availability for that store.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept
active_only Boolean Boolean that defines whether or not to include terminated employees in response

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getEmpAvailability?active_only=true"

Sample JSON response:

[
    {
        "availabilities": [
            {
                "dayName": "Sunday",
                "dayNum": 1,
                "parHoursMax": -1,
                "parHoursMin": -1,
                "parShiftsMax": -1,
                "parShiftsMin": -1,
                "partialBeforeAfter": null,
                "partialTime": null,
                "shiftId": 1582006201,
                "shiftName": "AM",
                "statusName": "Not Available",
                "statusNum": 3
            },
            {
                "dayName": "Sunday",
                "dayNum": 1,
                "parHoursMax": -1,
                "parHoursMin": -1,
                "parShiftsMax": -1,
                "parShiftsMin": -1,
                "partialBeforeAfter": null,
                "partialTime": null,
                "shiftId": 1582006202,
                "shiftName": "PM",
                "statusName": "Not Available",
                "statusNum": 3
            }
        ],
        "empHrId": -1,
        "empNum": 9801
    }
]
Key Type Description
empNum Number Employee POS ID
availabilities Array Returns an array of availability for an employee
empHrId Number Employee HR ID

getEmpInfo

This method takes in a concept ID and a store ID and returns an array of wsEmpInfo objects. It is meant to get a list of all employees for that store.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
active_only Boolean Boolean that defines whether or not to include terminated employees in response.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getEmpInfo?active_only=true"

Sample JSON response:

[
    {
        "accountCreated": "2017-05-04T10:18:46.957-05:00",
        "empHrId": -1,
        "empNum": -1,
        "lastUpdated": "2017-05-04T10:18:47.040-05:00",
        "permissionSetName": "Default HotSchedules Employee"
    },
    {
        "accountCreated": "2017-07-07T10:05:48.820-05:00",
        "assignedSchedules": {
            "extId": -1,
            "hsId": 1050941698,
            "name": "FOH"
        },
        "empHrId": -1,
        "empNum": 9898,
        "lastUpdated": "2017-10-13T13:59:36.523-05:00",
        "permissionSetName": "Employee"
    },
    {
        "accountCreated": "2017-05-04T10:18:46.817-05:00",
        "empHrId": -1,
        "empNum": -1,
        "lastUpdated": "2017-07-07T10:00:20.487-05:00",
        "permissionSetName": "Default HS Support User"
    },
    {
        "accountCreated": "2017-10-13T12:48:57.903-05:00",
        "assignedSchedules": {
            "extId": -1,
            "hsId": 1050941698,
            "name": "FOH"
        },
        "empHrId": -1,
        "empNum": 9801,
        "lastUpdated": "2017-10-13T12:50:58.597-05:00",
        "permissionSetName": "Employee"
    }
]
Key Type Description
lastUpdated String Last time the employee record was updated
accountCreated String Date/time the account was created
permissionSetName String Permission set name assigned to the employee
empNum Number Employee POS ID
assignedSchedules Array The schedule in which the employee is assigned. Array contains extId, hsId and name
empHrId Number Employees HR ID

getEmpJobs

This method takes in a concept ID and a store ID and returns an array of wsEmpJob objects. It is meant to get a list of all jobs assigned to all employees for that store.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getEmpJobs?active_only=true"

Sample JSON response:

[
    {
        "clientId": 25124840,
        "hsEmpId": 587378309,
        "hsJobId": 27134060,
        "ovtWage": 22.5,
        "posEmpId": 9898,
        "posJobId": 1099,
        "primary": true,
        "regWage": 15,
        "storeNum": 98
    }
]
Key Type Description
hsJobId Number HotSchedules internal job code ID
clientId Number Unique identifier for client provided via HotSchedules
regWage Number Regular hourly wage rate for employee
posEmpId Number POS numeric ID for employee
hsEmpId Number HotSchedules internal employee account ID
storeNum Number Unique numeric store ID within HotSchedules, generally set up to mirror the client internal store IDs
ovtWage Number Overtime hourly wage rate for employee
posJobId Number POS numeric ID for the job code
primary Boolean Boolean flag to designate if the job code is the primary job for the employee

getGroups

This method takes in a concept ID and returns group information for the concept.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/getGroups"

Sample JSON response:

[
    {
        "conceptExtId": 3714,
        "extId": 0,
        "name": "My Group Name"
    }
]
Key Type Description
conceptExtId Number Concept external ID
extId Number Group external ID
name String Group name

getGuestCounts

This method will take a concept ID, store number, start and end dates and return a list of guest counts for the date range requested.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
start dateTime Start date for the range of data requested. This is a basic dateTime object.
end dateTime End date for the range of data requested. This is a basic dateTime object.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getGuestCounts?start_date=2016-04-30T00:00:00&end_date=2016-05-03T00:00:00"

Sample JSON response:

[
    {
        "businessDate": "2017-02-05T00:00:00-06:00",
        "dateTime": "2017-02-05T05:41:00-06:00",
        "guestCount": 8,
        "rvcExtId": 1
    },
    {
        "businessDate": "2017-03-05T00:00:00-06:00",
        "dateTime": "2017-03-05T05:41:00-06:00",
        "guestCount": 18,
        "rvcExtId": 1
    }
]
Key Type Description
businessDate String Business date of transaction
dateTime String Date time of the transaction
guestCount Number Number of guests for the transaction
rvcExtId Number Represents the numeric revenue center ID associated with the guest

getLaborByBusDay

This method will take a concept ID, store number, start and end dates and a labor type and return a list of total labor by job code for each interval in the date range requested for that concept, store and labor type.

Intervals are configured during initial setup for the customer and are typically 30 minutes.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept
start hsSimpleDate Start date for the range of data requested
end hsSimpleDate End date for the range of data requested
laborType laborType Type of labor requested. Allowed types are “optimal”, “forecasted” and “scheduled”.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getLaborByBusDay?start_day=30&start_month=1&start_year=2016&end_day=5&end_month=5&end_year=2016&labor_type=optimal"

Sample JSON response:

[
  {
    "interval": {
      "intervalDate": {
        "day": 1,
        "month": 2,
        "year": 2016
      },
      "intervalTime": {
        "hours": 0,
        "militaryTime": true,
        "minutes": 0,
        "seconds": 0
      },
      "laborType": "forecasted",
      "volume": 0
    }
  }
]  
Key Type Description
intervalDate Object Date expressed in the record
intervalTime Object The hour, minutes, and seconds expressed in record
laborType String Type of labor requested. Allowed types are “optimal”, “forecasted” and “scheduled”.
volume String Number of employees based on demand at that interval

getLaborByJobAndInterval

This method will take a concept ID, store number, start and end dates and a labor type and return a list of total labor by job code for each interval in the date range requested for that concept, store and labor type.

Intervals are configured during initial setup for the customer and are typically 30 minutes.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
start hsSimpleDate Start date for the range of data requested
end hsSimpleDate End date for the range of data requested
laborType laborType Type of labor requested. Allowed types are “optimal”, “forecasted” and “scheduled”.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getLaborByJobAndInterval?start_day=30&start_month=1&start_year=2016&end_day=5&end_month=5&end_year=2016&labor_type=optimal"

Sample JSON response:

[
  {
    "interval": {
      "intervalDate": {
        "day": 1,
        "month": 2,
        "year": 2016
      },
      "intervalTime": {
        "hours": 12,
        "militaryTime": true,
        "minutes": 0,
        "seconds": 0
      },
      "laborType": "scheduled",
      "volume": 0
    }
  }
]
Key Type Description
intervalDate Object Date expressed in the record
intervalTime Object The hour, minutes, and seconds expressed in record
laborType String Type of labor requested. Allowed types are “optimal”, “forecasted” and “scheduled”.
volume String Number of employees based on demand at that interval

getSalesItemsV3

This method takes in a concept ID, store ID, start and end dates.It returns an array of sales for that store.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
start hsSimpleDate First day of projected sales requested. This is an hsSimpleDate object.
end hsSimpleDate Last day of projected sales requested. This is an hsSimpleDate object.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getSalesItemsV3?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016"

Sample JSON response:

[
  {
    "clientId": 1234567,
    "empId": 7,
    "extId": -3,
    "rvc": 1,
    "rvcName": "TAKE OUT",
    "salesCat": 1,
    "storeNum": 13,
    "ttl": 7.99,
    "businessDate": {
      "day": 30,
      "month": 4,
      "year": 2016
    },
    "transDate": {
      "day": 30,
      "month": 4,
      "year": 2016
    },
    "transTime": {
      "hours": 7,
      "militaryTime": true,
      "minutes": 33,
      "seconds": 0
    }
  }
]
Key Type Description
clientId Object Business Date information, Day, Months and Year
empId Array Array of the day part total. Start Time and End Time
extId Number Optional-Unique transaction ID for the sales item
rvc Number Revenue center
rvcName String Name for the revenue center associated with the location within the restaurant
salesCat Number Sales category
storeNum Number Store number
ttl Number Total sales for the sales category
businessDate Object Business Date information, Day, Months and Year
transDate Object Transaction data
transTime Object Transaction time

getProjectedSalesV3

This method will take a concept ID, store number, start and end dates. This method uses hsSimpleDate objects for dates and hsSimpleTime objects for times.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
start hsSimpleDate First day of projected sales requested. This is an hsSimpleDate object.
end hsSimpleDate Last day of projected sales requested. This is an hsSimpleDate object.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getProjectedSalesV3?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016"

Sample JSON response:

  [
    {
      "businessDate": {
        "month": 4,
        "year": 2016,
        "day": 30
      },
      "dayPartTotals": [
        {
          "summaryItemTotals": {
            "summaryItemTotal": 5246.26,
            "summaryItemName": "Take out Drive through"
          },
          "dayPartEndTime": {
            "hours": 4,
            "seconds": 0,
            "amPm": "pm",
            "militaryTime": true,
            "minutes": 0
          },
          "dayPartName": "Evening",
          "dayPartTotal": 5246.26,
          "dayPartStartTime": {
            "hours": 18,
            "seconds": 0,
            "amPm": "am",
            "militaryTime": true,
            "minutes": 0
          }
        }
      ],
      "dateTotal": 9934.779
    }
  ]
Key Type Description
businessDate Object Business Date information, Day, Months and Year
dayPartTotals Array Array of the day part total. Start Time and End Time
dateTotal Number Total projected sales for the day part

getRCVs

Revenue center information defined for a group.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getRCVs"

Sample JSON response:

  [
    {
      "revenueCenterName": "Take Out",
      "extId": 0,
      "groupLevel": true
    },
    {
      "revenueCenterName": "Drive Thru",
      "extId": 1,
      "groupLevel": true
    },
    {
      "revenueCenterName": "Beverage",
      "extId": 2,
      "groupLevel": true
    }
  ]
Key Type Description
revenueCenterName String Revenue center name
extId Number Revenue center ID
groupLevel Boolean Indicates if the revenue center was created at a group level

getSalesCats

This method takes in a concept ID and a store ID and returns an array of sales categories for that store. Sales categories will typically establish what kind of item was sold: Food, Beverage, Alcohol, Merchandise.Sales categories can be local to a particular store, or defined in HotSchedules as belonging to an entire group (called group-level sales categories).

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getSalesCats"

Sample JSON response:

  [
    {
      "salesCategoryName": "Beverages",
      "extId": 1,
      "groupLevel": true
    }
  ]
Key Type Description
salesCategoryName String Name of the sales category
extId Number External ID associated with the category
groupLevel Boolean Indicates if the revenue center was created at a group level

getScheduleV3

This method takes in a concept ID, store ID, start and end dates. It returns an array of WSScheduleItem3 objects, which represent one scheduled shift each, for import into the POS. This method returns the same data as getSchedule, plus extended scheduled shift data, including location ID, regular pay rate, OT pay rate, scheduled regular minutes, scheduled OT minutes (if any), scheduled special pay (if any) and the unique schedule ID, internal to HS.This method uses hsSimpleDate objects for dates.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
start hsSimpleDate First day of scheduled shifts you are requesting. This method uses hsSimpleDate objects for dates.
end hsSimpleDate Last day of scheduled shifts you are requesting. This method uses hsSimpleDate objects for dates.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getScheduleV3?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016"

Sample JSON response:

  [
      {
     "inDate": {
       "month": 5,
       "year": 2016,
       "day": 2
     },
     "inTime": {
       "hours": 9,
       "seconds": 0,
       "militaryTime": true,
       "minutes": 0
      },
      "outDate": {
       "month": 5,
       "year": 2016,
       "day": 2
     },
     "outTime": {
       "hours": 18,
       "seconds": 0,
       "militaryTime": true,
       "minutes": 0
      },
     "jobHsId": 1111111,
     "payRate": 1,
     "specialPay": 0,
     "empHSId": 222222,
     "ovtMinutes": 0,
    }  
  ]
Key Type Description
outDate Object Schedules out date
jobHsId Number HotSchedules internal job code ID
payRate Number Regular hourly pay rate for employee
inDate Object Scheduled in date
specialPay Number Special Pay amounts
empHsId Number HotSchedules internal employee account ID
ovtMinutes Number Total Overtime Minutes for employee
inTime Object Scheduled in time
outTime Object Scheduled out time

getShiftsV3

This method takes in a concept ID, store ID, start and end dates and three flags (isHouse, isScheduled and isPosted). It returns an array of WSScheduleItem3 objects, which represent one scheduled shift each. What shifts are returned depends on the flags set:

This method returns extended scheduled shift data, including location ID, regular pay rate, OT pay rate, scheduled regular minutes, scheduled OT minutes (if any), scheduled special pay (if any) and the unique schedule ID, internal to HS.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy
isHouse Boolean Include house shifts? These are shifts which were never assigned to someone on a schedule, or were once assigned but removed from an employee when their status, job, etc. changed.
isScheduled Boolean Include scheduled shifts? These are shifts which are on a schedule that has been saved in HotSchedules, but might not have been posted
isPosted Boolean These are shifts that are in schedules that have been set to the 'posted’ status within HotSchedules.
jobCodes IntArray Integer array of job codes to be included in this method’s return. if this parameter is null or empty, all jobs will be included.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getShiftsV3?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016&is_house=true&is_scheduled=true&is_posted=true"

Sample JSON response:

  [
    {
      "empHSId": -1,
      "empPosId": -1,
      "jobHsId": 786323133,
      "jobPosId": 11,
      "inDate": {
        "day": 5,
        "month": 5,
        "year": 2016
      },
      "outDate": {
        "day": 5,
        "month": 5,
        "year": 2016
      },
      "inTime": {
        "hours": 9,
        "militaryTime": true,
        "minutes": 0,
        "seconds": 0
      },
      "outTime": {
        "hours": 16,
        "militaryTime": true,
        "minutes": 0,
        "seconds": 0
      },
      "weekStart": {
        "day": 2,
        "month": 5,
        "year": 2016
      },
      "weekEnd": {
        "day": 8,
        "month": 5,
        "year": 2016
      },
      "locationId": 787124196,
      "scheduleId": 781691586,
      "payRate": 0,
      "ovtRate": 0,
      "ovtMinutes": 0,
      "regMinutes": 420,
      "specialPay": 0
    }
  ]
Key Type Description
empHsId Number HotSchedules internal employee account ID
empPosId Number POS numeric Employee ID
jobHsId Number HotSchedules internal job code ID
jobPosId Number POS job code ID
inDate Object Scheduled in date
outDate Object Schedules out date
inTime Object Scheduled in time
outTime Object Scheduled out time
weekStart Object Start date of the work week
weekEnd Object End date of the work week
locationId Number Location ID
scheduleId Number Schedule ID
payRate Number Regular hourly pay rate for employee
ovtRate Number overtime pay rate
ovtMinutes Number Total overtime minutes for employee
regMinutes Number total regular minutes for employee
specialPay Number Special Pay amounts

getStoreEmployees

This method takes in a concept ID, store ID, a flag to determine if only active employees are returned, and returns an array of WSEmployee objects.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
active_only Boolean Boolean that defines whether or not to include terminated employees in response.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getStoreEmployees?active_only=true"

Sample JSON response:

[
    {
      "zipCode": 12345,
      "hireDate": "2016-11-03T10:16:38.533-05:00",
      "address": "111 Addy Way",
      "clientId": 87654321,
      "LName": "Lockman",
      "address2": "Unit 3",
      "city": "Austin",
      "mobile": "(222) 222-2222",
      "NName": "Jay",
      "altId": -1,
      "FName": "Harrison",
      "empNum": -1,
      "phone": "(333) 333-3333",
      "hsId": 987654321,
      "dob": "1981-09-16T00:00:00-05:00",
      "state": "TX",
      "storeNum": 3,
      "email": "harrison.lockman@email.com",
      "status": 1
    }
]
Key Type Description
zipCode Number Zip Code
hireDate String Employee Hire Date
address String Employee Address line 1
clientId Number Unique identifier for client provided via HotSchedules
LName String Employee Last Name
address2 String Employee Address line 2
city String City field for Address
mobile String Employees Mobile Phone
NName String Employee Nickname
altId Number Employee HR ID. This must be a unique value across the company. It is used for HotSchedules Shared Employees.
FName String Employee First Name
empNum Number Employee POS ID
phone String Phone Number
hsId Number HS unique ID of an employee that is assigned at the time the employee is created in HS. This number is not configurable but automatically assigned. This number can be obtained through the get method and is an option to include in the set. However this is not necessary
dob String Date of birth
state String State
storeNum Number Unique numeric store ID within HotSchedules. Generally set up to mirror the client internal store IDs.
email String Employee’s email address
status Number Active = 1, Inactive = 0, Terminated = -1

getStoreJobs

This method takes in a concept ID and a store ID, and returns an array of all jobs currently defined in HotSchedules for the given concept/store.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getStoreJobs"

Sample JSON response:

  [
    {
      "jobName": "Manager",
      "posId": 11,
      "clientId": 14935376,
      "hsId": 786323133,
      "defRate": 0,
      "storeNum": 3
    }
  ]
Key Type Description
jobName String Name for Job Code
posId Number Numeric POS ID for Job Code
clientId Number Unique identifier for client provided via HotSchedules
hsId Number HS unique ID of an employee that is assigned at the time the employee is created in HS. This number is not configurable but automatically assigned. This number can be obtained through the get method and is an option to include in the set. However this is not necessary
defRate Number Default Pay Rate for a Job Code

getStoresV2

Returns information about the stores within a group.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
group_id Number Group in which the store is assigned

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/getStoresV2?group_id=0"

Sample JSON response:

  [
    {
      "groupName": "HS Grill",
      "active": true,
      "groupExtId": 1,
      "storeName": "Sales Demo - Bug Test",
      "storeNum": -1,
      "city": "Fremont",
      "postalCode": "94555",
      "stateProvince": "CA",
      "streetAddress1": "1 st. address",
      "streetAddress2": "Unit 3",
      "timeZone": "US/Central"
    }
  ]
Key Type Description
groupName String Name of the group
active Boolean Indicates if the store is active
groupExtId Number The external ID for the store
storeName String The name of the store
storeNum Number Unique numeric store ID within HotSchedules. Generally set up to mirror the client internal store IDs.
city String City
postalCode Number Zip code / postal code
stateProvince String State province
streetAddress1 String Main street adress
streetAddress2 String Apartment number, Suite, Unit, etc..
timeZone String Store timezone

getTimeCards

This method takes in a concept ID, store ID, start and end dates. It returns an array of wsTimeCard3 objects, which represent one employee time card each. Each time card has information for one employee punch record, including business date, regular and OT minutes and wages, clock in and clock out times. If this store is using HotSchedules’ web-based timeclock for employee clock-in, any open punches in the date range are also included in the response.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getTimeCards?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016"

Sample JSON response

[
    {
      "jobName": "Bartender",
      "ovtTtl": 0,
      "ovtHrs": 0,
      "clockOut": "2016-05-01T23:48:00-05:00",
      "regWage": 0,
      "clockIn": "2016-05-01T16:36:00-05:00",
      "ovtWage": 7.5,
      "breakMinutes": 0,
      "jobExtId": 18,
      "jobId": -1,
      "businessDate": {
        "month": 5,
        "year": 2016,
        "day": 1
      },
      "regHrs": 7.2,
      "spcTtl": 7.25,
      "hsId": 929931332168,
      "spcHrs": 0,
      "ovtMins": 0,
      "extId": -2005922,
      "storeNum": 3,
      "empPosId": 2068,
      "regTtl": 0
    }
]
Key Type Description
jobName String POS job code name
ovtTtl Number Optional-Overtime total pay amount
ovtHrs Number Optional-Overtime hours in shift
clockOut String Clock out timestamp for the shift
regWage Number Regular hourly pay rate
clockIn String Clock in timestamp for the shift
ovtWage Number Optional-Overtime hourly pay rate
breakMinutes Number Number of non-paid break minutes in shift
jobId Number POS numeric identifier for the job
jobExtId Number POS numeric Job Code ID
businessDate Array Business Date information, Day, Months and Year
regHrs Number Regular hours represented in shift
spcTtl Number Optional-Special Pay total pay amount
hsId Number Optional-Internal HotSchedules employee Account ID. Not required, will be set by the service.
spcHrs Number Optional-Special Pay Hours
ovtMins Number Optional-Overtime minutes in shift
storeNum Number Unique numeric store identifier. Generally set up to mirror the client internal store ID.
empPosId Number POS numeric Employee ID
regTtl Number Regular total pay amount
extId Number Optional-Unique transaction ID for the time card record

getTimeCardsV2

Same as getTimeCards but additionally provides double time info for each timecard.

getTimeCardsDeclaredTips

This method takes in a concept ID, store ID, start and end dates. It returns an array of wsTimeCard3 objects, which represent one employee time card each. Each time card has information for one employee punch record, including business date, regular and OT minutes and wages, clock in, clock out times and declared tips. If this store is using HotSchedules’ web-based timeclock for employee clock-in, any open punches in the date range are also included in the response.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getTimeCardsDeclaredTips?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016"

Sample JSON object

  [
    {
      "breakMinutes": 0,
      "empPosId": 4067,
      "extId": -2031248,
      "hsId": 929931332583,
      "jobExtId": 18,
      "jobId": -1,
      "jobName": "Bartender",
      "ovtHrs": 0,
      "ovtMins": 0,
      "ovtTtl": 0,
      "ovtWage": 6.75,
      "regHrs": 5.1,
      "regTtl": 22.95,
      "regWage": 4.5,
      "spcHrs": 0,
      "spcTtl": 0,
      "storeNum": 2,
      "businessDate": {
      "day": 30,
      "month": 4,
      "year": 2016
      },
      "clockIn": "2016-04-30T09:29:00-05:00",
      "clockOut": "2016-04-30T14:35:00-05:00",
      "declaredTips": 0
    }
  ]
Key Type Description
jobName String POS job code name
ovtTtl Number Optional-Overtime total pay amount
ovtHrs Number Optional-Overtime hours in shift
clockOut String Clock out timestamp for the shift
regWage Number Regular hourly pay rate
clockIn String Clock in timestamp for the shift
ovtWage Number Optional-Overtime hourly pay rate
breakMinutes Number Number of non-paid break minutes in shift
jobId Number POS numeric identifier for the job
jobExtId Number POS numeric Job Code ID
businessDate Array Business Date information, Day, Months and Year
regHrs Number Regular hours represented in shift
spcTtl Number Optional-Special Pay total pay amount
hsId Number Optional-Internal HotSchedules employee Account ID. Not required, will be set by the service.
spcHrs Number Optional-Special Pay Hours
ovtMins Number Optional-Overtime minutes in shift
storeNum Number Unique numeric store identifier. Generally set up to mirror the client internal store ID.
empPosId Number POS numeric Employee ID
regTtl Number Regular total pay amount
extId Number Optional-Unique transaction ID for the time card record
declaredTips Number Tip amount

getVolumeCounts

This method will take a concept ID, store number, start and end dates and a volume type and return a list of volume counts for the date range requested. Supported Volume Types are: “TABLES”, “ENTRÉE”, “GUESTS”, “DELIVERIES”, “PRODUCTS”, and “TRANSACTIONS”.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
volumeType volumeType Classification of driver requested. Allowed types would be all of the classifications supported from API, HSC, or FTP integration. “Guests”, “Tables”, “Entrees”, “Deliveries”, “Transactions” and “Products”.
start hsSimpleDate Start date for the range of data requested
end hsSimpleDate End date for the range of data requested

curl -X GET -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/getVolumeCounts?start_date=2015-04-30T00:00:00&end_date=2016-05-03T00:00:00&volume_type=TABLE"

Sample JSON response:

  [
    {
      "dateTime": "2016-05-03T23:30:00-05:00",
      "volumeAmount": 5,
      "businessDate": "2016-05-03T00:00:00-05:00",
      "volumeType": "Guests",
      "rvcExtId": 0
    }
  ]
Key Type Description
dateTime String Date of business
volumeAmount Number Value of the volume count for the transaction
businessDate String Business Date information, Day, Months and Year
volumeType String Classification of driver requested. Allowed types would be all of the classifications supported from API, HSC, or FTP integration. “Guests”, “Tables”, “Entrees”, “Deliveries”, “Transactions” and “Products”.
rvcExtId Number Represents the numeric revenue center ID associated with the volume count

setTimeCardsV3

Extends dataTimeCard (includes business date and clock in and clockout date/times).

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setTimeCardsV3?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016" -d "[{ \"jobName\": \"Cook\", \"ovtTtl\": 0, \"ovtHrs\": 0, \"clockOut\": \"2016-07-31T22:05:00-05:00\", \"regWage\": 9, \"clockIn\": \"2016-07-30T15:56:00-05:00\", \"ovtWage\": 13.5, \"breakMinutes\": 0, \"jobId\": 16921407, \"businessDate\": { \"month\": 7, \"year\": 2016, \"day\": 31 }, \"regHrs\": 6.15, \"spcTtl\": 0, \"hsId\": 929931334634, \"spcHrs\": 0, \"ovtMins\": 0, \"storeNum\": 1, \"empPosId\": 1052, \"regTtl\": 55.35 }]"

Sample JSON object

  [
    {
      "jobName": "Cook",
      "ovtTtl": 0,
      "ovtHrs": 0,
      "clockOut": "2016-07-31T22:05:00-05:00",
      "regWage": 9,
      "clockIn": "2016-07-30T15:56:00-05:00",
      "ovtWage": 13.5,
      "breakMinutes": 0,
      "jobId": 16921407,
      "businessDate": {
        "month": 7,
        "year": 2016,
        "day": 31,
      },
      "regHrs": 6.15,
      "spcTtl": 0,
      "hsId": 929931334634,
      "spcHrs": 0,
      "ovtMins": 0,
      "storeNum": 1,
      "empPosId": 1052,
      "regTtl": 55.35
    }
  ]
Key Type Description
jobName String POS job code name
ovtTtl Number Optional-Overtime total pay amount
ovtHrs Number Optional-Overtime hours in shift
clockOut String Clock out timestamp for the shift
regWage Number Regular hourly pay rate
clockIn String Clock in timestamp for the shift
ovtWage Number Optional-Overtime hourly pay rate
breakMinutes Number Number of non-paid break minutes in shift
jobId Number POS numeric identifier for the job
jobExtId Number POS numeric Job Code ID
businessDate Array Business Date information, Day, Months and Year
regHrs Number Regular hours represented in shift
spcTtl Number Optional-Special Pay total pay amount
hsId Number Optional-Internal HotSchedules employee Account ID. Not required, will be set by the service.
spcHrs Number Optional-Special Pay Hours
ovtMins Number Optional-Overtime minutes in shift
storeNum Number Unique numeric store identifier. Generally set up to mirror the client internal store ID.
empPosId Number POS numeric Employee ID
regTtl Number Regular total pay amount
extId Number Optional-Unique transaction ID for the time card record

setEmpJobs

This method takes in a concept ID, store ID, and an array of WSEmpJob objects to assign jobs to individual employees. This method returns a WSReturn object.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setEmpJobs?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016" -d "[{json_object_1}, {json_object_2}, {json_object_3}...]"

Sample JSON object

  [
    {
      "hsJobId": 11878523,
      "clientId": 14935376,
      "regWage": 1,
      "posEmpId": 2069,
      "hsEmpId": 4177214,
      "storeNum": 3,
      "ovtWage": 1.5,
      "posJobId": 18,
      "primary": true
    }
  ]
Key Type Description
hsJobId Number HotSchedules internal job code ID
clientId Number Unique identifier for client provided via HotSchedules
regWage Number Regular hourly wage rate for employee
posEmpId Number POS numeric ID for employee
hsEmpId Number HotSchedules internal employee account ID
storeNum Number Unique numeric store ID within HotSchedules. Generally set up to mirror the client internal store IDs.
ovtWage Number Overtime hourly wage rate for employee
posJobId Number POS numeric ID for the job code
primary Boolean Boolean flag to designate if the job code is the primary job for the employee

setEmps

This method takes in a concept ID, store ID and an array of WSEmployee objects. Using the authentication from the username token and the conecpt and store IDs, the server will resolve which HotSchedules client this sync is for. The array of employees will be parsed on the server side to employees who need to be inserted or updated in the HS database. This method returns a WSReturn object.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
emps wsEmployeeArray Array of WSEmployee objects. Each object represents an employee at this store.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setEmps?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016" -d "[{json_object_1}, {json_object_2}, {json_object_3}...]"

Sample JSON object

[
    {
      "zipCode": 78681,
      "hireDate": "2017-08-03T10:16:38.533-05:00",
      "termDate": "2017-11-05T10:16:38.533-05:00",
      "address": "111 Addy Way",
      "clientId": 25124840,
      "LName": "Lockman",
      "address2": "Unit 3",
      "city": "Austin",
      "mobile": "(222) 222-2222",
      "NName": "Jay",
      "altId": -1,
      "FName": "Harrison",
      "empNum": -1,
      "phone": "(333) 333-3333",
      "hsId": 587378309,
      "dob": "1981-09-16T00:00:00-05:00",
      "state": "TX",
      "storeNum": 98,
      "email": "harrison.lockman@email.com",
      "status": 1
    }
  ]
Key Type Description
zipCode Number Zip Code
hireDate String Employee Hire Date
termDate String Employee Termination Date
address String Employee Address line 1
clientId Number Unique identifier for client provided via HotSchedules
LName String Employee Last Name
address2 String Employee Address line 2
city String City field for Address
mobile String Employees Mobile Phone
NName String Employee Nickname
altId Number Employee HR ID. This must be a unique value across the company. It is used for HotSchedules Shared Employees.
FName String Employee First Name
empNum Number Employee POS ID
phone String Phone Number
hsId Number HS unique ID of an employee that is assigned at the time the employee is created in HS. This number is not configurable but automatically assigned. This number can be obtained through the get method and is an option to include in the set. However this is not necessary
dob String Date of birth
state String State
storeNum Number Unique numeric store ID within HotSchedules. Generally set up to mirror the client internal store IDs.
email String Employee’s email address
status Number Active = 1, Inactive = 0, Terminated = -1

setForecastDriversV2

This method takes in a concept ID, store ID, workweek, startdate, enddate, starttime, endtime, volume amount, volume type, and a revenue center for the purpose of submitting forecasted volume drivers to HotSchedules from a third party system or point of sale. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains volume driver counts for a range of dates, corresponding to the start and end dates. The server side logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the guest are already in the HS database and do not need to be updated, then nothing will change.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setForecastDriversV2?start_day=30&start_month=4&start_year=2016" -d "[{json_object_1}, {json_object_2}, {json_object_3}...]"

Sample JSON object

  [
    {
      "concept": 1,
      "storeNum": 1,
      "workweekStartDate": {
        "day": 11,
        "month": 10,
        "year": 2016
      },
      "driverAmount": 10,
      "intervalStartDate" : {
        "day": 1,
        "month": 5,
        "year": 2016
      },
      "intervalEndDate": {
        "day": 11,
        "month": 10,
        "year": 2016
      },
      "intervalStartTime": {
        "amPm": "am",
        "hours": 0,
        "seconds": 0,
        "militaryTime": true,
        "minutes": 0
      },
      "intervalEndTime": {
        "amPm": "am",
        "hours": 0,
        "seconds": 0,
        "militaryTime": true,
        "minutes": 15
      },
      "rvcId": 1,
      "volumeType": "Guests"
    }
  ]
Key Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
workweekStartDate Object Start date of the work week
driverAmount Number Quantity of driver for interval expressed in the record
intervalStartTime Object The hour, minutes, and seconds corresponding to the start of the interval expressed in the record. Interval times are local to the store’s time zone.
intervalEndTime Object The hour, minutes, and seconds corresponding to the end of the interval expressed in the record. Interval times are local to the store’s time zone.
intervalStartDate Object The date corresponding to the start of the interval expressed in the record
intervalEndDate Object The date corresponding to the end of the interval expressed in the record
rvcId Number Numeric ID for the revenue center associated with the location within the restaurant
volumeType String Classification of driver requested. Allowed types would be all of the classifications supported from API, HSC, or FTP integration. “Guests”, “Tables”, “Entrees”, “Deliveries”, “Transactions” and “Products”.

setGuestCounts

This method takes in a concept ID, store ID, business date, date time, guest count and a revenue center for the purpose of submitting actual guest count drivers to HotSchedules from a third party system or point of sale. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains guest counts for a range of dates, corresponding to the start and end dates. The server-side logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the guest are already in the HS database and do not need to be updated, then nothing will change. This method returns a WSReturn object.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setGuestCounts?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016" -d "[{json_object_1}, {json_object_2}, {json_object_3}...]"

Sample JSON object

  [
    {
      "dateTime": "2016-05-03T23:30:00-05:00",
      "businessDate": "2016-05-03T00:00:00-05:00",
      "guestCount": 113,
      "rvcExtID": 123
    }
  ]
Key Type Description
businessDate String Business date of transaction
dateTime String Date Time of the transaction
guestCount Number Number of guests for the transaction
rvcExtID Number Numeric ID for the revenue center associated with the transaction

setRVC

This method takes in a concept ID and a store ID and returns an array of revenue centers for that store.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept
group Number Numeric ID group in which the store is assigned
rvcId Number Numeric ID for the revenue center associated with the location within the restaurant
rvcName String Name for the revenue center associated with the location within the restaurant.
i.e. Bar, Togo etc…
isGroupLevel Boolean Indicates if the revenue center is assigned at the group level.
i.e. Bar used across all locations

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setRVC?group=1&rvcId=1&rvcName=1&isGroupLevel=true" -d "[{json_object_1}, {json_object_2}, {json_object_3}...]"

Sample JSON object

[
    {
      "concept": 1,
      "group": 1,
      "isGroupLevel": true,
      "store": 13,
      "rvcId": 11,
      "rvcName": "Bar"
    }
]
Key Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
group Number Numeric ID group in which the store is assigned
rvcId Number Numeric ID for the revenue center associated with the location within the restaurant
rvcName String Name for the revenue center associated with the location within the restaurant.
i.e. Bar, Togo etc…
isGroupLevel Boolean Indicates if the revenue center is assigned at the group level.
i.e. Bar used across all locations

setSalesCat

This method allows you to add the sales category associated with menu items. Sales categories will typically establish what kind of item was sold: Food, Beverage, Alcohol, Merchandise. Sales categories can be local to a particular store.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
group Number Numeric ID group in which the store is assigned
salesCatId Number Numeric ID for the sales category associated with the location within the restaurant
salesCatName String Name for the sales category associated with the item sold within the restaurant.
i.e. Liquor, Beer, etc..
isGroupLevel Boolean Indicates if the sales category is assigned at the group level.
i.e. Liquor ID 2 used across all locations

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setSalesCat?group=1&salesCatId=1&salesCatName=1&isGroupLevel=true" -d "[{json_object_1}, {json_object_2}, {json_object_3}...]"

Sample JSON object

[
  {
    "concept": 1,
    "group": 1,
    "isGroupLevel": true,
    "store": 13,
    "salesCatId": 9,
    "salesCatName": "Liquor"
  }
]

Key Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
group Number Numeric ID group in which the store is assigned
salesCatId Number Numeric ID for the sales category associated with the location within the restaurant
salesCatName String Name for the sales category associated with the item sold within the restaurant.
i.e. Liquor, Beer, etc..
isGroupLevel Boolean Indicates if the sales category is assigned at the group level.
i.e. Liquor ID 2 used across all locations

setSalesItemsV4

This method takes in a concept ID, store ID, a start and end date and an array of WSSalesItem objects. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains sales items for a range of dates, corresponding to the start and end dates. The server-side logic can handle overlapping data (i.e. if you sync 7 days worth of sales, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the sales items are already in the HS database and do not need to be updated, then nothing will change. The method returns a WSReturn object. This method uses hsSimpleDate objects for dates.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setSalesItemsV4?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016" -d "[{json_object_1}, {json_object_2}, {json_object_3}...]"

Sample JSON object

[
    "concept": 1,
    "storeNum": 1,
    "sales": {
      "catName": "Beer",
      "clientId": 3,
      "empId": 123,
        "extId": 333,
        "rvc": "Revenue",
        "rvcName": "Bar",
        "salesCat": "Beer",
        "storeNum": 3,
        "ttl": 0,
        "businessDate": {
          "day": 1,
          "month": 7,
          "year": 2016
        },
        "transDate": {
          "day": 1,
          "month": 7,
          "year": 2015
        },
        "transTime": {
          "amPm": "am",
          "hours": 1,
          "militaryTime": true,
          "minutes": 15,
          "seconds": 0
        }
    },
      "start": {
        "day": 1,
        "month": 7,
        "year": 2016
      },
      "end": {
        "day": 1,
        "month": 8,
        "year": 2016
      }
]
Key Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept
catName String Category name
clientId Number Unique identifier for client provided via HotSchedules
empId Number Employee ID
extId Number External ID
rvc String Revenue Center
rvcName String Name for the revenue center associated with the location within the restaurant
salesCat String Sales category
ttl String Total sales for the sales category
businessDate Object Business Date information, Day, Months and Year
transDate Object Transaction date
transTime Object Transaction time
start Object Start date for the range of data requested
end Object End date for the range of data requested

setTimeCardsDeclaredTips

This method takes in a concept ID, store ID, a start and end date and an array of WSTimeCardsDeclaredTips objects. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains time cards for a range of dates, corresponding to the start and end dates. The server-side logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the time cards are already in the HS database and do not need to be updated, then nothing will change. This method returns a WSReturn object.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.
Day Number Day formatted dd
Month Number Month formatted mm
Year Number Year formated yyyy

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setTimeCardsDeclaredTips?start_day=30&start_month=4&start_year=2016&end_day=5&end_month=5&end_year=2016" -d "[{json_object_1}, {json_object_2}, {json_object_3}...]"

Sample JSON object

  [
    {
      "breakMinutes": 0,
      "empPosId": 4067,
      "extId": -2031248,
      "hsId": 929931332583,
      "jobExtId": 18,
      "jobId": -1,
      "jobName": "Bartender",
      "ovtHrs": 0,
      "ovtMins": 0,
      "ovtTtl": 0,
      "ovtWage": 6.75,
      "regHrs": 5.1,
      "regTtl": 22.95,
      "regWage": 4.5,
      "spcHrs": 0,
      "spcTtl": 0,
      "storeNum": 2,
      "businessDate": {
      "day": 30,
      "month": 4,
      "year": 2016
      },
      "clockIn": "2016-04-30T09:29:00-05:00",
      "clockOut": "2016-04-30T14:35:00-05:00",
      "declaredTips": 0
    }
  ]
Key Type Description
jobName String POS job code name
ovtTtl Number Optional-Overtime total pay amount
ovtHrs Number Optional-Overtime hours in shift
clockOut String Clock out timestamp for the shift
regWage Number Regular hourly pay rate
clockIn String Clock in timestamp for the shift
ovtWage Number Optional-Overtime hourly pay rate
breakMinutes Number Number of non-paid break minutes in shift
jobId Number POS numeric identifier for the job
jobExtId Number POS numeric Job Code ID
businessDate Array Business Date information, Day, Months and Year
regHrs Number Regular hours represented in shift
spcTtl Number Optional-Special Pay total pay amount
hsId Number Optional-Internal HotSchedules employee Account ID. Not required, will be set by the service.
spcHrs Number Optional-Special Pay Hours
ovtMins Number Optional-Overtime minutes in shift
storeNum Number Unique numeric store identifier. Generally set up to mirror the client internal store ID.
empPosId Number POS numeric Employee ID
regTtl Number Regular total pay amount
extId Number Optional-Unique transaction ID for the time card record
declaredTips Number Tip amount

setVolumeCountsV2

This method takes in a concept ID, store ID, business date, date time, volume amount, volume type, and a revenue center for the purpose of submitting actual volume drivers to HotSchedules from a third party system or point of sale. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains volume driver counts for a range of dates, corresponding to the start and end dates. The server-side logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the guest are already in the HS database and do not need to be updated, then nothing will change. This method returns a WSReturn object.

Query parameter Type Description
concept Number The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum Number Numeric (integer) identifier for the store. Must be unique within the concept.

curl -X PUT -H "Content-Type:application/json" -u <username>:<password> "https://api.hotschedules.io/<namespace>/controllers/vertx/hotschedules/<concept>/<storeNum>/setVolumeCountsV2" -d "[{json_object_1}, {json_object_2}, {json_object_3}...]"

Sample JSON object

  [
    {
      "businessDate": "2014-10-05T00:00:00",
      "dateTime": "2014-10-05T06:41:00-05:00",
      "rvcExtId": 4,
      "volumeAmount": 1,
      "volumeType": "GUESTS"
    }
  ]
Key Type Description
businessDate String Business date of transaction
dateTime String Date time of transaction
rvcExtId Number Represents the numeric revenue center ID associated with the guest
volumeAmount Number Value of the volume count for the transaction
volumeType String Classification of driver requested. Allowed types would be all of the classifications supported from API, HSC, or FTP integration. “Guests”, “Tables”, “Entrees”, “Deliveries”, “Transactions” and “Products”.

Agent Integration

Overview

The Agent provides a single integration point that enables in-store and near-store data collection.

The Platform provides real time bi-directional connections between the cloud and POS via existing Macromatix Livelink and HotSchedules Connect integrations, as well as an an in-store appliance and software agent.

The IoT Platform is built on open standards and integrates with:

Getting Started

The HotSchedules IoT Platform Agent provides a single integration point that enables in-store and near-store data collection. The Agent allows you to integrate with in store data, above store data and near store data.

alt text

Environment Setup

Installation

The agent cli is installed via a platform specific installer or via node package manager (NPM). The cli prefers to be installed globally.

$> npm install -g agent-cli

General Usage

The general structure of the a command is as follows:

$> npm install agent-cli [options] <action> [arguments]

Options

Options are prefixed with - or -- to separate them from arguments. Each action defines the options it uses, but the options are consistent in naming and usage across the commands.

Common Options

long short arg description
–help none none print help about the command
–verbose -v none print more detailed output
–quiet -q none print essential output
–config -f path specifies the agent’s configuration file
–home -h path specifies the agent’s working directory
–force -F none directive to override safety logic

Arguments

The cli interprets the first argument (non-option) as the action. All subseuqent arguements are command specific.

Each action is described below:

Informational Commands

help

The command line provides built in helper functions.

For a descriptive list of the commands

$> npm install agent-cli --help

Action Specific Help

Action specific help can be requested using the following structure.

$> npm install agent-cli <action> --help

version

Print version information.

$> agent-cli --version 
$> agent-cli -V

The output is a simple version identifier following the semantic versioning rules of major, minor, and build.

vM.m.b

info

CLI splash screen for the agent.

$> agent-cli info

Lifecycle Commands

Lifecycle commands allow an administrator to change and check the run state of an agent.

start

Attempts to start an agent.

$> agent-cli start [options] 

Options

long short arg deacription
–verbose -v none print more detailed output
–quiet -q none print essential output
–config -f path specifies the agent’s configuration file
–home -h path specifies the agent’s working directory

status

Provides status about a running agent.

$> agent-cli status [options] 

Options

long short arg deacription
–verbose -v none print more detailed output
–quiet -q none print essential output
–config -f path specifies the agent’s configuration file

stop

Gracefully shutdown the agent.

$> agent-cli stop [options] 

Options

long short arg deacription
–verbose -v none print more detailed output
–quiet -q none print essential output
–config -f path specifies the agent’s configuration file

Diagnostic Commands

Diagnostic commands are used by an admin to troubleshoot an agent having trouble entering a running state or to test environmental specific details uniformly across platforms.

check-core

Used to check the version of agent-core being used and where that file is located on the file system.

$> agent-cli check-core [options]

Options

long short arg deacription
–config -f path specifies the agent’s configuration file

check-config

Used to check for configuration problems in the agent. The agent will load and process all configuration files, but will not enter into a ready state. This command is safe to run even if there is a currently running agent.

$> agent-cli check-cofig [options]

Options

long short arg deacription
–config -f path specifies the agent’s configuration file

check-connection

Used to check for configuration problems in the agent.

$> agent-cli check-connection [options]

Options

long short arg deacription
–config -f path specifies the agent’s configuration file

The provided URL will go through the following checks:

  1. Check the URL format
  2. Check the DNS resolution from the agent’s host
  3. Check the TCP port is reachable by opening up a connection on host:port
  4. Issue a HTTP GET against the ping endpoint of the system

check-route

Used to check for network problems (firewalls & proxy rules) from the perspective of the agent runtime.

$> agent-cli check-route <scheme://host:port/path>

The provided URL will go through the following checks:

  1. Parse
  2. DNS resolve of host/IP
  3. TCP port reachable by opening up a connection on host:port
  4. If scheme is http of https then issue a HTTP GET against the specified URL

Installing Bodhi Agent

Agent Installer and Registration User Guide

Welcome to the User Guide for Installing and registering the Bodhi agent

System Requirements for computer OS: Windows XP SP3, Windows 7, Windows 8.1
Memory: 2GB or more
Disk Space: 10 GB

System requirements for Mobile iOS 7.x, 8.x
Android 4.x
Windows Phone

Step 1: Download Bodhi Installer and the Bodhi Mobile Application

Go developer.hotschedules.io to get the correct installer for your system

alt text

NOTE: if the system you are using to download the installer is not a Windows system you will get the Not Supported.

Just select the Windows system that matches the system you will be installer the Bodhi Agent on.

For the mobile applications here is where you can download them to your device.

Bodhi Mobile - iOS Apple Apps Store
Bodhi Mobile - Android Google Play Store

Step 2: Run the installer

alt text

Step 3: Select the Next button to move to the next Button

alt text

Step 4: License agreement screen

alt text

NOTE: the Next Button will be greyed out, until the, I accept the agreement radio button is selected.

Step 5: Select the I accept the agreement Radio Button

alt text

Step 6: Select the Next Button

alt text

Step 7: Selecting the Destination location for the Agent

alt text

NOTE: If this destination location is OK, then select the Next Button.

alt text

Go to Step 8

Step 7a: If you wish to change the location of the destination location
7a. Select the Browse Button

alt text

7b. Select the folder you wish to install the Bodhi Agent into or you can open a different folder.

alt text

7c. After you have selected the folder

alt text

7d. Select the OK Button

alt text

The New destination location should be displayed

alt text

7e. Select the Next Button to continue

alt text

Step 8: Review of Destination location.

alt text

Step 9: Select the Install Button

alt text

9a. A Progress bar will be displayed

alt text

Step 10: Installing Nodejs page

alt text

Step 11: Selecting the Next Button

alt text

Step 12: License agreement screen

alt text

NOTE: the Next Button will be greyed out, until the, I accept the agreement checkbox is selected.

Step 13: Select the I accept the agreement Radio Button

alt text

Step 14: Select the Next Button

alt text

Step 15: Selecting the Destination location for Nodejs

alt text

NOTE: If this destination location is OK, then select the Next Button.

alt text

Go to Step 16

Step 15a: If you wish to change the location of the destination location, Select the change Button

alt text

Step 15b. Select the folder you wish to install nodejs into or you can open a different folder

alt text

Step 15c. After you have selected the new folder

alt text

Step 15d. After you have selected the folder in the new selected folder

alt text

Step 15e. Select the OK Button

alt text

Step 15f. Review the Destination location

alt text

Step 16: Review of the Custom Setup.

alt text

Step 17: Select the Install Button

alt text

15h. A Progress bar will be displayed

alt text

alt text

alt text
figure 19

10b. Command Line Interface is opened

alt text
figure 20

10c. The command line window should close and you will be at the Desktop.

alt text
figure 21

Step 1: Register the Agent with a Mobile Device

Note: If your agent is not registered, it will be unable to send any data to the cloud

alt text
figure 22

Note: If the registration dialog is dismissed before registration * Select the Registration Code Menu item on the left to redisplay it

alt text
figure 23

Step 2: Start the Bodhi Mobile App

alt text
figure 24

Step 3: Enter the a Mobile Device

alt text
figure 25

Step 4: Select the POS Manager

alt text
figure 26

Step 5: Select the the Plus Sign to add a POS to the Manager

alt text
figure 27

Step 6: Select a store to associate the POS with.

Flowers figure 28

Step 7: Enter the Activation code that is displayed in the Browser.

alt text
figure 29

Step 8: Select the Request Button.

alt text
figure 30

Step 9: Verify that POS agent with the selected store and is displayed

alt text
figure 31

Step 20: The Browser will display the console dashboard

alt text
figure 32

Console Dashboard Legend

  1. This is the status of the agent (e.g. Online, Offline)
  2. This changes the Left Menu from Icon Only to Icons and Text

Congratulations on your successful installation of Bodhi Agent

Creating an Agent Application

Configuring Agent Application

Parameters

Mutable environmental variables that can be modified in Agent Manager. Values can overwrite default settings.

Property Type Description
description String Description in Agent manager application
type String Expected data type of parameter value
setting String Assigned variable name to this parameter
required Boolean True or False
default String The default value of the parameter if not set

Parameters example

parameters : {
        master_id: {
            description : 'System ID of Master Agent',
            setting     : 'master_id',
            type        : 'string',
            required    : true
        },
        role: {
            description : 'Role of Master Agent for Slave to assume',
            type        : 'string',
            setting     : 'role',
            required    : true
        }
}

Extensions

Extensions are injected dependencies that your application can refer to. Your application may use one or more extensions. Extensions can provide potential configuration components or actual runtime components. Extensions are a good way to design resuable components that can be shared and reused across projects. Extensions are loaded in the order in which they are specified.

Property Type Required Description
module String Yes By default searches node_modules folder. Relative path also accepted.

Extensions example

extensions  : [
        { module: './lib/plugin.js' },
        { module: 'agent-ext-timers' }
]

Settings

A Setting is an Object that represents static configuration data. Parameters can overwrite a setting if the property matches a parameter key. These values will take the highest precedence in the processing of settings. The precedence rules are:

  1. Agent.json settings object (highest precedence)
  2. Any settings within the js/json files in the settings folder
  3. Any settings added by an extension (lowest precedence)
Property Type Required Description
property String Yes Name of your property
value String, Function, Boolean, Number, Object Yes The value of your setting

Settings example

settings: [
        {
            property: 'master_id',
            value: '588f9fc508a94349cc1ad3b8'
        },
        {
            property: 'role',
            value   : 'pos-monitor'
        }
]

Counters

Tracks the number of times specific application events occur and are logged found in the Agent heartbeat. Each counter can subscribe to an array of application events.

Counters example

 counters: {
        activations : ['app:monitor'],
        success     : ['app:success'],
        stopped     : ['app:stopped'],
        failed      : ['app:failed' ]
}

Sources

An object that sources external events. Sources bind events to listeners and emits application level events. Any counters, handlers and pipelines subscribed to source events are initiated.

Property Type Required Description
name String Yes Unique identifier (within the context’s handler)
provider String or Function Yes A function or reference to a plugin that creates an object
args Array of Strings, Functions, Objects, Booleans Optional A list of dependencies used by the source
bindings Object Optional A Map that routes external events to internal topics
factory String Optional An enumeration that describes alternate instantiation behavior for the service constructor, function, literal

Sources example

sources: [ 
        {
           name: 'sampleSource',
           provider: 'compris:dir',
           args: ['$settings:rootPath'],
           bindings: { 'created' : 'read' }
        } 
]

Services

A Service is an Object that represents a concrete extension of the API. Services are singletons.

Property Type Required Description
name String Yes Unique identifier (within the context’s handler)
provider String or Function Yes A function or reference to a plugin that creates an object
args Array of Strings, Functions, Objects, Booleans Optional A list of the dependencies used by the service
factory String (Constructor, Function, Literal) Optional An enumeration that describes alternate instantiation behavior for the service

Services example

services: [
        {
            name: 'cloud',
            provider: 'connection:resources'
        }
]

Handlers

A Handler is a Function that responds to events within an application.

Property Type Required Description
name String Yes Unique identifier (within the context’s handler)
subscriptions Array Yes String of application level events that will initiate this handler
fn String or Function Yes A function or reference to a plugin will handle the events
props Object Optional A list of properties available to the instance

Handlers example

handlers: [
        {
            name            : 'Monitor Master Agent',
            subscriptions   : ['app:monitor'],
            fn              : '$plugins:handler:monitor',
            props           : {
                master_role : '$setting:role',
                conn        : '$service:cloud',
                master_id   : '$setting:master_id',
                getInfo     : '$plugins:core:info',
                identity    : '$plugins:core:identity',
            }
        },
        {
            name            : 'Update Agent Role',
            subscriptions   : ['app:update'],
            fn              : '$plugins:handler:update',
            props           : {
                conn        : '$service:cloud',
            }
        }
]

Pipelines

Similar to handlers, pipeline(s) are subscribed to event(s). The difference being that pipelines execute a series of steps rather than just one function. Each pipeline step should follow the single responsiblity principle. Each step is given two arguments - input and a callback.

Property Type Required Description
name String Yes Unique identifier
subscriptions Array Yes String of application level events that will initiate this pipeline
steps Array Yes Takes an array of objects described below
failed String Optional Emits mapped event based on the state of the pipeline
success String Optional Emits mapped event based on the state of the pipeline
done String Optional Emits mapped event based on the state of the pipeline

Pipeline.steps

pipeline | Object

Property Description
fn Functional plugin reference. See pipeline and fn description below
props Optional dependencies to be injected in the pipeline function context

Pipeline.fn(input, callback)

input | Object
Initially an empty object. Later becomes whatever the result of the previous pipeline step is.

callback | Function
Needs to be invoked with a possible error arguement and an optional result to be passed in to the next step. If an error is passed in, it will stop the pipeline and the failed event will be emitted.

Context of this callback includes core methods described below as well as Pipeline.props injected during configuration.

Property Description
logger Logs viewable in Agent Manager
publish EventEmitter that takes in a event and message
name Pipeline.name
event Name of event that triggered the pipeline

Pipelines example

// pipeline breakdown of handlers

    pipelines: [
        {
            name: 'Monitor Master Agent',
            subscriptions: ['app:monitor'],
            steps: [
                { fn: '$plugins:core:identity:addAgentInfo'     },
                { fn: '$plugins:main:checkMasterAgentStatus'    },
                { fn: '$plugins:main:processAgentStatus'        }
            ],
            stopped : 'app:stopped',
            failed  : 'app:failed'
        },
        {
            name: 'Update Status',
            subscriptions: ['app:update'],
            steps: [
                { fn: '$plugins:main:patchAgentRole'    },
                { fn: '$plugins:main:syncAgent'         }
            ],
            stopped : 'app:stopped',
            failed  : 'app:failed'
        }
]

Init

Init is a function that is given a callback as its only argument. This callback must be invoked in order to intialize the application. The keyword “this” refers to the application’s reactive context

Init example

init: function(done){

        this.publish('app:initialized');

        console.log('###################################');
        console.log('## ' + pkg.name.toUpperCase());
        console.log('## v' + pkg.version);
        console.log('###################################');

        done();
}

Creating an Agent Source

Returns a function that instantiates an Agent source. See sample code that watches for any directory changes using npm watch.

Sample Code:

var fs      = require('fs-extra');
var watch   = require('watch');

module.exports = function dirSrc() {
    var path        = arguments[0];
    var source      = {};
    source.routers  = {};

    var bind = function bindDir(bindings, emitter, done) {
        var logger = this.logger;

        logger.info('Ensuring ', path, 'exists...');

        if (!path) return done('Expected path to exist. Please ensure args array is properly configured.');

        fs.ensureDir(path, function (err) {
            if (err) return done(err);

            logger.info(path, 'ensured.');
            /*
                bindings = { 'created' : 'read' }
                emitter = fn()  { context.emit.apply(context, arguments); }
                done = fn()      { return exit(done, source); }

                YOU HAVE TO CALL DONE OR ELSE THE REST OF THE APP WILL NOT LOAD
                KICK LISTEN OR IT WILL NOT HEAR
            */

            // routes = ['created']
            var routes = Object.keys(bindings);

            /*
                routers = {

                        emitter(event, arguments);
                    }
                }
            */
            routes.forEach(function (event) {
                source.routers[event] = function () {
                    emitter(bindings[event], { path: arguments[0], detail: arguments[1] });
                }
            });

            done();
        });
    };

    /*
        SOURCES GET LOADED BEFORE INIT
            ENSURE DIR BEFORE SETTING MONITORS
    */
    var listen = function listenDir(cb) {
        watch.createMonitor(path, function (monitor) {
            source.monitor = monitor;
            ['created', 'changed', 'removed'].forEach(function (e) {
                if (source.routers[e]) {
                    source.monitor.on(e, function (file, detail) {
                        source.routers[e](file, detail);
                    });
                }
            });
        });
    };

    var close = function closeDir() {
        source.monitor.stop();
    };

    return function (cb) {
        cb(null, { bind: bind, listen: listen, close: close})
    }
};
Property Type Description
bind Function Responsible for binding application level events when a source level event occurs
listen Function Creates EventEmitter that emit application level events based on bind
close Function Destroy existing EventEmitter for the source

Creating an Agent Extension

Returns an Agent extension object.

Property Type Description
name String Name of extension used primarily for debugging purposes
attach Function Attach the specified extension to this instance, extending the ReactiveContext with new functionality with the implicit registerPlugin method

Sample Code:

module.exports = {
    name        : 'plugin',

    attach      : function (overloads, done) {

        /** LOAD HANDLERS **/
        this.registerPlugin(['handler', 'monitor'   ], require('./handlers/monitor.js'  ));
        this.registerPlugin(['handler', 'update'    ], require('./handlers/update.js'   ));

        done();
    }
};

Agent Path Resolution

Every extension, service and setting can be injected through namespacing

Type Reference Sample
extension “$plugins” “$plugins:myFunction”
service “$service” “$service:cloud”
setting “$setting” “$setting:jobInterval”

Job Engine

Creating a job engine application

Introduction
Bodhi Job Engine is a job scheduler running on node.js and MongoDB. The engine is designed to run scheduled cloud-to-cloud data transactions, e.g. requesting data from web APIs, pushing data to the Bodhi cloud, etc.

Work Functions
Jobs must be built in a specific format in order for Bodhi Job Engine to recognize and run them properly. The job should contain an index.js file that follows this structure:

index.js

module.exports = function work(context, done){
    //the work of your job
    done(errThatOccurred, messageToReport, stateToSave);
};

Context Object

Key Type Description
connection bodhi-js-client https://www.npmjs.com/package/bodhi-driver-superagent
settings Object immutable configuration options associated with this job
state Object mutable persistent state from previous runs
meta Object immutable metadata about the job

meta

{

}

Job Metadata

Key Type Description
name String name of the job
package String package name
version String semantic package version
namespace String namespace of the job
lastRun Data last time the job ran

Callback
A job must be completed by calling the callback

arg type required description
err Error optional if err != null then the job did not process properly
message String optional a string to be recorded in the message
state Object optional the state to persist for the next run

Example Job: Hello World

This is a very basic Hello World job.

module.exports = function(options, done){
  console.log('HELLO WORLD!');

  if(err){
    done(err);
  }
  else{
    done();
  }
};

Example Job: Get and Use Some Data

Get and use data

module.exports = function(options, done){

  var client = options.connection;
  var data   = options.state;
  data.storestuff = [];

  client.get(['resources', 'Store'].join('/'), function(err, data, ctx){
    if(err){
      done(err);
    }
    else{
      data.forEach(function(store){
        data.storestuff.push(store.store_name + ' is an awesome store!');
      });
    }
  });

  var json = {

    "data1": "some data you need to post",
    "data2": "also data you need to post"
  };

  client.post(['resources', 'aCustomType'].join('/'), json, function(err, data, ctx){

    if(err){
      done(err);
    }
    else{
      console.log('Server says: ', ctx);
      done();
    }
  });
};

This is a less basic example job that uses HTTP requests and stores data in the “state” property of the options object. Data stored in the state property persists between jobs and is available in the next execution of the job.

Publishing Applications

Overview

To publish application for the IoT Platform, you need to follow a few simple steps to describe your application.

Configuring package.json

To publish your application, add the following directory structure for your application:

    /<app-name>/
            /public/

To publish an app into the IoT Platform you have to zip up the following:
index.js
LICENSE
package.json

    folder=<public>
      app_icon.png
      NewType1.json file (optional)
      NewType2.json file (optional)
      NewType3.json file (optional)
      ...

Example package.json for Mobile Applications

By Clicking on HS Template you get a package.zip file that is downloaded to your desktop that contains the following:

package.json that gets includes with HS Template's zip file:

{
    "name": "HSappTemplate",
    "version": "0.0.0",
    "title": "HSappTemplate",
    "description": "New application Hello, World!",
    "profile": {
        "name": "HSappTemplate",
        "dml": {
            "BodhiApplication": {
                "select": {}
            }
        }
    },
    "settings": {
        "publisher": "",
        "categories": [""],
        "offline": false,
        "navigationBar": "auto",
        "location": "S3",
        "storage": "s3",
        "type":"mobile"
    },
    "dependencies": {
        "bodhi-mobile":"*" 
        },
    "autoUpdateVersion": true
}

Example of Package.json for agent or job Applications

Example of package.json for agent or job applications:
#!javascript

{
  "name": "app-package-name",
  "version": "0.0.1",
  "title": "Application Title",
  "description": "Short Application Description.",
  "profile": {
    "name": "app-package-name",
    "dml": {
      “BodhiApplication": {
       "select": {},
       "update":{},
       "delete":{},
       "insert":{}
      },
      "NewType1": {
        "select": {}
      },
      "NewType2": {
        "select": {}
      }
    }
  },
  "settings": {
    "categories": [
      "Aloha",
      "POS"
    ],
    "publisher": "your company",
    "npm_package_name": "app-package-name",


if you have any related apps you want to install together::
"related-apps": [
      "bodhi.aloha-app-transactions",
      "bodhi.aloha-app-store"
    ],
    "public_path": "public",
    "global_store_icon": "public/icon.png",
   "location": "S3",
   "storage": "s3",
   "type": "agent",    
(type can be “job”, “agent”, “mobile”, “web” )   
 "new_type_required": true,
  "install": {
"new": {
"model": [
{
"type": "enumeration",
"name": "TypeName",
"object": "Enumerations/TypeName.json"
},
{
"type": "embedded_type",
"name": "InventoryPurchaseOrder",
"object": "Types/InventoryPurchaseOrder.json"
},
{ "type": "custom_type",
"name": "TypeName2",
"object": "Types/TypeName2.json"
}
],
"post-type-install": [
{"action": "POST",
"object": "Data/DataFile.json",
"path": "/resources/DataFile"
}
]
if you have any parameters required to be used with the app we add this section:: 
 "agent_parameters": {
      "interval": {
        "description": "How often to execute a grind",
        "required": true,
        "type": "string",
        "default": "every 15 minutes",
        "position": 1
      }
    }
  },
  "autoUpdateVersion": false
}

Description of package.json contents

name=“HSappTemplate” required

The name of your application must match the name of the profile

“version”: “0.0.1” required

Ideally this is the version of your application that gets posted as versions show for Agent Application in the Agent Event Logs so keeping this version the same as your Agent Application that is published is highly recommended.

“title”: “Application Title” required

This is the title that will show on the HotSchedules Store once you publish your application to the HotSchedules Store.

“description”: “Short Application Description.” required

The description is the application description that will be displayed with the title for your application when displayed in the HotSchedules Store. Description will be part of “Learn More” button.

“profile”: {} required

The profile section contains the following required sections:

“settings”:{} required

The settings is the main section of package.json contains the following sections:

agent_parameters/job_parameters

Depending on your application needs, you may want to have parameters setup for your applications. Both Agent and Job applications can take parameters. The agent/job_parameters contain information about any parameters that the agent or job requires to run. They contain data_dir formatted information containing description, a required flag, type string and an optional position which is set will position the parameter in the order set 0, 1, 2, etc if not set then the parameter will be displayed in the order it’s defined. Application parameters will be saved under settings so the application should use parameters from settings.

NOTE: The hidden parameter option will not be visible to the user in the installation process but will be written under the application settings.

The following are examples of parameters that can be set for agent or the job applications respectively:

Agent Parameters example:

Example of agent parameters that can be defined for an agent application:

    "agent_parameters": {
      "config_file_path": {
        "description": "Config file location",
        "required": true,
        "type": "string",
        "default": "",
        "setting": "config_file_path"
      },
      "data_dir": {
        "description": "Folder location to save database files for the agent app",
        "required": true,
        "type": "string",
        "default": "C:/bodhiAgent/node_modules/merit-agent-labor/_xmloutput/",
        "setting": "data_dir"
      },
      "number_of_days_to_query": {
        "description": "Limit query to this number of days",
        "required": true,
        "type": "integer",
        "default": 60,
        "setting": "number_of_days_to_query"
      },
      "interval": {
        "description": "How often to execute a grind",
        "required": true,
        "type": "string",
        "default": "every 12 hours",
        "setting": "interval"
      },
      "local_storage_ignore_flag": {
        "description": "Ignore local storage and write all data",
        "required": true,
        "type": "boolean",
        "default": false,
        "setting": "local_storage_ignore_flag"
      }
    }
Job Parameters example:
    "job_parameters": {
      "timing_expression": {
        "description": "How often to execute a job",
        "repeat": true,
        "type": "string",
        "default": "60 minutes"
      },
      "brink_location": {
        "description": "The alpha numeric string provided by the Brink POS API to identify the store location, e.g. tSm8y1TMSk7J4ZMyQBpeTg==",
        "type": "string",
        "required": true,
        "setting": "brink_location"
      },
      "accessToken": {
        "description": "The alpha numeric string provided by the Brink POS API to authenticate the user",
        "type": "string",
        "required": true,
        "setting": "accessToken"
      },
      "uri": {
        "description": "The url for the Brink POS API service e.g. https://api2.brinkpos.net/",
        "type": "string",
        "required": true,
        "setting": "uri"
      }
    }

offline=true/false

Offline controls whether the container will cache application information for offline use. If offline=true and the user launches the application, any data that was previously loaded will be available when the device is offline. This will also enable queuing of data to write to the IoT Platform if the application has write permissions.

single_container_app=true/false

single_container_app tells the container know whether the app should be displayed with a menu (a collection of apps) or as a standalone single app. Bodhi Mobile has single_container_app = false. Bodhi Reveal has single_container_app = true

hide_from_global_store=true/false

hide_from_global_store controls whether the app is available to the general public to see in the global app store. Apps like Settings which cannot be removed should have hide_from_global_store=true

new_type_required=true/false

new_type_required tells the installer of the app in the global app store if the app will run 'out of the box’ or if new custom types need to be installed on the namespace. NOTE:: if new_type_required=true, troubleshooting_url should be required

screenshots{}

The screenshots array contains relative paths to screenshots which the Global App Store will use for display purposes. These files should be included in the app folder that is published and the path should be relative to the public_path.

data_dir:{}

The data_dir formatted information contains a description, a required flag, type string and an optional position which is set will position the parameter in the order set 0, 1, 2, etc if not set then the parameter will be displayed in the order it’s defined.

“autoUpdateVersion”: “false”

This flag prevents autoUpdate version of the app each time you publish. If you mark this false, you need to manually bump the version of the app each time you update it.

Example Type Definition

This is an example of an enumeration, embedded_type and custom_type.

NOTE: All enumerations must be declared first, embedded_type must be after enumerations and custom_types have to be defined after enumerations and embedded_types: This example shows the objects as folders under the application’s root directory. This is where you define your json for each type. There is a one to one correspondence of the type declared in package.json to the json defining that type in the folder under the application.

Defining your custom schema/types example:
"install": {
"new": {
"model": [
{
"type": "enumeration",
"name": "TypeName",
"object": "Enumerations/TypeName.json"
},
{
"type": "embedded_type",
"name": "InventoryPurchaseOrder",
"object": "Types/InventoryPurchaseOrder.json"
},
{ "type": "custom_type",
"name": "TypeName2",
"object": "Types/TypeName2.json"
}
],
"post-type-install": [
{"action": "POST",
"object": "Data/DataFile.json",
"path": "/resources/DataFile"
}
]

Adding Scripts and Versioning: “versions”: [..]

To make an application script available set the following in the settings section of your package.json:

Template for adding scripts/versions to package.json
versions:[
{
    "version": "<script_version>",
    "bundle": "<jar_name>",
    "pre-type-install": {
      "main": "<main_class_name>"
    },
    "post-type-install": {
      "main": "<main_class_name>"
    }
]
Example of versions/scripts using seed-data:
    "versions": [
      {
        "bundle": "installer.jar", 
        "post-type-install": {}, 
        "pre-type-install": {}, 
        "seed-data": [
          {
            "action": "POST", 
            "object": "Data/measurements.json", 
            "path": "/resources/InventoryUnitOfMeasure"
          }, 
          {
            "action": "POST", 
            "object": "Data/conversions.json", 
            "path": "/resources/InventoryUomConversion"
          }
        ], 
        "version": "new"
      }, 
      {
        "bundle": "upgrade-3.0.0.jar", 
        "post-type-install": {
          "main": "com.bodhi.vertx.appinstaller.script.DeveloperScript"
        }, 
        "version": "2.7.19"
      }
    ]

Publishing to shop

1 - Ensure that you have your package.json, LICENSE and index.html in the root folder of your application. Note that index.html can be an empty file.

2 - Zip/compress your files. Note that the files we are compressing are the files itself not the project folder.

3 - Login to Bodhi Shop: https://tools.hotschedules.io/shop/#/my

alt text

4 - Click Publish App.

alt text

5 - Upload zip file.

alt text

6 - Verify fields are correct then publish.

alt text

7a - Verify that your application is successfully published.

alt text

7b - Make sure your file is found in https://tools.hotschedules.io/file-upload/#/files. If it doesn’t exist refer back to configuring your package.json file

alt text

Monitoring Application

Logs can be found here: https://tools.hotschedules.io/job-engine-manager/#/jobs?filters=all,all

alt text

HotSchedules SOAP Web Services

Introduction

Note: This Documentation Is Currently Being Updated For This Environment

HotSchedules provides a Web Services API for client integration. This API can be used to exchange Employee, Labor and Sales information with HotSchedules directly, rather than via file exchange or HSConnect integration.

This API consists of a set of SOAP web services, implemented using the CXF framework. Calls to these services should be done via serialized data objects. Services will use a UsernameToken security header, which must be explicitly added by the third party before we will accept their web service calls. We will provide each company with a username and password for secure access to the API services.

Requesting a username/password

Please contact your HotSchedules account manager for a username/password.

Required SSL certificates

Our web services connect through an SSL encrypted connection, requiring a certificate to be present on the client side. HotSchedules uses DigiCert for our services.hotschedules.com SSL certificate. Because GoDaddy will not generate SSL certificates directly off of the root cert, we also require their intermediate certificate to be installed on the client. The certificates required can be downloaded directly from GoDaddy.

Download Location: https://certs.godaddy.com/anonymous/repository.seam

The two certificates required are,

Go Daddy Class 2 Certification Authority Root Certificate
gd•class2•root.crt
Certificate File Hash (sha1) : F0 EC B0 51 00 08 A3 1A D3 60 9A C8 C5 54 10 C3 9B F4 BA A2
Certificate Thumbprint (sha1) : 27 96 ba e6 3f 18 01 e2 77 26 1b a0 d7 77 70 02 8f 20 ee e4

Go Daddy Secure Server Certificate (Intermediate Certificate)
gd_intermediate.crt
Certificate File Hash (sha1) : 17 93 21 10 65 FA 24 D9 46 53 18 83 DE 62 CA 0F AE 4D 61 7D
Certificate Thumbprint (sha1) : 7C 46 56 C3 06 1F 7F 4C 0D 67 B3 19 A8 55 F6 0E BC 11 FC 44

Once you have the certificates downloaded, you must install them in your keystore. Here is an Oracle article explaining keystores as well as how to install a certificate into your keystore:

Oracle Certificate Installation HOW•TO
Generally, the keystore file is created in your installed JRE’s directory (/jre/lib/security). The default name is cacerts, and the default password is changeit. If you need to generate a new keystore file, see the following link for directions.

Apache SSL Configuration HOW•TO
Once the keystore is located in the /lib/security directory of your Java install, and the certificates are installed in the keystore, your code should be able to correctly navigate the SSL connection.

Available SOAP Web Services

The HotSchedules SOAP API provides a user-friendly way to obtain HS Data. Each service contains a sayHello call, a test method intended to be used to validate access to the service. It returns a text message indicating success.

CertificationService: This service is intended for third parties to be able to request and set certification requests from HotSchedules.

EmpService: This service provides operations for a third party to push or request employee and employee job data into HotSchedules.

LaborService: This service is intended for third parties to be able to request labor data from HotSchedules and import it into their POS/data warehouse/enterprise/etc.

OperatingBudgetPlanService: Allows a customer to SET their budget via API. The service also allow a customer to GET their labor budget data.

ProjectedSalesService: This service is intended for third parties to be able to grab projected sales data from HotSchedules and import it into their POS/data warehouse/enterprise/etc.

SalesService: This service is intended for third parties to be able to import their sales items into the HotSchedules system in a straightforward fashion. Currently there is only one method for setting sales items.

ScheduleService: This service is intended for third parties to be able to grab scheduled shifts from HotSchedules and import them into their POS/data warehouse/enterprise/etc.

TimeCardService: This service is intended for third parties to be able to import their time cards into the HotSchedules system or get time cards from HotSchedules in a straightforward fashion.

TimeOffService: This service is intended for third parties to be able to request approved timeoff requests from HotSchedules.

VolumeService: This service is intended for third parties to be able to request and send volume driver related data from/to HotSchedules. Driver items include examples such as guests, tables, entrees…. Etc.

CertificationService

This service is intended for third parties to be able to request and set certification requests from HotSchedules.

getClientCertifications

This method takes in a concept ID and a store ID and returns client certification objects. It is meant to get a list of all certifications for that store.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:cer="http://services.hotschedules.com/api/services/CertificationService">
   <soapenv:Header/>
   <soapenv:Body>
      <cer:getClientCertifications>
         <concept>1</concept>
         <storeNum>55</storeNum>
      </cer:getClientCertifications>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getClientCertificationsResponse xmlns:ns1="http://services.hotschedules.com/api/services/CertificationService">
         <return>
            <item>
               <certExtRef>-1</certExtRef>
               <certName>Team Member Alcohol Cert</certName>
               <certType>2</certType>
               <certTypeDescription>Expires Without AutoInactivation</certTypeDescription>
               <groupLevel>false</groupLevel>
            </item>
            <item>
               <certExtRef>-1</certExtRef>
               <certName>Alcohol Certification</certName>
               <certType>1</certType>
               <certTypeDescription>Expires With AutoInactivation</certTypeDescription>
               <groupLevel>false</groupLevel>
            </item>
         </return>
      </ns1:getClientCertificationsResponse>
   </soap:Body>
</soap:Envelope>

getEmployeeCertifications

This method takes in a concept ID, store ID and employee POS ID and returns an array of employee certificate objects. It is meant to get a list of all employee certification information for an employee for that store.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.
empPOSId Int 1..1 POS numeric employee ID.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
          xmlns:emp="http://services.hotschedules.com/api/services/CertificationService"
          xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
          <soapenv:Header>
                      <wsse:Security
                                  xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
                                  xmlns:wsu="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•utility•1.0.xsd" soapenv:mustUnderstand="1">
                                  <wsse:UsernameToken wsu:Id="UsernameToken•63A716DE011BE2D649145262747932814">
                                              <wsse:Username>laura1234!</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordText">laura 1234!</wsse:Password>
                                              <wsse:Nonce EncodingType="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•soap•message•security•1.0#Base64Bina ry">9iOMGex3ZDEpdw4xsAweWA==</wsse:Nonce>
                                              <wsu:Created>2016•01•12T19:37:59.328Z</wsu:Created>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </soapenv:Header>
          <soapenv:Body>
                      <cer:getEmployeeCertifications>
                                  <concept>1</concept>
                                  <storeNum>1</storeNum>
                                  <empPosId>100</empPosId>
                      </cer:getEmployeeCertifications>
          </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
          xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
          <soap:Body>
                      <ns1:getEmployeeCertificationsResponse
                                  xmlns:ns1="http://services.hotschedules.com/api/services/CertificationService">
                                  <return>
                                              <item>
                                                          <certExtRef>•1</certExtRef>
                                                          <certName>21 Day Certification</certName>
                                                          <certType>2</certType>
                                                          <certTypeDescription>Expires Without AutoInactivation</certTypeDescription>
                                                          <groupLevel>true</groupLevel>
                                                          <empPosId>100</empPosId>
                                                          <expirationDate>2016•11•30T00:00:00•06:00</expirationDate>
                                              </item>
                                  </return>
                      </ns1:getEmployeeCertificationsResponse>
          </soap:Body>
</soap:Envelope>

setEmployeeCertifications

This method takes in a concept ID, store ID. It is meant to set certifications from a specified employee for that store.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
          xmlns:emp="http://services.hotschedules.com/api/services/CertificationService"
          xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
          <soapenv:Header>
                      <wsse:Security
                                  xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
                                  xmlns:wsu="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•utility•1.0.xsd" soapenv:mustUnderstand="1">
                                  <wsse:UsernameToken wsu:Id="UsernameToken•63A716DE011BE2D649145262747932814">
                                              <wsse:Username>laura1234!</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordText">laura 1234!</wsse:Password>
                                              <wsse:Nonce EncodingType="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•soap•message•security•1.0#Base64Bina ry">9iOMGex3ZDEpdw4xsAweWA==</wsse:Nonce>
                                              <wsu:Created>2016•01•12T19:37:59.328Z</wsu:Created>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </soapenv:Header>
          <soapenv:Body>
                      <cer:setEmployeeCertifications>
                                  <concept>1</concept>
                                  <storeNum>1</storeNum>
                                  <certs>
                                              <item>
                                                          <certExtRef>500</certExtRef>
                                                          <certName>Laura Test</certName>
                                                          <certType>0</certType>
                                                          <certTypeDescription>Testingnewcert</certTypeDescription>
                                                          <groupLevel>1</groupLevel>
                                                          <empPosId>100</empPosId>
                                                          <expirationDate>?</expirationDate>
                                              </item>
                                  </certs>
                      </cer:setEmployeeCertifications>
          </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
          xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
          <soap:Body>
                      <ns1:removeEmployeeCertificationsResponse
                                  xmlns:ns1="http://services.hotschedules.com/api/services/CertificationService">
                                  <return>
                                              <failCount>0</failCount>
                                              <success>true</success>
                                              <successCount>1</successCount>
                                  </return>
                      </ns1:removeEmployeeCertificationsResponse>
          </soap:Body>
</soap:Envelope>

removeEmployeeCertifications

This method takes in a concept ID and a store ID. It is meant to get allow you to remove certifications from a specified employee for that store.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
          xmlns:emp="http://services.hotschedules.com/api/services/CertificationService"
          xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
          <soapenv:Header>
                      <wsse:Security
                                  xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
                                  xmlns:wsu="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•utility•1.0.xsd" soapenv:mustUnderstand="1">
                                  <wsse:UsernameToken wsu:Id="UsernameToken•63A716DE011BE2D649145262747932814">
                                              <wsse:Username>laura1234!</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordText">laura 1234!</wsse:Password>
                                              <wsse:Nonce EncodingType="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•soap•message•security•1.0#Base64Bina ry">9iOMGex3ZDEpdw4xsAweWA==</wsse:Nonce>
                                              <wsu:Created>2016•01•12T19:37:59.328Z</wsu:Created>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </soapenv:Header>
          <soapenv:Body>
                      <cer:removeEmployeeCertifications>
                                  <concept>1</concept>
                                  <storeNum>1</storeNum>
                                  <certs>
                                              <item>
                                                          <certExtRef>200</certExtRef>
                                                          <certName>21 Day Certification</certName>
                                                          <certType>2</certType>
                                                          <certTypeDescription>Expires Without AutoInactivation</certTypeDescription>
                                                          <groupLevel>true</groupLevel>
                                                          <empPosId>100</empPosId>
                                                          <expirationDate>2016•11•30T00:00:00•06:00</expirationDate>
                                              </item>
                                  </certs>
                      </cer:removeEmployeeCertifications>
          </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
          xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
          <soap:Body>
                      <ns1:setEmployeeCertificationsResponse
                                  xmlns:ns1="http://services.hotschedules.com/api/services/CertificationService">
                                  <return>
                                              <failCount>0</failCount>
                                              <success>true</success>
                                              <successCount>1</successCount>
                                  </return>
                      </ns1:setEmployeeCertificationsResponse>
          </soap:Body>
</soap:Envelope>

EmpService

This service provides operations for a third party to push or request employee and employee job data into HotSchedules.

getStoreEmployees

This method takes in a concept ID, store ID, a flag to determine if only active employees are returned, and returns an array of WSEmployee objects.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum boolean 1..1 Boolean that defines whether or not to include terminated employees in response.
activeOnly Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
return wsEmployeeArray 1..1 Array of WSEmployee objects.

Faults

Name Content Description
Exception Exception perm 3009
API_EMP_PERMISSION_GET_STORE_EMPS
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:emp="http://services.hotschedules.com/api/services/EmpService">
   <soapenv:Header/>
   <soapenv:Body>
      <emp:getStoreEmployees>
         <concept>1</concept>
         <storeNum>55</storeNum>
         <activeOnly>Y</activeOnly>
      </emp:getStoreEmployees>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getStoreEmployeesResponse xmlns:ns1="http://services.hotschedules.com/api/services/EmpService">
         <return>
            <item>
               <address>6504 Bridgepoint Pkwy #425</address>
               <address2/>
               <altId>-1</altId>
               <city>Austin</city>
               <clientId>17638840</clientId>
               <email/>
               <empNum>-1</empNum>
               <FName>HotSchedules</FName>
               <hsId>12262906</hsId>
               <LName>Support</LName>
               <mobile/>
               <NName/>
               <phone>(512) 123-4567</phone>
               <state>TX</state>
               <status>1</status>
               <storeNum>23</storeNum>
               <zipCode>78730</zipCode>
               <dob>2000-02-01T00:00:00-06:00</dob>
               <hireDate>2015-02-09T12:40:09.733-06:00</hireDate>
            </item>
            </return>
      </ns1:getStoreEmployeesResponse>
   </soap:Body>
</soap:Envelope>

getEmpAvailability

This method takes in a concept ID and a store ID and returns an array of wsEmpAvailability objects. It is meant to get a list of all employee availability for that store.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.
activeOnly bolean 1..1 Boolean that defines whether or not to include terminated employees in response.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
return wsEmpAvailabilityArray 1..1 Array of wsEmpAvailability objects, which describes all jobs assigned to all active employees for that store.

Faults

Name Content Description
Exception Exception perm 3021
API_EMP_PERMISSION_GET_EMP_AVAIL
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
          xmlns:emp="http://services.hotschedules.com/api/services/EmpService"
          xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
          <soapenv:Header>
                      <wsse:Security
                                  xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
                                  xmlns:wsu="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•utility•1.0.xsd" soapenv:mustUnderstand="1">
                                  <wsse:UsernameToken wsu:Id="UsernameToken•63A716DE011BE2D649145262747932814">
                                              <wsse:Username>laura1234!</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordText">laura 1234!</wsse:Password>
                                              <wsse:Nonce EncodingType="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•soap•message•security•1.0#Base64Bina ry">9iOMGex3ZDEpdw4xsAweWA==</wsse:Nonce>
                                              <wsu:Created>2016•01•12T19:37:59.328Z</wsu:Created>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </soapenv:Header>
          <soapenv:Body>
                      <emp:getEmpAvailability>
                                  <concept>1</concept>
                                  <storeNum>1</storeNum>
                                  <activeOnly>true</activeOnly>
                      </emp:getEmpAvailability>
          </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
          xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
          <soap:Body>
                      <ns1:getEmpAvailabilityResponse
                                  xmlns:ns1="http://services.hotschedules.com/api/services/EmpService">
                                  <return>
                                              <item>
                                                          <availabilities>
                                                                      <dayName>Sunday</dayName>
                                                                      <dayNum>1</dayNum>
                                                                      <parHoursMax>•1</parHoursMax>
                                                                      <parHoursMin>•1</parHoursMin>
                                                                      <parShiftsMax>•1</parShiftsMax>
                                                                      <parShiftsMin>•1</parShiftsMin>
                                                                      <partialBeforeAfter>After</partialBeforeAfter>
                                                                      <partialTime>11:45</partialTime>
                                                                      <shiftId>964362624</shiftId>
                                                                      <shiftName>Breakfast</shiftName>
                                                                      <statusName>Partially Available</statusName>
                                                                      <statusNum>1</statusNum>
                                                          </availabilities>
                                                          <empHrId>•1</empHrId>
                                                          <empNum>•1</empNum>
                                              </item>
                                  </return>
                      </ns1:getEmpAvailabilityResponse>
          </soap:Body>
</soap:Envelope>

getStoreJobs

This method takes in a concept ID and a store ID, and returns an array of all jobs currently defined in HotSchedules for the given concept/store.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
return wsJobArray 1..1 WSJob object

Faults

Name Content Description
Exception Exception perm 3010
API_EMP_PERMISSION_GET_STORE_JOBS
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:emp="http://services.hotschedules.com/api/services/EmpService">
   <soapenv:Header/>
   <soapenv:Body>
      <emp:getStoreJobs>
         <concept>1</concept>
         <storeNum>32</storeNum>
      </emp:getStoreJobs>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getStoreJobsResponse xmlns:ns1="http://services.hotschedules.com/api/services/EmpService">
         <return>
            <item>
               <clientId>12316576</clientId>
               <defRate>1.0</defRate>
               <hsId>1236319092</hsId>
               <jobName>ATO</jobName>
               <posId>99</posId>
               <storeNum>32</storeNum>
            </item>
            </return>
      </ns1:getStoreJobsResponse>
   </soap:Body>
</soap:Envelope>

getEmpInfo

This method takes in a concept ID and a store ID and returns an array of wsEmpInfo objects. It is meant to get a list of all employees assigned to a schedule for that store.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.
activeOnly boolean 1..1 Boolean that defines whether or not to include terminated employees in response.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
return wsEmpInfoArray 1..1 Array of wsEmpInfo objects, which describes all jobs assigned to all active employees for that store.

Faults

Name Content Description
Exception Exception perm 3020
API_EMP_PERMISSION_GET_EMP_INFO
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
          xmlns:emp="http://services.hotschedules.com/api/services/EmpService"
          xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
          <soapenv:Header>
                      <wsse:Security
                                  xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
                                  xmlns:wsu="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•utility•1.0.xsd" soapenv:mustUnderstand="1">
                                  <wsse:UsernameToken wsu:Id="UsernameToken•63A716DE011BE2D649145262475127713">
                                              <wsse:Username>laura1234!</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordText">laura 1234!</wsse:Password>
                                              <wsse:Nonce EncodingType="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•soap•message•security•1.0#Base64Bina ry">deQn1F/GUBV/fMNJ7pdatA==</wsse:Nonce>
                                              <wsu:Created>2016•01•12T18:52:31.276Z</wsu:Created>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </soapenv:Header>
          <soapenv:Body>
                      <emp:getEmpInfo>
                                  <concept>1</concept>
                                  <storeNum>1</storeNum>
                                  <activeOnly>true</activeOnly>
                      </emp:getEmpInfo>
          </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTF•8"?>
<soap:Envelope>
      <soap:Body>
                  <ns1:getEmpInfoResponse
                              xmlns:ns1="http://services.hotschedules.com/api/services/EmpService">
                              <return>
                                          <item>
                                                      <accountCreated>2015•11•04T10:54:22.807•06:00</accountCreated>
                                                      <assignedSchedules>
                                                                  <extId>0</extId>
                                                                  <hsId>964330043</hsId>
                                                                  <name>Kitchen</name>
                                                      </assignedSchedules>
                                                      <assignedSchedules>
                                                                  <extId>•1</extId>
                                                                  <hsId>964318722</hsId>
                                                                  <name>Meetings</name>
                                                      </assignedSchedules>
                                                      <assignedSchedules>
                                                                  <extId>0</extId>
                                                                  <hsId>964330041</hsId>
                                                                  <name>Team Member</name>
                                                      </assignedSchedules>
                                                      <empHrId>•1</empHrId>
                                                      <empNum>1</empNum>
                                                      <lastUpdated>2015•11•09T10:29:31.123•06:00</lastUpdated>
                                                      <permissionSetName>Employee</permissionSetName>
                                          </item>
                                          <item>
                                                      <accountCreated>2015•11•04T08:33:41.090•06:00</accountCreated>
                                                      <empHrId>•1</empHrId>
                                                      <empNum>•1</empNum>
                                                      <permissionSetName>HS ASC Support</permissionSetName>
                                          </item>
                                          <item>
                                                      <accountCreated>2015•11•04T08:42:02.483•06:00</accountCreated>
                                                      <empHrId>•1</empHrId>
                                                      <empNum>•1</empNum>
                                                      <lastUpdated>2015•11•05T18:29:55.857•06:00</lastUpdated>
                                                      <permissionSetName>Admin ALL</permissionSetName>
                                          </item>
                                          <item>
                                                      <accountCreated>2015•11•04T08:49:32.623•06:00</accountCreated>
                                                      <empHrId>•1</empHrId>
                                                      <empNum>•1</empNum>
                                                      <lastUpdated>2015•11•04T08:49:33.120•06:00</lastUpdated>
                                                      <permissionSetName>Default HS Support User</permissionSetName>
                                          </item>
                                          <item>
                                                      <accountCreated>2015•11•04T08:49:33.887•06:00</accountCreated>
                                                      <empHrId>•1</empHrId>
                                                      <empNum>•1</empNum>
                                                      <lastUpdated>2015•11•04T08:49:34.093•06:00</lastUpdated>
                                                      <permissionSetName>Default HotSchedules Employee</permissionSetName>
                                          </item>
                              </return>
                  </ns1:getEmpInfoResponse>
      </soap:Body>
</soap:Envelope>

getEmpJobs

This method takes in a concept ID and a store ID and returns an array of wsEmpJob objects. It is meant to get a list of all jobs assigned to all employees for that store.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
return wsEmpJobArray 1..1 Array of wsEmpJob objects, which describes all jobs assigned to all active employees for that store.

Faults

Name Content Description
Exception Exception perm 3014
API_EMP_PERMISSION_GET_EMP_JOBS
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
          xmlns:emp="http://services.hotschedules.com/api/services/EmpService"
          xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
          <soapenv:Header>
                      <wsse:Security
                                  xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
                                  xmlns:wsu="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•utility•1.0.xsd" soapenv:mustUnderstand="1">
                                  <wsse:UsernameToken wsu:Id="UsernameToken•63A716DE011BE2D649145262410123010">
                                              <wsse:Username>laura1234!</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordText">laura 1234!</wsse:Password>
                                              <wsse:Nonce EncodingType="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•soap•message•security•1.0#Base64Bina ry">cZvq5MrVptRUWgLIIqmYRg==</wsse:Nonce>
                                              <wsu:Created>2016•01•12T18:41:41.230Z</wsu:Created>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </soapenv:Header>
          <soapenv:Body>
                      <emp:getEmpJobs>
                                  <concept>1</concept>
                                  <storeNum>1</storeNum>
                      </emp:getEmpJobs>
          </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope>
          <soap:Body>
                      <ns1:getEmpJobsResponse
                                  xmlns:ns1="http://services.hotschedules.com/api/services/EmpService">
                                  <return>
                                              <item>
                                                          <clientId>19054117</clientId>
                                                          <hsEmpId>17896647</hsEmpId>
                                                          <hsJobId>27229283</hsJobId>
                                                          <ovtWage>14.25</ovtWage>
                                                          <posEmpId>1</posEmpId>
                                                          <posJobId>•1</posJobId>
                                                          <primary>true</primary>
                                                          <regWage>9.5</regWage>
                                                          <storeNum>1</storeNum>
                                              </item>
                                              <item>
                                                          <clientId>19054117</clientId>
                                                          <hsEmpId>17896647</hsEmpId>
                                                          <hsJobId>27229285</hsJobId>
                                                          <ovtWage>11.25</ovtWage>
                                                          <posEmpId>1</posEmpId>
                                                          <posJobId>•1</posJobId>
                                                          <primary>false</primary>
                                                          <regWage>7.5</regWage>
                                                          <storeNum>1</storeNum>
                                              </item>
                                  </return>
                      </ns1:getEmpJobsResponse>
          </soap:Body>
</soap:Envelope>

setEmps

This method takes in a concept ID, store ID and an array of WSEmployee objects. Using the authentication from the username token and the conecpt and store IDs, the server will resolve which HotSchedules client this sync is for. The array of employees will be parsed on the server side to employees who need to be inserted or updated in the HS database. This method returns a WSReturn object.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.
emps wsEmployeeArray 1..1 Array of WSEmployee objects. Each object represents an employee at this store.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
return wsReturn 1..1 WSReturn object

Faults

Name Content Description
Exception Exception perm 3007
API_EMP_PERMISSION_SET_EMPS
client not found

WSReturn object

Name Description
dataEmpJob Employee job object. Contains job information (job code, regular and OT rates, primary flag) for a given employee job.
dataEmployee Employee information object. Contains employee information (name, address, phone info, active/terminated status).
dataJob General job information object. Contains job information (job code, job name, default rate).
wsEmpJob Extends dataEmpJob.
wsEmployee Extends dataEmployee (contains DOB, hire date, termination date).
wsJob Extends dataJob.
wsReturn Contains array of error strings, fail count, success flag, success count.

Array EmpJobs Employee job object. Contains job information (job code, regular and OT rates, primary flag) for a given employee job.

Derived By Restricting anyType

Content Model Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
hsEmpIdint1..1NoHotSchedules internal employee account ID
hsJobIdint1..1NoHotSchedules internal job code ID
ovtWagefloat1..1NoOvertime hourly wage rate for employee
posEmpIdint1..1NoPOS numeric ID for employee
posJobIdint1..1NoPOS numeric ID for the job code
primaryboolean1..1NoBoolean flag to designate if the job code is the primary job for the employee
regWagefloat1..1NoRegular hourly wage rate for employee
storeNumint1..1NoUnique numeric store ID within HotSchedules. Generally, set up to mirror the client internal store IDs.
datedateTime0..1NoDate job was added for the employee

Referenced By Complex Type wsEmpJob

Emp Array Employee information object. Contains employee information (name, address, phone info, active/terminated status)

Derived By Restricting anyType

Content Model Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
addressstring0..1NoOptional•Employee Address line 1
address2string0..1NoOptional•Employee Address line 2
altIdint1..1NoAlternative ID for employee generally reserved for the HR ID.
citystring0..1NoCity field for Address
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
emailstring0..1NoEmployee’s email address
empNumint1..1NoEmployee POS ID
FNamestring0..1NoEmployee First Name
hsIdint1..1NoOptional•HotSchedule unique employee account ID
LNamestring0..1NoEmployee Last Name
mobilestring0..1NoOptional•Employees Mobile Phone Number
NNamestring0..1NoOptional•Employee Nick Name
phonestring0..1NoOptional•Employee phone number
statestring0..1NoState field for Address
statusint1..1NoActive = 1, Inactive = 0, Terminated =•1
storeNumint1..1NoUnique numeric store ID within HotSchedules. Generally set up to mirror the client internal store IDs.
zipCodestring0..1NoZip Code from Address

Referenced By Complex Type wsEmployee

WSJob Array General job information object. Contains job information (job code, job name, default rate).

Derived By Restricting anyType

Content Model Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
defRatefloat1..1NoDefault Pay Rate for a Job Code
hsIdint1..1NoOptional•HotSchedules numeric ID for Job Code
jobNamestring0..1NoName for Job Code
posIdint1..1NoNumeric POS ID for Job Code
storeNumint1..1NoUnique numeric store ID within HotSchedules. Generally set up to mirror the client internal store IDs.

Referenced By Complex Type wsJob

wsEmpJobArray Extends dataEmpJob.

Derived By Extending dataEmpJob

Content Model Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
hsEmpIdint1..1NoOptional•HotSchedule unique employee account ID
hsJobIdint1..1NoOptional•HotSchedules internal ID for the Job Code
ovtWagefloat1..1NoOvertime hourly wage for job code for the employee
posEmpIdint1..1NoPOS numeric identifier for the employee
posJobIdint1..1NoPOS numeric identifier for the job
primaryboolean1..1NoFlag to indicate if a job is the primary job for the employee
regWagefloat1..1NoRegular hourly wage for the job for the employee
storeNumint1..1NoUnique numeric store ID within HotSchedules. Generally set up to mirror the client internal store IDs.
datedateTime0..1NoDate job was added for the employee

Referenced By Element item [type wsEmpJobArray]
Extends dataEmployee (contains DOB, hire date, termination date)

Derived By Extending dataEmployee

Content Model Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
addressstring0..1NoOptional•Employee Address line 1
address2string0..1NoOptional•Employee Address line 2
altIdint1..1NoAlternative ID for employee generally reserved for the HR ID.
citystring0..1NoCity field for Address
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
emailstring0..1NoEmployee’s email address
empNumint1..1NoEmployee POS ID
FNamestring0..1NoEmployee First Name
hsIdint1..1NoOptional•HotSchedule unique employee account ID
LNamestring0..1NoEmployee Last Name
mobilestring0..1NoOptional•Employees Mobile Phone Number
NNamestring0..1NoOptional•Employee Nick Name
phonestring0..1NoOptional•Employee phone number
statestring0..1NoState field for Address
statusint1..1NoActive = 1, Inactive = 0, Terminated =•1
storeNumint1..1NoUnique numeric store ID within HotSchedules. Generally set up to mirror the client internal store IDs.
zipCodestring0..1NoZip Code from Address
dobdateTime0..1NoEmployee Date of Birth
hireDatedateTime0..1NoEmployee Hire Date
termDatedateTime0..1NoEmployee Termination date. Only required for employees with a status of •1

Referenced By Element item [type wsEmployeeArray] Extends dataJob.

Derived By Extending dataJob

Content Model Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
defRatefloat1..1NoDefault Pay Rate for a Job Code
hsIdint1..1YesOptional•HotSchedules numeric ID for Job Code
jobNamestring0..1NoName for Job Code
posIdint1..1NoNumeric POS ID for Job Code
storeNumint1..1NoUnique numeric store ID within HotSchedules. Generally set up to mirror the client internal store IDs.

Referenced By Element item [type wsJobArray] Contains array of error strings, fail count, success flag, success count.

Derived By Restricting anyType

Content Model Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
errorsstring0..*YesDescription of the error code
failCountint1..1NoTotal number of records that failed to meet basic import specifications
successboolean1..1NoIndicator of the success or failure
successCountint1..1NoTotal number of records that successfully met basic import specifications
Name Description
address [type dataEmployee]Address Line 1
address2 [type dataEmployee]Address Line 2
altId [type dataEmployee]Alternative ID for employee generally reserved for the HR ID.
city [type dataEmployee]City field for Address
clientId [type dataEmpJob]Unique client ID provided via HotSchedules
clientId [type dataEmployee]Unique client ID provided via HotSchedules
defRate [type dataJob]Default Pay Rate for job code
dob [type wsEmployee]Employee Date of Birth
email [type dataEmployee]Employee email address
empNum [type dataEmployee]Employee POS ID
errors [type wsReturn]Error Codes
ExceptionException Codes
failCount [type wsReturn]Total number of records that failed to meet basic import specifications
FName [type dataEmployee]Employee First Name
hireDate [type wsEmployee]Employee Hire Date
hsEmpId [type dataEmpJob]HotSchedules Internal employee account ID
hsId [type dataEmployee]HotSchedules Internal employee account ID
hsId [type dataJob]HotSchedules Internal employee account ID
hsJobId [type dataEmpJob]HotSchedules Internal job code ID
item [type wsEmpJobArray]All jobs assigned to all active employees for that store
item [type wsEmployeeArray]All employees at this store.
item [type wsJobArray]All jobs at this store.
jobName [type dataJob]Address Line 1
LName [type dataEmployee]Address Line 2
message [type Exception]Alternative ID for employee generally reserved for the HR ID.
mobile [type dataEmployee]City field for Address
NName [type dataEmployee]Unique client ID provided via HotSchedules
ovtWage [type dataEmpJob]Unique client ID provided via HotSchedules
phone [type dataEmployee]Default Pay Rate for job code
posEmpId [type dataEmpJob]Employee Date of Birth
posId [type dataJob]Employee email address
posJobId [type dataEmpJob]Employee POS ID
primary [type dataEmpJob]Error Codes
regWage [type dataEmpJob]Exception Codes
state [type dataEmployee]Total number of records that failed to meet basic import specifications
status [type dataEmployee]Active = 1, Inactive = 0, Terminated = o1
storeNum [type dataEmpJob]Unique numeric store ID within HotSchedules. Generally, set up to mirror the client internal store IDs.
storeNum [type dataEmployee]Unique numeric store ID within HotSchedules. Generally, set up to mirror the client internal store IDs.
storeNum [type dataJob]Unique numeric store ID within HotSchedules. Generally, set up to mirror the client internal store IDs.
success [type wsReturn]Indicator of the success or failure.
successCount [type wsReturn]Number of records that successfully met the basic import specification
termDate [type wsEmployee]Employee termination date
zipCode [type dataEmployee]Zip code from Address

setEmpJobs

This method takes in a concept ID, store ID, and an array of WSEmpJob objects to assign jobs to individual employees. This method returns a WSReturn object.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
Concept Int 1..1 The identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNum Int 1..1 Numeric (integer) identifier for the store. Must be unique within the concept.
jobs wsEmpJobArray 1..1 Array of WSEmpJob objects. Each object represents one employee job, so a single employee can have one or more employee jobs (EmpJob) assigned to him/her. Each job that the employee works will be a separate object in this array.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
return wsReturn 1..1 WSReturn object

Faults

Name Content Description
Exception Exception perm 3008
API_EMP_PERMISSION_SET_EMP_JOBS
client not found

LaborService

This service is intended for third parties to be able to request labor data from HotSchedules and import it into their POS/data warehouse/enterprise/etc. system.

getLaborByBusDate

This method will take a concept ID, store number, start and end dates and a labor type and return a list of total labor by job code for each interval in the date range requested for that concept, store and labor type.

Intervals are configured during initial setup for the customer and are typically 30 minutes.

Input (Literal) The inputs of this method are the arguments defined by the following table.

-
Argument Type Description
All--
conceptintThe identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the store. Must be unique within the concept.
starthsSimpleDateStart date for the range of data requested
endhsSimpleDateEnd date for the range of data requested
laborTypelaborTypeType of labor requested. Allowed types are “optimal”, “forecasted” and “scheduled”.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
All
returnwsLaborJobArrayReturns a wsLaborJobArray object, which is an array of wsLaborJob objects.
Each wsLaborJob object contains.

•   a jobCode (which corresponds to the numeric ID that identifies this job)
•   a jobName (the name for this job)
•   a wsLaborInterval object, which can contain

+ an intervalDate object (an hsSimpleDate that determines the date for this particular interval)
+ an intervalTime object (an hsSimpleTime that determines the start time for this particular interval. Interval length in implied by   the span between two intervalTime objects)
+ a laborDate object (an enum which can be “optimal”, “forecasted”, “scheduled”
+ an volume value (which represents the value for the laborDate type for this particular interval, determined by intervalDate and intervalTime)

** Note about labor types **

“scheduled” labor refers to shifts that have been scheduled and posted and are assigned to an employee. This will not include house shifts or shifts not assigned to an employee.

“forecasted” labor refers to labor shifts generated after forecast labor drivers and applying labor shift generation rules within the Activity•based forecasting module in HotSchedules

“optimal” labor refers to labor shifts generated by using actual labor driver values and applying labor shift generation rules specified in the Activity•based forecasting module in HotSchedules. It represents the labor shifts that would have been generated using an exact forecast of labor drivers.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<SOAPENV:Envelope
          xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding/"
          xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
          xmlns:ns0="http://schemas.xmlsoap.org/soap/encoding/"
          xmlns:ns1="http://services.hotschedules.com/api/services/LaborService"
          xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema•instance"
          xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/" SOAPENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
          <SOAPENV:Header>
                      <wsse:Security mustUnderstand="true">
                                  <wsse:UsernameToken>
                                              <wsse:Username>REDACTED</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordT ext">REDACTED</wsse:Password>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </SOAPENV:Header>
          <ns2:Body>
                      <ns1:getLaborByJobAndInterval>
                                  <concept>1</concept>
                                  <storeNum>1101645</storeNum>
                                  <start>
                                              <day>8</day>
                                              <month>7</month>
                                              <year>2014</year>
                                  </start>
                                  <end>
                                              <day>14</day>
                                              <month>7</month>
                                              <year>2014</year>
                                  </end>
                                  <laborType>forecasted</laborType>
                      </ns1:getLaborByJobAndInterval>
          </ns2:Body>
</SOAPENV:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
          xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
          <soap:Body>
                      <ns1:getEmpInfoResponse
                                  xmlns:ns1="http://services.hotschedules.com/api/services/EmpService">
                                  <return>
                                              <item>
                                                          <accountCreated>2015•11•04T10:54:22.807•06:00</accountCreated>
                                                          <assignedSchedules>
                                                                      <extId>0</extId>
                                                                      <hsId>964330043</hsId>
                                                                      <name>Kitchen</name>
                                                          </assignedSchedules>
                                                          <assignedSchedules>
                                                                      <extId>•1</extId>
                                                                      <hsId>964318722</hsId>
                                                                      <name>Meetings</name>
                                                          </assignedSchedules>
                                                          <assignedSchedules>
                                                                      <extId>0</extId>
                                                                      <hsId>964330041</hsId>
                                                                      <name>Team Member</name>
                                                          </assignedSchedules>
                                                          <empHrId>•1</empHrId>
                                                          <empNum>1</empNum>
                                                          <lastUpdated>2015•11•09T10:29:31.123•06:00</lastUpdated>
                                                          <permissionSetName>Employee</permissionSetName>
                                              </item>
                                              <item>
                                                          <accountCreated>2015•11•04T08:33:41.090•06:00</accountCreated>
                                                          <empHrId>•1</empHrId>
                                                          <empNum>•1</empNum>
                                                          <permissionSetName>HS ASC Support</permissionSetName>
                                              </item>
                                              <item>
                                                          <accountCreated>2015•11•04T08:42:02.483•06:00</accountCreated>
                                                          <empHrId>•1</empHrId>
                                                          <empNum>•1</empNum>
                                                          <lastUpdated>2015•11•05T18:29:55.857•06:00</lastUpdated>
                                                          <permissionSetName>Admin ALL</permissionSetName>
                                              </item>
                                              <item>
                                                          <accountCreated>2015•11•04T08:49:32.623•06:00</accountCreated>
                                                          <empHrId>•1</empHrId>
                                                          <empNum>•1</empNum>
                                                          <lastUpdated>2015•11•04T08:49:33.120•06:00</lastUpdated>
                                                          <permissionSetName>Default HS Support User</permissionSetName>
                                              </item>
                                              <item>
                                                          <accountCreated>2015•11•04T08:49:33.887•06:00</accountCreated>
                                                          <empHrId>•1</empHrId>
                                                          <empNum>•1</empNum>
                                                          <lastUpdated>2015•11•04T08:49:34.093•06:00</lastUpdated>
                                                          <permissionSetName>Default HotSchedules Employee</permissionSetName>
                                              </item>
                                              <item>
                                                          <accountCreated>2015•11•05T18:02:12.477•06:00</accountCreated>
                                                          <assignedSchedules>
                                                                      <extId>0</extId>
                                                                      <hsId>964330043</hsId>
                                                                      <name>Kitchen</name>
                                                          </assignedSchedules>
                                                          <empHrId>•1</empHrId>
                                                          <empNum>2</empNum>
                                                          <lastUpdated>2015•11•09T10:30:32.927•06:00</lastUpdated>
                                                          <permissionSetName>Employee</permissionSetName>
                                              </item>
                                              <item>
                                                          <accountCreated>2015•11•09T09:38:47.617•06:00</accountCreated>
                                                          <assignedSchedules>
                                                                      <extId>0</extId>
                                                                      <hsId>964330043</hsId>
                                                                      <name>Kitchen</name>
                                                          </assignedSchedules>
                                                          <empHrId>•1</empHrId>
                                                          <empNum>3</empNum>
                                                          <lastUpdated>2015•11•09T10:29:31.170•06:00</lastUpdated>
                                                          <permissionSetName>Employee</permissionSetName>
                                              </item>
                                              <item>
                                                          <accountCreated>2016•01•07T11:25:55.020•06:00</accountCreated>
                                                          <empHrId>•1</empHrId>
                                                          <empNum>•1</empNum>
                                                          <lastUpdated>2016•01•07T11:28:13.373•06:00</lastUpdated>
                                                          <permissionSetName>Admin</permissionSetName>
                                              </item>
                                  </return>
                      </ns1:getEmpInfoResponse>
          </soap:Body>
</soap:Envelope>

getLaborByJobAndInterval

This method will take a concept ID, store number, start and end dates and a labor type and return a list of total labor by job code for each interval in the date range requested for that concept, store and labor type.

Intervals are configured during initial setup for the customer and are typically 30 minutes.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
All
conceptintThe identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the store. Must be unique within the concept.
starthsSimpleDateStart date for the range of data requested
endhsSimpleDateEnd date for the range of data requested
laborTypelaborTypeType of labor requested. Allowed types are “optimal”, “forecasted” and “scheduled”.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
All
returnwsLaborJobArray

Returns a wsLaborJobArray object, which is an array of wsLaborJob objects.

Each wsLaborJob object contains.


§  a jobCode (which corresponds to the numeric ID that identifies this job)

§  a jobName (the name for this job)

§  a wsLaborInterval object, which can contain


+ an intervalDate object (an hsSimpleDate that determines the date for this particular interval)

+ an intervalTime object (an hsSimpleTime that determines the start time for this particular interval. Interval length in implied by the span between two intervalTime objects)

+ a laborDate object (an enum which can be “optimal”, “forecasted”, “scheduled”

+ an volume value (which represents the value for the laborDate type for this particular interval, determined by intervalDate and intervalTime)


** Note about labor types **

“scheduled” labor refers to shifts that have been scheduled and posted and are assigned to an employee. This will not include house shifts or shifts not assigned to an employee.


“forecasted” labor refers to labor shifts generated after forecast labor drivers and applying labor shift generation rules within the Activity•based forecasting module in HotSchedules


“optimal” labor refers to labor shifts generated by using actual labor driver values and applying labor shift generation rules specified in the Activity•based forecasting module in HotSchedules. It represents the labor shifts that would have been generated using an exact forecast of labor drivers


EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<SOAPENV:Envelope
          xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding/"
          xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
          xmlns:ns0="http://schemas.xmlsoap.org/soap/encoding/"
          xmlns:ns1="http://services.hotschedules.com/api/services/LaborService"
          xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema•instance"
          xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/" SOAPENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
          <SOAPENV:Header>
                      <wsse:Security mustUnderstand="true">
                                  <wsse:UsernameToken>
                                              <wsse:Username>REDACTED</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordT ext">REDACTED</wsse:Password>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </SOAPENV:Header>
          <ns2:Body>
                      <ns1:getLaborByJobAndInterval>
                                  <concept>1</concept>
                                  <storeNum>1101645</storeNum>
                                  <start>
                                              <day>8</day>
                                              <month>7</month>
                                              <year>2014</year>
                                  </start>
                                  <end>
                                              <day>14</day>
                                              <month>7</month>
                                              <year>2014</year>
                                </end>
                                  <laborType>forecasted</laborType>
                      </ns1:getLaborByJobAndInterval>
          </ns2:Body>
</SOAPENV:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope>
          <soap:Body>
                      <ns1:getLaborByJobAndIntervalResponse>
                                  <return>
                                              <item>
                                                          <interval>
                                                                      <intervalDate>
                                                                                  <day>8</day>
                                                                                  <month>7</month>
                                                                                  <year>2014</year>
                                                                      </intervalDate>
                                                                      <intervalTime>
                                                                                  <hours>0</hours>
                                                                                  <militaryTime>true</militaryTime>
                                                                                  <minutes>0</minutes>
                                                                                  <seconds>0</seconds>
                                                                      </intervalTime>
                                                                      <laborType>forecasted</laborType>
                                                                      <volume>0.0</volume>
                                                          </interval>
                                                          <interval>
                                                                      <intervalDate>
                                                                                  <day>8</day>
                                                                                  <month>7</month>
                                                                                  <year>2014</year>
                                                                      </intervalDate>
                                                                      <intervalTime>
                                                                                  <hours>0</hours>
                                                                                  <militaryTime>true</militaryTime>
                                                                                  <minutes>30</minutes>
                                                                                  <seconds>0</seconds>
                                                                      </intervalTime>
                                                                      <laborType>forecasted</laborType>
                                                                      <volume>0.0</volume>
                                                          </interval>
                                                          <jobCode>16000</jobCode>
                                                          <jobName>Crew Person</jobName>
                                              </item>
                                  </return>
                      </ns1:getLaborByJobAndIntervalResponse>
          </soap:Body> </soap:Envelope>

setLaborForecastByJob

This method takes in a concept ID, store ID, business date, daypart start and end times,labor forecast and jobExtId. Forecasted labor for the site, date, internal and job will be updated for the purpose of labor scheduling and all relevant reports. The call can be sent for a full week or single date. All intervals must be updated. A zero in the interval is an acceptable value. A null or blank is an acceptable value and will be treated as a zero. If sent for a single date only the date provided will be updated. All other dates within the week will not be impacted and any values already in the database will be retained. A full day’s data must be sent, updating only one interval within a business date is not permitted and the call will fail.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the location. Must be unique within the concept.
jobswsEmpJobArray1..1Array of WSEmpJob objects. Each object represents one employee job, so a single employee can have one or more employee jobs (EmpJob) assigned to him/her. Each job that the employee works will be a separate object in this array.
dayint1..1Formatted dd
monthint1..1Formatted mm
yearint1..1Formatted yyyy
dayPartStartTimedateTime0..1Day part start time
laborForecastMinutesint1..1Minutes value
jobExtRefint1..1Job reference id

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsReturn1..1WSReturn object

Faults

Name Content Description
ExceptionExceptionperm 3008
API_EMP_PERMISSION_SET_EMP_JOBS
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:lab="http://services.hotschedules.com/api/services/LaborService">
   <soapenv:Header/>
   <soapenv:Body>
      <lab:setLaborForecastByJob>
         <concept>8436</concept>
         <storeNum>23</storeNum>
         <idata>
            <!--Zero or more repetitions:-->
            <item>
               <businessDate>
                  <day>10</day>
                  <month>9</month>
                  <year>2017</year>
               </businessDate>
               <dayPartStartDate>
                  <day>10</day>
                  <month>9</month>
                  <year>2017</year>
               </dayPartStartDate>
               <dayPartStartTime>0045</dayPartStartTime>
               <laborForecastMinutes>15</laborForecastMinutes>
               <jobExtRef>11</jobExtRef>
            </item>
         </idata>
      </lab:setLaborForecastByJob>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:lab="http://services.hotschedules.com/api/services/LaborService">
  <soapenv:Header/>
  <soapenv:Body>
    <lab:setLaborForecastByJob>
      <concept>8436</concept>
      <storeNum231</storeNum>
      <idata>
        <item>
          <businessDate>
            <day>10</day>
            <month>9</month>
            <year>2017</year>
          </businessDate>
          <dayPartStartDate>
            <day>10</day>
            <month>9</month>
            <year>2017</year>
          </dayPartStartDate>
          <dayPartStartTime>0000</dayPartStartTime>
          <jobExtRef>55</jobExtRef>
          <laborForecastMinutes>1</laborForecastMinutes>
        </item>
        <item>
          <businessDate>
            <day>10</day>
            <month>9</month>
            <year>2017</year>
          </businessDate>
          <dayPartStartDate>
            <day>10</day>
            <month>9</month>
            <year>2017</year>
          </dayPartStartDate>
          <dayPartStartTime>0030</dayPartStartTime>
          <jobExtRef>55</jobExtRef>
          <laborForecastMinutes>2</laborForecastMinutes>
        </item>
      </idata>
    </lab:setLaborForecastByJob>
  </soapenv:Body>
</soapenv:Envelope>

OperatingBudgetPlanService

Enables a customer to GET their budget via API. The service also allow a customer to SET their labor budget data.

getLaborData

This method takes in a concept ID, store ID and a data Type ID. In order to utilize the method, customer must have 3031 “API - API Operating Budget Plan Service - Set OBP” permission enabled.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
All
conceptintThe identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the location. Must be unique within the concept.
dataTypeIdintThe id of Labor Budget Type (LaborDollars, LaborPercent, SPLH, GPLH, LH100, LaborHours types). The ids correspond to labor budget types in the following way: 0 - LaborDollars, 1 - LaborPercent, 2 - SPLH, 3 - GPLH, 4 - LH100, 5 - LaborHours. This parameter is mandatory. If you pass a non existing type (10, for instance), an error will appear. dataTypeId value must be integer from 0 to 5.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
All
dataTypeIDintinteger from 0 to 5
dayOfWeekintthe day of week (is valid for values from Sunday (1) to Saturday (7)
valueintactual volume of work
idintposJobId of the job

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:oper="http://services.hotschedules.com/api/services/OperatingBudgetPlanService">
   <soapenv:Header/>
   <soapenv:Body>
      <oper:getLaborData>
         <concept>8436</concept>
         <storeNum>23</storeNum>
         <dataTypeId>1</dataTypeId>
      </oper:getLaborData>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getLaborDataResponse xmlns:ns1="http://services.hotschedules.com/api/services/OperatingBudgetPlanService">
         <return>
            <dataTypeId>1</dataTypeId>
            <jobs>
               <days>
                  <dayOfWeek>1</dayOfWeek>
                  <value>1.8</value>
               </days>
               <days>
                  <dayOfWeek>2</dayOfWeek>
                  <value>1.65</value>
               </days>
               <days>
                  <dayOfWeek>3</dayOfWeek>
                  <value>1.54</value>
               </days>
               <days>
                  <dayOfWeek>4</dayOfWeek>
                  <value>1.6</value>
               </days>
               <days>
                  <dayOfWeek>5</dayOfWeek>
                  <value>1.7</value>
               </days>
               <days>
                  <dayOfWeek>6</dayOfWeek>
                  <value>1.9</value>
               </days>
               <days>
                  <dayOfWeek>7</dayOfWeek>
                  <value>2.0</value>
               </days>
               <id>-1</id>
            </jobs>
         </return>
      </ns1:getLaborDataResponse>
   </soap:Body>
</soap:Envelope>

setLaborData

This method takes in a concept ID, store ID, data Type ID, day of the week, value, and ID.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
conceptintThe identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the location. Must be unique within the concept.
dataTypeIDintinteger from 0 to 5
dayOfWeekintthe day of week (is valid for values from Sunday (1) to Saturday (7)
valueintactual volume of work
idintposJobId of the job

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:oper="http://services.hotschedules.com/api/services/OperatingBudgetPlanService">
   <soapenv:Header/>
   <soapenv:Body>
      <oper:setLaborData>
         <concept>8436</concept>
         <storeNum>23</storeNum>
         <budget>
            <!--type: int-->
            <dataTypeId>3</dataTypeId>
            <!--Zero or more repetitions:-->
            <jobs>
               <!--Zero or more repetitions:-->
               <days>
                  <!--type: int-->
                  <dayOfWeek>5</dayOfWeek>
                  <!--type: double-->
                  <value>1.65</value>
               </days>
               <!--type: int-->
               <id>6</id>
            </jobs>
         </budget>
      </oper:setLaborData>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:setLaborDataResponse xmlns:ns1="http://services.hotschedules.com/api/services/OperatingBudgetPlanService">
         <return>
            <failCount>0</failCount>
            <success>true</success>
            <successCount>2</successCount>
         </return>
      </ns1:setLaborDataResponse>
   </soap:Body>
</soap:Envelope>

ProjectedSalesService

This service is intended for third parties to be able to grab projected sales data from HotSchedules and import it into their POS/data warehouse/enterprise/etc. system.

getProjectedSales

This method takes in a concept ID, store ID, start and end dates. It returns an array of WSProjectedSales objects, which represent the projected sales totals for a particular piece of time, for import into the POS.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
conceptint1..1Numeric (integer) identifier for the
storeNumint1..1location. Must be unique within the concept.
startdateTime1..1First day of projected sales.
enddateTime1..1Last day of projected sales.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsProjectedSalesArray1..1Array of WSProjectedSales objects, which represent the projected sales totals for a particular period.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proj="http://services.hotschedules.com/api/services/ProjectedSalesService">
   <soapenv:Header/>
   <soapenv:Body>
      <proj:getProjectedSales>
         <concept>1</concept>
         <storeNum>55</storeNum>
         <start>2017-05-01</start>
         <end>2017-05-30</end>
      </proj:getProjectedSales>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getProjectedSalesResponse xmlns:ns1="http://services.hotschedules.com/api/services/ProjectedSalesService">
         <return>
            <item>
               <businessDate>2017-05-01T00:00:00-05:00</businessDate>
               <dateTotal>4903.84</dateTotal>
               <dayPartTotals>
                  <dayPartEndTime>1970-01-01T10:00:00-06:00</dayPartEndTime>
                  <dayPartName>AM</dayPartName>
                  <dayPartStartTime>1969-12-31T22:00:00-06:00</dayPartStartTime>
                  <dayPartTotal>1247.08</dayPartTotal>
               </dayPartTotals>
               <dayPartTotals>
                  <dayPartEndTime>1969-12-31T22:00:00-06:00</dayPartEndTime>
                  <dayPartName>PM</dayPartName>
                  <dayPartStartTime>1970-01-01T10:00:00-06:00</dayPartStartTime>
                  <dayPartTotal>3656.76</dayPartTotal>
               </dayPartTotals>
            </item>
</return>
      </ns1:getProjectedSalesResponse>
   </soap:Body>
</soap:Envelope>

getProjectedSalesV3

This method takes in a concept ID, store ID, start and end dates. It returns an array of WSProjectedSales objects, which represent the projected sales totals for a particular piece of time, for import into the POS.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the location. Must be unique within the concept.
starthsSimpleDate1..1First day of projected sales requested. This is an hsSimpleDate object.
endhsSimpleDate1..1First day of projected sales requested. This is an hsSimpleDate object.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsProjectedSalesArray1..1Array of WSProjectedSales3 objects, which represent the projected sales totals for a particular period. hsSimpleDate objects are used for dates and hsSimpleTime objects for times.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:proj="http://services.hotschedules.com/api/services/ProjectedSalesService">
   <soapenv:Header/>
   <soapenv:Body>
      <proj:getProjectedSalesV3>
         <concept>1</concept>
         <storeNum>55</storeNum>
         <start>
            <day>01</day>
            <month>05</month>
            <year>2017</year>
         </start>
         <end>
            <day>05</day>
            <month>05</month>
            <year>2017</year>
         </end>
      </proj:getProjectedSalesV3>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getProjectedSalesV3Response xmlns:ns1="http://services.hotschedules.com/api/services/ProjectedSalesService">
         <return>
            <item>
               <businessDate>
                  <day>1</day>
                  <month>5</month>
                  <year>2017</year>
               </businessDate>
               <dateTotal>4903.84</dateTotal>
               <dayPartTotals>
                  <dayPartEndTime>
                     <amPm/>
                     <hours>16</hours>
                     <militaryTime>true</militaryTime>
                     <minutes>0</minutes>
                     <seconds>0</seconds>
                  </dayPartEndTime>
                  <dayPartName>AM</dayPartName>
                  <dayPartStartTime>
                     <amPm/>
                     <hours>4</hours>
                     <militaryTime>true</militaryTime>
                     <minutes>0</minutes>
                     <seconds>0</seconds>
                  </dayPartStartTime>
                  <dayPartTotal>1247.08</dayPartTotal>
               </dayPartTotals>
               <dayPartTotals>
                  <dayPartEndTime>
                     <amPm/>
                     <hours>4</hours>
                     <militaryTime>true</militaryTime>
                     <minutes>0</minutes>
                     <seconds>0</seconds>
                  </dayPartEndTime>
                  <dayPartName>PM</dayPartName>
                  <dayPartStartTime>
                     <amPm/>
                     <hours>16</hours>
                     <militaryTime>true</militaryTime>
                     <minutes>0</minutes>
                     <seconds>0</seconds>
                  </dayPartStartTime>
                  <dayPartTotal>3656.76</dayPartTotal>
               </dayPartTotals>
            </item>
</return>
      </ns1:getProjectedSalesV3Response>
   </soap:Body>
</soap:Envelope>

SalesService

This service is intended for third parties to be able to import their sales items into the HotSchedules system in a straightforward fashion. Currently there is only one method for setting sales items.

getRVCs

This method takes in a concept ID and a store ID and returns an array of revenue centers for that store. Revenue centers will typically establish where to attribute a sale: Bar, Dining, To go, etc.Revenue centers can be local to a particular store, or defined in HotSchedules as belonging to an entire group (called group•level RVCs).

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the store. Must be unique within the concept.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsRevenueCenterArray1..1Array of wsRevenueCenter objects, which represents all revenue centers defined for that store. This will include store and group level revenue centers, and will be flagged appropriately.

Faults

Name Content Description
Exception Exception perm 3002
API_SALES_PERMISSION
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
          xmlns:sal="http://services.hotschedules.com/api/services/SalesService"
          xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
          <soapenv:Header>
                      <wsse:Security
                                  xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
                                xmlns:wsu="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•utility•1.0.xsd" soapenv:mustUnderstand="1">
                                  <wsse:UsernameToken wsu:Id="UsernameToken•5A4A0145444B759EC8145272034993393">
                                              <wsse:Username>HSAPIUser</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordText">ao24 wO2n8gkh7lp</wsse:Password>
                                              <wsse:Nonce EncodingType="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•soap•message•security•1.0#Base64Bina ry">eup88j1y/qnxGKg2Rn6J4A==</wsse:Nonce>
                                              <wsu:Created>2016•01•13T21:25:49.933Z</wsu:Created>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </soapenv:Header>
          <soapenv:Body>
                      <sal:getRVCs>
                                  <concept>101</concept>
                                  <storeNum>111</storeNum>
                      </sal:getRVCs>
          </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
          xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
          <soap:Body>
                      <ns1:getRVCsResponse
                                  xmlns:ns1="http://services.hotschedules.com/api/services/SalesService">
                                  <return>
                                              <item>
                                                          <extId>10</extId>
                                                          <groupLevel>true</groupLevel>
                                                          <revenueCenterName>Dine in</revenueCenterName>
                                              </item>
                                              <item>
                                                          <extId>17</extId>
                                                          <groupLevel>true</groupLevel>
                                                          <revenueCenterName>Bar</revenueCenterName>
                                              </item>
                                              <item>
                                                          <extId>15</extId>
                                                          <groupLevel>true</groupLevel>
                                                          <revenueCenterName>To go</revenueCenterName>
                                              </item>
                                  </return>
                      </ns1:getRVCsResponse>
          </soap:Body>
</soap:Envelope>

getSalesCats

This method takes in a concept ID and a store ID and returns an array of sales categories for that store. Sales categories will typically establish what kind of item was sold: Food, Beverage, Alcohol, Merchandise.Sales categories can be local to a particular store, or defined in HotSchedules as belonging to an entire group (called group•level sales categories).

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the store. Must be unique within the concept.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsSalesCategoryArray1..1Array of wsSalesCategory objects, which represents all sales categories defined for that store. This will include store and group level sales categories, and will be flagged appropriately.

Faults

Name Content Description
Exception Exception perm 3002
API_SALES_PERMISSION
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
          xmlns:sal="http://services.hotschedules.com/api/services/SalesService"
          xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
          <soapenv:Header>
                      <wsse:Security
                                  xmlns:wsse="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•secext•1.0.xsd"
                                  xmlns:wsu="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•wssecurity•utility•1.0.xsd" soapenv:mustUnderstand="1">
                                  <wsse:UsernameToken wsu:Id="UsernameToken•5A4A0145444B759EC8145272075572695">
                                              <wsse:Username>HSAPIUser</wsse:Username>
                                              <wsse:Password Type="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•username•token•profile•1.0#PasswordText">ao24 wO2n8gkh7lp</wsse:Password>
                                              <wsse:Nonce EncodingType="http://docs.oasis•open.org/wss/2004/01/oasis•200401•wss•soap•message•security•1.0#Base64Bina ry">HWXdmwP4l8qNEDjt4a0G9Q==</wsse:Nonce>
                                              <wsu:Created>2016•01•13T21:32:35.726Z</wsu:Created>
                                  </wsse:UsernameToken>
                      </wsse:Security>
          </soapenv:Header>
          <soapenv:Body>
                      <sal:getSalesCats>
                                  <concept>101</concept>
                                  <storeNum>111</storeNum>
                      </sal:getSalesCats>
          </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
          xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
          <soap:Body>
                      <ns1:getSalesCatsResponse
                                  xmlns:ns1="http://services.hotschedules.com/api/services/SalesService">
                                  <return>
                                              <item>
                                                          <extId>10</extId>
                                                          <groupLevel>true</groupLevel>
                                                          <salesCategoryName>Food</salesCategoryName>
                                              </item>
                                              <item>
                                                          <extId>20</extId>
                                                          <groupLevel>true</groupLevel>
                                                          <salesCategoryName>Beverages</salesCategoryName>
                                              </item>
                                              <item>
                                                          <extId>30</extId>
                                                          <groupLevel>true</groupLevel>
                                                          <salesCategoryName>Beer</salesCategoryName>
                                              </item>
                                              <item>
                                                          <extId>40</extId>
                                                          <groupLevel>true</groupLevel>
                                                          <salesCategoryName>Wine</salesCategoryName>
                                              </item>
                                  </return>
                      </ns1:getSalesCatsResponse>
          </soap:Body>
</soap:Envelope>

getSalesItemsV3

This method takes in a concept ID, store ID, start and end dates.It returns an array of sales for that store.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the location. Must be unique within the concept.
dayintFormatted dd
monthintFormatted mm
yearintFormatted yyyy

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsSalesItem3Array1..1Array of WSSalesItem objects. Each object represents one sales item at this store.

Faults

Name Content Description
Exception Exception perm 3002
API_SALES_PERMISSION
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTFo8"?>
<soapenv:Envelope
  xmlns:sal="http://services.hotschedules.com/api/services/SalesService"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <wsse:Security
      xmlns:wsse="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityosecexto1.0.xsd"
      xmlns:wsu="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityoutilityo1.0.xsd" soapenv:mustUnderstand="1">
      <wsse:UsernameToken wsu:Id="UsernameTokeno5A4A0145444B759EC81452722705669100">
        <wsse:Username>HSAPIUser</wsse:Username>
        <wsse:Password Type="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssousernameotokenoprofileo1.0#PasswordText">ao24 wO2n8gkh7lp</wsse:Password>
        <wsse:Nonce EncodingType="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssosoapomessageosecurityo1.0#Base64Bina ry">WHQ2rdJcHsI92WDsEaBDpA==</wsse:Nonce>
        <wsu:Created>2016o01o13T22:05:05.669Z</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
    <sal:getSalesItemsV3>
      <concept>101</concept>
      <storeNum>111</storeNum>
      <start>
        <day>1</day>
        <month>1</month>
        <year>2015</year>
      </start>
      <end>
        <day>1</day>
        <month>2</month>
        <year>2015</year>
      </end>
    </sal:getSalesItemsV3>
  </soapenv:Body> </soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:getSalesItemsV3Response
      xmlns:ns1="http://services.hotschedules.com/api/services/SalesService">
      <return>
        <item>
          <clientId>16477839</clientId>
          <empId>o1</empId>
          <extId>o1</extId>
          <rvc>o1</rvc>
          <salesCat>o1</salesCat>
          <storeNum>111</storeNum>
          <ttl>13.45</ttl>
          <businessDate>
            <day>3</day>
            <month>1</month>
            <year>2015</year>
          </businessDate>
          <transDate>
            <day>4</day>
            <month>1</month>
            <year>2015</year>
          </transDate>
          <transTime>
            <hours>2</hours>
            <militaryTime>true</militaryTime>
            <minutes>28</minutes>
            <seconds>35</seconds>
          </transTime>
        </item>
        <item>
          <clientId>16477839</clientId>
          <empId>o1</empId>
          <extId>o1</extId>
          <rvc>o1</rvc>
          <salesCat>o1</salesCat>
          <storeNum>111</storeNum>
          <ttl>0.0</ttl>
          <businessDate>
            <day>3</day>
            <month>1</month>
            <year>2015</year>
          </businessDate>
          <transDate>
            <day>4</day>
            <month>1</month>
            <year>2015</year>
          </transDate>
          <transTime>
            <hours>2</hours>
            <militaryTime>true</militaryTime>
            <minutes>33</minutes>
            <seconds>19</seconds>
          </transTime>
        </item>
      </return>
    </ns1:getSalesItemsV3Response>
  </soap:Body>
</soap:Envelope>

setSalesItems

This method takes in a concept ID, store ID, a start and end date and an array of WSSalesItem objects. If the sales items are already in the HS database and do not need to be updated, then nothing will change. The method returns a WSReturn object.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the store. Must be unique within the concept.
saleswsSalesItemArray1..1Array of WSSalesItem objects. Each object represents one sales item at this store.
startdateTime1..1Business date of the first sales item in the array.
enddateTime1..1Business date of the last sales item in the array.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
return wsReturn 1..1 WSReturn object

Faults

Name Content Description
Exception Exception perm 3002
API_SALES_PERMISSION
client not found

setSalesItemsV3

This method takes in a concept ID, store ID, a start and end date and an array of WSSalesItem objects. If the sales items are already in the HS database and do not need to be updated, then nothing will change. The method returns a WSReturn object.

This method uses hsSimpleDate objects for dates.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the location. Must be unique within the concept.
saleswsSalesItem3Array1..1Array of WSSalesItem objects. Each object represents one sales item at this store.
starthsSimpleDate1..1Business date of the first sales item in the array. This method uses hsSimpleDate objects for dates.
endhsSimpleDate1..1Business date of the last sales item in the array. This method uses hsSimpleDate objects for dates.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsReturn1..1WSReturn object

Faults

Name Content Description
ExceptionExceptionperm 3002
API_SALES_PERMISSION
client not found
validation errors
Name Description
dataSalesItemContains sales item data (sales category, revenue center, sales amount, ID of employee that made the sale, store ID where the sale ocurred)
hsSimpleDateSimple date object that excludes any time zone or locale data. Consists of day, month and year integer values.
hsSimpleTimeSimple time object that excludes any time zone or locale data. Consists of hour, minute and second integer values, am/pm string indicator and militaryTime flag.
wsReturnContains array of error strings, fail count, success flag, success count.
wsRevenueCenterContains revenue center objects (RVC ID (external ref ID), RVC name)
wsRevenueCenterArrayAn array of wsRevenueCenterArray objects. Each wsRevenueCenter object describes the total revenue center sales for a given revenue center.
Each wsRevenueCenter object contains,
•      a RevenueCenter (which corresponds to the numeric ID that identifies this revenue center)
wsSalesCategoryContains sales category objects (salesCategoryName, extId, groupLevel)
wsSalesCategoryArrayArray of wsSalesCategory objects, which represents all sales categories defined for that store. This will include store and group level sales categories, and will be flagged appropriately.
wsSalesItemExtends dataSalesItem (includes business date and calendar date of the sale)
wsSalesItem3Extends dataTimeCard (includes business date and hsSimpleDate object and clock in and clockout date/times as hsSimpleDate and hsSimpleTime objects)

Contains sales item data (sales category, revenue center, sales amount, ID of employee that made the sale, store ID where the sale occurred)

Derived By

Restricting anyType

Content Model

Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
catNamestring0..1NoName of the category
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
empIdint1..1NoHotSchedules internal employee account ID
extIdint1..1NoNumeric ID from the external system associated with the transaction
rvcint1..1NoRevenue Center ID
rvcNamestring0..1NoName of the revenue center
salesCatint1..1NoNumeric (integer) identifier for the sales category
storeNumint1..1NoNumeric (integer) identifier for the location. Must be unique within the concept.
ttlfloat1..1NoTotal of the sales category

Referenced By

Simple date object that excludes any time zone or locale data. Consists of day, month and year integer values.

Derived By

Restricting anyType

Content Model

Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
dayint1..1NoFormatted dd
monthint1..1NoFormatted mm
yearint1..1NoFormatted yyyy

Referenced By

Simple time object that excludes any time zone or locale data. Consists of hour, minute and second integer values, am/pm string indicator and militaryTime flag.

Derived By

Restricting anyType

Content Model

Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
amPmstring0..1NoAM or PM indicator. amPm enum. If militaryTime is set to true, amPm is ignored.
hoursint1..1NoHour value
militaryTimeboolean1..1NoMilitary Time indicator
minutesint1..1NoMinutes value
secondsint1..1NoSeconds value

Referenced By

Contains array of error strings, fail count, success flag, success count.

Derived By

Restricting anyType

Content Model

Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
errorsstring0..*YesError messages
failCountint1..1NoNumber of records that failed to meet basic import specifications
successboolean1..1NoIndicator of the success or failure
successCountint1..1NoTotal number of records that successfully met basic import specifications
Component Type Occurs Nillable? Description
Sequence1..1
extIdint1..1NoNumeric (integer) identifier for the location. Must be unique within the concept.
groupLevelboolean1..1NoIndicates if the revenue center is assigned at the group level.
revenueCenterNamestring0..1NoRevenue center name.

Referenced By

Component Type Occurs Nillable? Description
Sequence1..1
itemwsRevenueCenter0..*YesContains revenue center objects (RVC ID (external ref ID), RVC name)
Component Type Occurs Nillable? Description
Sequence1..1
extIdint1..1NoNumeric ID from the external system associated with the transaction
groupLevelboolean1..1NoIndicates if the revenue center is assigned at the group level.
salesCategoryNamestring0..1NoName of the sales category.

Referenced By

Component Type Occurs Nillable? Description
Sequence1..1
itemwsSalesCategory0..*YesContains sales category objects (salesCategoryName, extId, groupLevel)

Extends dataSalesItem (includes business date and calendar date of the sale)

Derived By

Extending dataSalesItem

Content Model

Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
catNamestring0..1NoName of the category.
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
empIdint1..1NoHotSchedules internal employee account ID.
extIdint1..1NoNumeric ID from the external system associated with the transaction.
rvcint1..1NoRevenue Center ID.
rvcNamestring0..1NoName of the revenue center.
salesCatint1..1NoNumeric (integer) identifier for the sales category.
storeNumint1..1NoNumeric (integer) identifier for the location. Must be unique within the concept.
ttlfloat1..1NoTotal of the sales category.
businessDatedateTime0..1NoBusiness date of transaction.
dateTimedateTime0..1NoDate and time of transaction.

Referenced By

Description

Extends dataTimeCard (includes business date and hsSimpleDate object and clock in and clockout date/times as hsSimpleDate and hsSimpleTime objects).

Derived By

Extending dataSalesItem

Content Model

Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
catNamestring0..1NoName of the category
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
empIdint1..1NoHotSchedules internal employee account ID
extIdint1..1NoNumeric ID from the external system associated with the transaction
rvcint1..1NoRevenue Center ID
rvcNamestring0..1NoName of the revenue center
salesCatint1..1NoNumeric (integer) identifier for the sales category
storeNumint1..1NoNumeric (integer) identifier for the location. Must be unique within the concept
ttlfloat1..1NoTotal of the sales category
businessDatehsSimpleDate0..1NoBusiness date of transaction
transDatehsSimpleDate0..1NoDate of the transaction
transTimehsSimpleTime0..1NoTime of the transaction

Referenced By

Elements: SalesItemService

Elements

Name Description
amPm [type hsSimpleTime]AM or PM indicator.
businessDate [type wsSalesItem]Business date of transaction.
businessDate [type wsSalesItem3]Business date of transaction.
catName [type dataSalesItem]Category name.
clientId [type dataSalesItem]Unique identifier for client provided via HotSchedules.
dateTime [type wsSalesItem]Date time of transaction.
day [type hsSimpleDate]Day formatted dd.
empId [type dataSalesItem]Employee ID.
errors [type wsReturn]Error messages.
ExceptionMessage for the exception
extId [type dataSalesItem]Numeric (integer) identifier for the location. Must be unique within the concept.
extId [type wsRevenueCenter]Numeric (integer) identifier for the location. Must be unique within the concept.
extId [type wsSalesCategory]Numeric (integer) identifier for the location. Must be unique within the concept.
failCount [type wsReturn]Total number of records that failed to meet basic import specifications.
groupLevel [type wsRevenueCenter]Indicates if the revenue center is assigned at the group level.
groupLevel [type wsSalesCategory]Indicates if the revenue center is assigned at the group level.
hours [type hsSimpleTime]Number of hours.
item [type wsRevenueCenterArray]Array of wsRevenueCenter objects, which represents all revenue centers defined for that store. This will include store and group level revenue centers, and will be flagged appropriately.
item [type wsSalesCategoryArray]Array of wsSalesCategory objects, which represents all sales categories defined for that store. This will include store and group level sales categories, and will be flagged appropriately.
item [type wsSalesItem3Array]Array of WSSalesItem objects. Each object represents one sales item at this store.
item [type wsSalesItemArray]Array of WSSalesItem objects. Each object represents one sales item at this store.
message [type Exception]Information about an exception that has been caught.
militaryTime [type hsSimpleTime]Military Time indicator.
minutes [type hsSimpleTime]Minute value.
month [type hsSimpleDate]Month value.
revenueCenterNameRevenue center name.
[type wsRevenueCenter]Contains revenue center objects (RVC ID (external ref ID), RVC name).
rvc [type dataSalesItem]Revenue Center.
rvcName [type dataSalesItem]Name for the revenue center associated with the location within the restaurant.
salesCat [type dataSalesItem]Sales category.
salesCategoryName [typeName of the sales category.
wsSalesCategory]Contains sales category objects (salesCategoryName, extId, groupLevel)
seconds [type hsSimpleTime]Seconds value.
storeNum [type dataSalesItem]Numeric (integer) identifier for the location. Must be unique within the concept.
success [type wsReturn]Indicator of the success or failure
successCount [type wsReturn]Total number of records that successfully met basic import specifications.
transDate [type wsSalesItem3]Transaction date.
transTime [type wsSalesItem3]Time of the transaction
ttl [type dataSalesItem]Total of the sales category
year [type hsSimpleDate]year yyyy format

Type String

Referenced By

Type dateTime

Referenced By

Content Model

Contains elements as defined in the following table.

Name Description
Sequence1..1
dayint1..1NoFormatted dd
monthint1..1NoFormatted mm
yearint1..1NoFormatted yyyy

Referenced By

Referenced By

Type int

Referenced By

Type dateTime

Referenced By

Content Model

Contains elements as defined in the following table.

Component Type Occurs Nillable? Description
Sequence1..1
messagestring0..1NoReturn message

Component Type Occurs Nillable? Description
Sequence1..1
extIdint1..1NoNumeric (integer) identifier for the location. Must be unique within the concept.
groupLevelboolean1..1NoIndicates if the revenue center is assigned at the group level.
revenueCenterNamestring0..1NoRevenue center name.

Referenced By

Component Type Occurs Nillable? Description
Sequence1..1
extIdint1..1NoNumeric (integer) identifier for the location. Must be unique within the concept.
groupLevelboolean1..1NoIndicates if the revenue center is assigned at the group level.
salesCategoryNamestring0..1NoName of the sales category.

Referenced By

Component Type Occurs Nillable? Description
Sequence1..1
catNamestring0..1NoName of the category
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
empIdint1..1NoHotSchedules internal employee account ID
extIdint1..1NoNumeric ID from the external system associated with the transaction
rvcint1..1NoRevenue Center ID
rvcNamestring0..1NoName of the revenue center
salesCatint1..1NoNumeric (integer) identifier for the sales category
storeNumint1..1NoNumeric (integer) identifier for the location. Must be unique within the concept.
ttlfloat1..1NoTotal of the sales category
businessDatehsSimpleDate0..1NoBusiness date of transaction
transDatehsSimpleDate0..1NoDate of the transaction
transTimehsSimpleTime0..1NoTime of the transaction

Component Type Occurs Nillable? Description
Sequence1..1
catNamestring0..1NoName of the category
clientIdint1..1NoUnique identifier for client provided via HotSchedules.
empIdint1..1NoHotSchedules internal employee account ID
extIdint1..1NoNumeric ID from the external system associated with the transaction
rvcint1..1NoRevenue Center ID
rvcNamestring0..1NoName of the revenue center
salesCatint1..1NoNumeric (integer) identifier for the sales category
storeNumint1..1NoNumeric (integer) identifier for the location. Must be unique within the concept.
ttlfloat1..1NoTotal of the sales category
businessDatedateTime0..1NoBusiness date of transaction
dateTimedateTime0..1NoDate time of the transaction

Component Type Occurs Nillable? Description
Sequence1..1
dayint1..1NoDay formatted dd
monthint1..1NoMonth formatted mm
yearint1..1NoYear formatted yyyy

Referenced By

Component Type Occurs Nillable? Description
Sequence1..1
amPmstring0..1NoAM or PM indicator. amPm enum. If militaryTime is set to true, amPm
hoursint1..1Nois ignored.
militaryTimeboolean1..1NoHour value
minutesint1..1NoMilitary Time indicator
secondsint1..1NoMinutes value
Seconds value

Referenced By

setSalesItemsV4

Same as setSalesItemsV3 but accepts alphanum store XR

ScheduleService

This service is intended for third parties to be able to grab scheduled shifts from HotSchedules and import them into their POS/data warehouse/enterprise/etc. system.

getLocations

This method takes in a concept ID and store ID. It returns an array of dataLocation objects, each of which represent one HotSchedules schedule location.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the location. Must be unique within the concept.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returndataLocationArray1..1Array of dataLocation objects.

EXAMPLE:

<?xml version="1.0" encoding="UTFo8"?>
<SOAPoENV:Envelope
  xmlns:SOAPoENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:wsse="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityosecexto1.0.xsd"
  xmlns:ns0="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ns2="http://services.hotschedules.com/api/services/ScheduleService"
  xmlns:xsi="http://www.w3.org/2001/XMLSchemaoinstance"
  xmlns:SOAPoENV="http://schemas.xmlsoap.org/soap/envelope/" SOAPoENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAPoENV:Header>
    <wsse:Security mustUnderstand="true">
      <wsse:UsernameToken>
        <wsse:Username>REDACTED</wsse:Username>
        <wsse:Password Type="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssousernameotokenoprofileo1.0#PasswordText"
>REDACTED</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </SOAPoENV:Header>
  <ns1:Body>
    <ns2:getLocations>
      <concept>1</concept>
      <storeNum>103</storeNum>
    </ns2:getLocations>
  </ns1:Body>
</SOAPoENV:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope>
  <soap:Body>
    <ns1:getLocationsResponse>
      <return>
        <item>
          <disabled>false</disabled>
          <id>677337753</id>
          <name>Location Name 1</name>
        </item>
        <item>
          <disabled>false</disabled>
          <id>517879406</id>
          <name>Location Name 2</name>
        </item>
      </return>
    </ns1:getLocationsResponse>
  </soap:Body>
</soap:Envelope>

getSchedule

This method takes in a concept ID, store ID, start and end dates. It returns an array of WSScheduleItem objects, which represent one scheduled shift each, for import into the POS. This method returns a limited amount of data per shift: employee HS ID, employee POS ID, internal HS Job ID, POS Job ID, shift start date/time, shift end date/time, work week start date/time, work week end date/time.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the location. Must be unique within the concept.
startdateTime1..1First day of scheduled shifts you are requesting.
enddateTime1..1Last day of scheduled shifts you are requesting.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All 1..1
return wsReturn 1..1 WSReturn object

Faults

Name Content Description
Exception Exception perm 3008
API_EMP_PERMISSION_SET_EMP_JOBS
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTFo8"?>
<SOAPoENV:Envelope
  xmlns:SOAPoENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:wsse="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityosecexto1.0.xsd"
  xmlns:ns0="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ns2="http://services.hotschedules.com/api/services/ScheduleService"
  xmlns:xsi="http://www.w3.org/2001/XMLSchemaoinstance"
  xmlns:SOAPoENV="http://schemas.xmlsoap.org/soap/envelope/" SOAPoENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAPoENV:Header>
    <wsse:Security mustUnderstand="true">
      <wsse:UsernameToken>
        <wsse:Username>REDACTED</wsse:Username>
        <wsse:Password Type="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssousernameotokenoprofileo1.0#PasswordText"
>REDACTED</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </SOAPoENV:Header>
  <ns1:Body>
    <ns2:getSchedule>
      <concept>1</concept>
      <storeNum>37</storeNum>
      <start>2014o04o18T00:00:00</start>
      <end>2014o04o18T00:00:00</end>
    </ns2:getSchedule>
  </ns1:Body>
</SOAPoENV:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope>
  <soap:Body>
    <ns1:getScheduleResponse>
      <return>
        <item>
          <empHsId>REDACTED
          </empHSId>
          <empPosId>REDACTED</empPosId>
          <jobHsId>2129482342</jobHsId>
          <jobPosId>453</jobPosId>
          <in>2014o04o18T05:00:00o05:00</in>
          <out>2014o04o18T16:00:00o05:00</out>
          <weekEnd>2014o04o24T00:00:00o05:00</weekEnd>
          <weekStart>2014o04o18T00:00:00o05:00</weekStart>
        </item>
        <item>
          <empHSId>REDACTED</empHSId>
          <empPosId>REDACTED</empPosId>
          <jobHsId>837906321</jobHsId>
          <jobPosId>600</jobPosId>
          <in>2014o04o18T06:00:00o05:00</in>
          <out>2014o04o18T14:00:00o05:00</out>
          <weekEnd>2014o04o24T00:00:00o05:00</weekEnd>
          <weekStart>2014o04o18T00:00:00o05:00</weekStart>
        </item>
      </return>
    </ns1:getScheduleResponse>
  </soap:Body>
</soap:Envelope>

getSchedule2

This method takes in a concept ID, store ID, start and end dates. It returns an array of WSScheduleItem2 objects, which represent one scheduled shift each, for import into the POS. This method returns the same data as getSchedule, plus extended scheduled shift data, including location ID, regular pay rate, OT pay rate, scheduled regular minutes, scheduled OT minutes (if any), scheduled special pay (if any) and the unique schedule ID, internal to HS.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the location. Must be unique within the concept.
startdateTime1..1First day of scheduled shifts you are requesting.
enddateTime1..1Last day of scheduled shifts you are requesting.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsScheduleItem2Array1..1Array of WSScheduleItem2 objects, which represent one scheduled shift each.

Faults

Name Content Description
Exception Exception perm 3004
API_SCHEDULE_PERMISSION
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTFo8"?>
<SOAPoENV:Envelope
  xmlns:SOAPoENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:wsse="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityosecexto1.0.xsd"
  xmlns:ns0="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ns2="http://services.hotschedules.com/api/services/ScheduleService"
  xmlns:xsi="http://www.w3.org/2001/XMLSchemaoinstance"
  xmlns:SOAPoENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAPoENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAPoENV:Header>
    <wsse:Security mustUnderstand="true">
      <wsse:UsernameToken>
        <wsse:Username>REDACTED</wsse:Username>
        <wsse:Password Type="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssousernameotokenoprofileo1.0#PasswordText"
>REDACTED</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </SOAPoENV:Header>
  <ns1:Body>
    <ns2:getSchedule2>
      <concept>1</concept>
      <storeNum>37</storeNum>
      <start>2014o04o18T00:00:00</start>
      <end>2014o04o18T00:00:00</end>
    </ns2:getSchedule2>
  </ns1:Body>
</SOAPoENV:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope>
  <soap:Body>
    <ns1:getSchedule2Response>
      <return>
        <item>
          <empHSId>REDACTED</empHSId>
          <empPosId>REDACTED</empPosId>
          <jobHsId>2129482342</jobHsId>
          <jobPosId>453</jobPosId>
          <in>2014o04o18T05:00:00o05:00</in>
          <out>2014o04o18T16:00:00o05:00</out>
          <weekEnd>2014o04o24T00:00:00o05:00</weekEnd>
          <weekStart>2014o04o18T00:00:00o05:00</weekStart>
          <locationId>578176916</locationId>
          <ovtMinutes>0</ovtMinutes>
          <ovtRate>0.0</ovtRate>
          <payRate>0.0</payRate>
          <regMinutes>660</regMinutes>
          <scheduleId>2129477321</scheduleId>
          <specialPay>0.0</specialPay>
        </item>
        <item>
          <empHSId>REDACTED</empHSId>
          <empPosId>REDACTED</empPosId>
          <jobHsId>837906321</jobHsId>
          <jobPosId>600</jobPosId>
          <in>2014o04o18T06:00:00o05:00</in>
          <out>2014o04o18T14:00:00o05:00</out>
          <weekEnd>2014o04o24T00:00:00o05:00</weekEnd>
          <weekStart>2014o04o18T00:00:00o05:00</weekStart>
          <locationId>o1</locationId>
          <ovtMinutes>0</ovtMinutes>
          <ovtRate>0.0</ovtRate>
          <payRate>24.0</payRate>
          <regMinutes>480</regMinutes>
          <scheduleId>2129477321</scheduleId>
          <specialPay>0.0</specialPay>
        </item>
      </return>
    </ns1:getSchedule2Response>
  </soap:Body> </soap:Envelope>

getScheduleV3

This method takes in a concept ID, store ID, start and end dates. It returns an array of WSScheduleItem3 objects, which represent one scheduled shift each, for import into the POS. This method returns the same data as getSchedule, plus extended scheduled shift data, including location ID, regular pay rate, OT pay rate, scheduled regular minutes, scheduled OT minutes (if any), scheduled special pay (if any) and the unique schedule ID, internal to HS. This method uses hsSimpleDate objects for dates.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the store. Must be unique within the concept.
starthsSimpleDate1..1First day of scheduled shifts you are requesting. This method uses hsSimpleDate objects for dates.
endhsSimpleDate1..1Last day of scheduled shifts you are requesting. This method uses hsSimpleDate objects for dates.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsScheduleItem3Array1..1Array of WSScheduleItem3 objects, which represent one scheduled shift each. Dates are hsSimpleDate objects and times are hsSimpleTime objects.

Faults

Name Content Description
Exception Exception perm 3004
API_SCHEDULE_PERMISSION
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTFo8"?>
<SOAPoENV:Envelope
  xmlns:SOAPoENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:wsse="http://docs.oasisoopen.org/wss/2 004/01/oasiso200401owssowssecurityosecexto1.0.xsd"
  xmlns:ns0="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:ns1="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:ns2="http://services.hotschedules.com/api/services/ScheduleService"
  xmlns:xsi="http://www.w3.org/2001/XMLSchemaoinstance"
  xmlns:SOAPoENV="http://schemas.xmlsoap.org/soap/envelope/" SOAPoENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAPoENV:Header>
    <wsse:Security mustUnderstand="true">
      <wsse:UsernameToken>
        <wsse:Username>REDACTED</wsse:Username>
        <wsse:Password Type="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssousernameotokenoprofileo1.0#PasswordText"
>REDACTED</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </SOAPoENV:Header>
  <ns1:Body>
    <ns2:getScheduleV3>
      <concept>1</concept>
      <storeNum>37</storeNum>
      <start>
        <day>18</day>
        <month>4</month>
        <year>2014</year>
      </start>
      <end>
        <day>18</day>
        <month>4</month>
        <year>2014</year>
      </end>
    </ns2:getScheduleV3></ns1:Body></SOAPoENV:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope>
  <soap:Body>lOCA
    <ns1:getScheduleV3Response>
      <return>
        <item>
          <empHSId>1712094</empHSId>
          <empPosId>190</empPosId>
          <jobHsId>489527461</jobHsId>
          <jobPosId>120000</jobPosId>
          <inDate>
            <day>18</day>
            <month>4</month>
            <year>2014</year>
          </inDate>
          <inTime>
            <hours>6</hours>
            <militaryTime>true</militaryTime>
            <minutes>30</minutes>
            <seconds>0</seconds>
          </inTime>
          <locationId>o1</locationId>
          <outDate>
            <day>18</day>
            <month>4</month>
            <year>2014</year>
          </outDate>
          <outTime>
            <hours>15</hours>
            <militaryTime>true</militaryTime>
            <minutes>0</minutes>
            <seconds>0</seconds>
          </outTime>
          <ovtMinutes>0</ovtMinutes>
          <ovtRate>0.0</ovtRate>
          <payRate>0.0</payRate>
          <regMinutes>0</regMinutes>
          <scheduleId>o1</scheduleId>
          <specialPay>0.0</specialPay>
          <weekEnd>
            <day>24</day>
            <month>4</month>
            <year>2014</year>
          </weekEnd>
          <weekStart>
            <day>18</day>
            <month>4</month>
            <year>2014</year>
          </weekStart>
        </item>
      </return>
    </ns1:getScheduleV3Response>
  </soap:Body>
</soap:Envelope>

getShiftsV3

This method takes in a concept ID, store ID, start and end dates and three flags (isHouse, isScheduled and isPosted). It returns an array of WSScheduleItem3 objects, which represent one scheduled shift each. What shifts are returned depends on the flags set:

isHouse: includes scheduled or posted shifts that are not assigned to an employee (called 'house shifts’ in HotSchedules).

isScheduled: includes shifts that are in schedules that have been saved in HotSchedules, but might not have been posted

isPosted: includes shifts that are in schedules that have been set to the 'posted’ status within HotSchedules

This method returns extended scheduled shift data, including location ID, regular pay rate, OT pay rate, scheduled regular minutes, scheduled OT minutes (if any), scheduled special pay (if any) and the unique schedule ID, internal to HS.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the store. Must be unique within the concept.
dayint1..1Day formatted dd
monthint1..1Month formatted mm
yearint1..1Year formatted yyyy
isHouseboolean1..1Include house shifts? These are shifts which were never assigned to someone on a schedule, or were once assigned but removed from an employee when their status, job, etc. changed.
isScheduledboolean1..1Include scheduled shifts? These are shifts which are on a schedule that has been saved in HotSchedules, but might not have been posted
isPostedboolean1..1These are shifts that are in schedules that have been set to the 'posted’ status within HotSchedules.
jobCodesintArray1..1Integer array of job codes to be included in this method’s return. if this parameter is null or empty, all jobs will be included.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsScheduleItem3Array1..1Array of WSScheduleItem3 objects, which represent one scheduled shift each. Dates are hsSimpleDate objects and times are hsSimpleTime objects.

Faults

Name Content Description
Exception Exception perm 3004
API_SCHEDULE_PERMISSION
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTFo8"?>
<soapenv:Envelope
  xmlns:sch="http://services.hotschedules.com/api/services/ScheduleService"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <wsse:Security
      xmlns:wsse="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityosecexto1.0.xsd"
      xmlns:wsu="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityoutilityo1.0.xsd" soapenv:mustUnderstand="1">
      <wsse:UsernameToken wsu:Id="UsernameTokeno5A4A0145444B759EC8145271260874466">
        <wsse:Username>laura1234!</wsse:Username>
        <wsse:Password Type="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssousernameotokenoprofileo1.0#PasswordText">laura 1234!</wsse:Password>
        <wsse:Nonce EncodingType="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssosoapomessageosecurityo1.0#Base64Bina ry">m2/v7Yt2bmHeTDmYvu85CA==</wsse:Nonce>
        <wsu:Created>2016o01o13T19:16:48.744Z</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
    <sch:getShiftsV3>
      <concept>1</concept>
      <storeNum>1</storeNum>
      <start>
        <day>1</day>
        <month>1</month>
        <year>2016</year>
      </start>
      <end>
        <day>9</day>
        <month>2</month>
        <year>2016</year>
      </end>
      <isHouse>false</isHouse>
      <isScheduled>true</isScheduled>
      <isPosted>true</isPosted>
      <jobCodes>
        <!ooZero or more repetitions:
<item>871507284</item>oo>
</jobCodes>
</sch:getShiftsV3>
</soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:getShiftsV3Response
      xmlns:ns1="http://services.hotschedules.com/api/services/ScheduleService">
      <return>
        <item>
          <empHSId>17896647</empHSId>
          <empPosId>1</empPosId>
          <jobHsId>964330045</jobHsId>
          <jobPosId>o1</jobPosId>
          <inDate>
            <day>11</day>
            <month>1</month>
            <year>2016</year>
          </inDate>
          <inTime>
            <hours>7</hours>
            <militaryTime>true</militaryTime>
            <minutes>0</minutes>
            <seconds>0</seconds>
          </inTime>
          <locationId>o1</locationId>
          <outDate>
            <day>11</day>
            <month>1</month>
            <year>2016</year>
          </outDate>
          <outTime>
            <hours>15</hours>
            <militaryTime>true</militaryTime>
            <minutes>0</minutes>
            <seconds>0</seconds>
          </outTime>
          <ovtMinutes>0</ovtMinutes>
          <ovtRate>0.0</ovtRate>
          <payRate>9.5</payRate>
          <regMinutes>480</regMinutes>
          <scheduleId>964330041</scheduleId>
          <specialPay>0.0</specialPay>
          <weekEnd>
            <day>16</day>
            <month>1</month>
            <year>2016</year>
          </weekEnd>
          <weekStart>
            <day>10</day>
            <month>1</month>
            <year>2016</year>
          </weekStart>
        </item>
      </return>
    </ns1:getShiftsV3Response>
  </soap:Body>
</soap:Envelope>

getTemplates

This method takes in a concept ID, store ID, start and end dates. This method returns template information.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the store. Must be unique within the concept.
dayint1..1Day formatted dd
monthint1..1Month formatted mm
yearint1..1Year formatted yyyy

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnTemplate objects1..1Returns a list of template objects.

Faults

Name Content Description
Exception Exception invalid start and/or end dates
perm 3004
perm 3002
API_SCHEDULE_PERMISSION
API_SCHEDULE_GET_TEMPLATES_PERMISSION
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTFo8"?>
<soapenv:Envelope
  xmlns:sch="http://services.hotschedules.com/api/services/ScheduleService"
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <wsse:Security
      xmlns:wsse="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityosecexto1.0.xsd"
      xmlns:wsu="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityoutilityo1.0.xsd" soapenv:mustUnderstand="1">
      <wsse:UsernameToken wsu:Id="UsernameTokeno63A716DE011BE2D649145262988637423">
        <wsse:Username>laura1234!</wsse:Username>
        <wsse:Password Type="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssousernameotokenoprofileo1.0#PasswordText">laura 1234!</wsse:Password>
        <wsse:Nonce EncodingType="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssosoapomessageosecurityo1.0#Base64Bina ry">WjFLOOT1CCJWLffHSRdCnQ==</wsse:Nonce>
        <wsu:Created>2016o01o12T20:18:06.374Z</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
    <sch:getTemplates>
      <concept>1</concept>
      <storeNum>1</storeNum>
      <start>
        <day>1</day>
        <month>1</month>
        <year>2016</year>
      </start>
      <end>
        <day>20</day>
        <month>1</month>
        <year>2016</year>
      </end>
    </sch:getTemplates>
  </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:getTemplatesResponse
      xmlns:ns1="http://services.hotschedules.com/api/services/ScheduleService">
      <return>
        <item>
          <durationMinutes>360</durationMinutes>
          <endTime>
            <hours>16</hours>
            <militaryTime>true</militaryTime>
            <minutes>0</minutes>
            <seconds>0</seconds>
          </endTime>
          <jobCode>o1</jobCode>
          <jobName>Baker</jobName>
          <locationId>o1</locationId>
          <locationName>NO_LOC</locationName>
          <scheduleId>964330043</scheduleId>
          <scheduleName>Kitchen</scheduleName>
          <shiftName>Kitchen</shiftName>
          <startTime>
            <hours>10</hours>
            <militaryTime>true</militaryTime>
            <minutes>0</minutes>
            <seconds>0</seconds>
          </startTime>
          <templateDesc>Low Volume</templateDesc>
          <templateGroupId>o1</templateGroupId>
          <templateGroupName>NOT_GROUPED</templateGroupName>
          <templateId>964318045</templateId>
          <templateName>Low Volume</templateName>
          <weekday>6</weekday>
          <weekdayName>Friday</weekdayName>
        </item>
      </return>
    </ns1:getTemplatesResponse>
  </soap:Body></soap:Envelope>

TimeCardService

This service is intended for third parties to be able to import their time cards into the HotSchedules system or get time cards from HotSchedules in a straightforward fashion.

getTimeCards

This method takes in a concept ID, store ID, start and end dates. It returns an array of wsTimeCard3 objects, which represent one employee time card each. Each time card has information for one employee punch record, including business date, regular and OT minutes and wages, clock in and clock out times. If this store is using HotSchedules’ web-based timeclock for employee clock-in, any open punches in the date range are also included in the response.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the store. Must be unique within the concept.
dayint1..1Day formatted dd
Monthint1..1Month formatted mm
yearint1..1Year formatted yyyy

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsTimeCard3Array1..1Array of wsTimeCard3 objects. Each object has data for one employee punch record. Dates are hsSimpleDate objects and times are hsSimpleTime objects.

Faults

Name Content Description
ExceptionExceptionperm 3003
perm 3011
API_LABOR_SERVICE
API_LABOR_PERMISSION_GET_TIMECARDS
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTFo8"?>
<SOAPoENV:Envelope
  xmlns:SOAPoENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:wsse="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityosecexto1.0.xsd"
  xmlns:ns0="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:ns1="http://services.hotschedules.com/api/services/TimeCardService"
  xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchemaoinstance"
  xmlns:SOAPoENV="http://schemas.xmlsoap.org/soap/envelope/"
SOAPoENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAPoENV:Header>
    <wsse:Security mustUnderstand="true">
      <wsse:UsernameToken>
        <wsse:Username>REDACTED</wsse:Username>
        <wsse:Password Type="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssousernameotokenoprofileo1.0#PasswordText"
>REDACTED</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </SOAPoENV:Header>
  <ns2:Body>
    <ns1:getTimeCards>
      <concept>1</concept>
      <storeNum>103</storeNum>
      <start>
        <day>25</day>
        <month>2</month>
        <year>2014</year>
      </start>
      <end>
        <day>25</day>
        <month>2</month>
        <year>2014</year>
      </end>
    </ns1:getTimeCards>
  </ns2:Body>
</SOAPoENV:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope>
  <soap:Body>
    <ns1:getTimeCardsResponse>
      <return>
        <item>
          <breakMinutes>0</breakMinutes>
          <empPosId>210</empPosId>
          <extId>156393867196</extId>
          <hsId>156393867197</hsId>
          <jobExtId>12</jobExtId>
          <jobName>Expediter</jobName>
          <ovtHrs>0.0</ovtHrs>
          <ovtMins>0</ovtMins>
          <ovtTtl>0.0</ovtTtl>
          <ovtWage>0.0</ovtWage>
          <regHrs>4.6833334</regHrs>
          <regTtl>0.0</regTtl>
          <regWage>8.0</regWage>
          <spcHrs>0.0</spcHrs>
          <spcTtl>0.0</spcTtl>
          <storeNum>103</storeNum>
          <businessDate>
            <day>25</day>
            <month>2</month>
            <year>2014</year>
          </businessDate>
          <clockIn>2014o02o25T10:26:00o06:00</clockIn>
          <clockOut>2014o02o25T15:07:00o06:00</clockOut>
        </item>
        <item>
          <breakMinutes>0</breakMinutes>
          <empPosId>207</empPosId>
          <extId>156393867200</extId>
          <hsId>156393867201</hsId>
          <jobExtId>12</jobExtId>
          <jobName>Expediter</jobName>
          <ovtHrs>0.0</ovtHrs>
          <ovtMins>0</ovtMins>
          <ovtTtl>0.0</ovtTtl>
          <ovtWage>0.0</ovtWage>
          <regHrs>4.983333</regHrs>
          <regTtl>0.0</regTtl>
          <regWage>8.0</regWage>
          <spcHrs>0.0</spcHrs>
          <spcTtl>0.0</spcTtl>
          <storeNum>103</storeNum>
          <businessDate>
            <day>25</day>
            <month>2</month>
            <year>2014</year>
          </businessDate>
          <clockIn>2014o02o25T16:28:00o06:00</clockIn>
          <clockOut>2014o02o25T21:27:00o06:00</clockOut>
        </item>
      </return>
    </ns1:getTimeCardsResponse>
  </soap:Body>
</soap:Envelope>

getTimeCardsDeclaredTips

This method takes in a concept ID, store ID, start and end dates. It returns an array of wsTimeCard3 objects, which represent one employee time card each. Each time card has information for one employee punch record, including business date, regular and OT minutes and wages, clock in, clock out times and declared tips. If this store is using HotSchedules’ webobased timeclock for employee clockoin, any open punches in the date range are also included in the response.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumint1..1Numeric (integer) identifier for the store. Must be unique within the concept.
dayint1..1Day formatted dd
Monthint1..1Month formatted mm
yearint1..1Year formatted yyyy

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsTimeCard3Array1..1Array of wsTimeCard3 objects. Each object has data for one employee punch record. Dates are hsSimpleDate objects and times are hsSimpleTime objects.

Faults

Name Content Description
ExceptionExceptionperm 3003
perm 3011
API_LABOR_SERVICE
API_LABOR_PERMISSION_GET_TIMECARDS
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTFo8"?>
<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:tim="http://services.hotschedules.com/api/services/TimeCardService">
  <soapenv:Header>
    <wsse:Security
      xmlns:wsse="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityosecexto1.0.xsd"
      xmlns:wsu="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssowssecurityoutilityo1.0.xsd" soapenv:mustUnderstand="1">
      <wsse:UsernameToken wsu:Id="UsernameTokeno5A4A0145444B759EC8145271596284975">
        <wsse:Username>laura1234!</wsse:Username>
        <wsse:Password Type="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssousernameotokenoprofileo1.0#PasswordText">laur a1234!</wsse:Password>
        <wsse:Nonce EncodingType="http://docs.oasisoopen.org/wss/2004/01/oasiso200401owssosoapomessageosecurityo1.0#Base64Bin ary">mafwHuh4YzpETuPwHxlC2g==</wsse:Nonce>
        <wsu:Created>2016o01o13T20:12:42.849Z</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
    <tim:getTimeCardsDeclaredTips>
      <concept>1</concept>
      <storeNum>1</storeNum>
      <start>
        <day>1</day>
        <month>1</month>
        <year>2016</year>
      </start>
      <end>
        <day>10</day>
        <month>1</month>
        <year>2016</year>
      </end>
    </tim:getTimeCardsDeclaredTips>
  </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<?xml version="1.0" encoding="UTFo8"?>
<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:getTimeCardsDeclaredTipsResponse
      xmlns:ns1="http://services.hotschedules.com/api/services/TimeCardService">
      <return>
        <item>
          <breakMinutes>0</breakMinutes>
          <empPosId>2</empPosId>
          <extId>844268158324</extId>
          <hsId>844268158325</hsId>
          <jobExtId>o1</jobExtId>
          <jobId>o1</jobId>
          <jobName>Baker</jobName>
          <ovtHrs>1.0</ovtHrs>
          <ovtMins>0</ovtMins>
          <ovtTtl>0.0</ovtTtl>
          <ovtWage>0.0</ovtWage>
          <regHrs>8.0</regHrs>
          <regTtl>0.0</regTtl>
          <regWage>0.0</regWage>
          <spcHrs>0.0</spcHrs>
          <spcTtl>0.0</spcTtl>
          <storeNum>1</storeNum>
          <businessDate>
            <day>10</day>
            <month>1</month>
            <year>2016</year>
          </businessDate>
          <clockIn>2016o01o10T15:00:00o06:00</clockIn>
          <clockOut>2016o01o11T00:00:00o06:00</clockOut>
          <declaredTips>0.0</declaredTips>
        </item>
      </return>
    </ns1:getTimeCardsDeclaredTipsResponse>
  </soap:Body>
</soap:Envelope>

getTimeCardsV2

Same as getTimeCards but additionally provides double time info for each timecard.

getTimeCardsV3

Same as getTimeCardsV2 but additionally exposes the “hsid” info for each timecard.

setTimeCards

This method takes in a concept ID, store ID, a start and end date and an array of WSTimeCard objects. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains time cards for a range of dates, corresponding to the start and end dates. The serveroside logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the time cards are already in the HS database and do not need to be updated, then nothing will change. This method returns a WSReturn object.

setTimeCardsDeclaredTips

This method takes in a concept ID, store ID, a start and end date and an array of WSTimeCardsDeclaredTips objects. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains time cards for a range of dates, corresponding to the start and end dates. The server•side logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the time cards are already in the HS database and do not need to be updated, then nothing will change. This method returns a WSReturn object.

setTimeCardsV3

This method takes in a concept ID, store ID, a start and end date and an array of WSTimeCard objects. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains time cards for a range of dates, corresponding to the start and end dates. The server•side logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the time cards are already in the HS database and do not need to be updated, then nothing will change. This method returns a WSReturn object. This method uses hsSimpleDate objects for dates.

updateTimeCards

Similar to setTimeCards but allows for many more flags to control the timecard sync: dropCards, createIds, calculateOvertime, usePunchIds, isSalary, overrideOT, manualPunchUpdate, skipAggregation. The API was created for simulation and shall be used with caution.

TimeOffService

This service is intended for third parties to be able to request approved time off requests from HotSchedules.

getApprovedPTO

This method takes in a concept ID, store ID, start date, end date and returns a list of employees approved scheduled time off.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
conceptint1..1The identifier for the location’s concept/group. Must be unique within the company. Contact HotSchedules if you’re Not sure about this value.
storeNumint1..1Numeric (integer) identifier for the location. Must be unique within the concept.
dayint1..1Formatted dd
monthint1..1Formatted dd
yearint1..1Formatted mm

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Occurs Description
All1..1
returnwsReturn1..1wsReturn object

Faults

Name Content Description
Exception Exception perm 3050
API_TIME_OFF_SERVICE_PERMISSION
client not found

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tim="http://services.hotschedules.com/api/services/TimeOffService">
   <soapenv:Header/>
   <soapenv:Body>
      <tim:getApprovedPTO>
         <concept>28</concept>
         <storeNum>408</storeNum>
         <start>
            <!--type: int-->
            <day>27</day>
            <!--type: int-->
            <month>4</month>
            <!--type: int-->
            <year>2016</year>
         </start>
         <end>
            <!--type: int-->
            <day>10</day>
            <!--type: int-->
            <month>5</month>
            <!--type: int-->
            <year>2016</year>
         </end>
      </tim:getApprovedPTO>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getApprovedPTOResponse xmlns:ns1="http://services.hotschedules.com/api/services/TimeOffService">
         <return>
            <item>
               <clientId>408</clientId>
               <date>2016-05-08</date>
               <dayParts>
                  <dayPart>Dinner</dayPart>
                  <dayPart>Lunch</dayPart>
               </dayParts>
               <employeeFirstName>SAM</employeeFirstName>
               <employeeHrId>-1</employeeHrId>
               <employeeLastName>SMITH</employeeLastName>
               <employeePosId>142</employeePosId>
               <jobId>200</jobId>
               <jobName>SERVER/200</jobName>
               <jobRate>11.25</jobRate>
               <timeOffHours>9.00</timeOffHours>
               <timeOffTypeCode>VAC</timeOffTypeCode>
            </item>
            <item>
               <clientId>408</clientId>
               <date>2016-05-09</date>
               <dayParts>
                  <dayPart>Dinner</dayPart>
                  <dayPart>Lunch</dayPart>
               </dayParts>
               <employeeFirstName>SAM</employeeFirstName>
               <employeeHrId>-1</employeeHrId>
               <employeeLastName>SMITH</employeeLastName>
               <employeePosId>142</employeePosId>
               <jobId>200</jobId>
               <jobName>SERVER/200</jobName>
               <jobRate>11.25</jobRate>
               <timeOffHours>4.00</timeOffHours>
               <timeOffTypeCode>VAC</timeOffTypeCode>
            </item>
            <item>
               <clientId>408</clientId>
               <date>2016-05-10</date>
               <dayParts>
                  <dayPart>Dinner</dayPart>
                  <dayPart>Lunch</dayPart>
               </dayParts>
               <employeeFirstName>SAM</employeeFirstName>
               <employeeHrId>-1</employeeHrId>
               <employeeLastName>SMITH</employeeLastName>
               <employeePosId>142</employeePosId>
               <jobId>200</jobId>
               <jobName>SERVER/200</jobName>
               <jobRate>11.25</jobRate>
               <timeOffHours>0</timeOffHours>
               <timeOffTypeCode>VAC</timeOffTypeCode>
            </item>
         </return>
      </ns1:getApprovedPTOResponse>
   </soap:Body>
</soap:Envelope>

VolumeService

This service is intended for third parties to be able to request and send volume driver related data from/to HotSchedules. Driver items include examples such as guests, tables, entrees, etc…

getDriversByInterval

This method will take a concept ID, store number, start and end dates, volume type, and data type and return a list of total driver amount for each interval in the date range requested for that concept, store and labor type.

Intervals are configured during initial setup for the customer and are typically 30 minutes or 15 minutes.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
All
conceptintThe identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the store. Must be unique within the concept.
startDatehsSimpleDateStart date for the range of data requested
endDatehsSimpleDateEnd date for the range of data requested
volumeTypedriverClassClassification of driver requested. Allowed types would be all of the classifications supported from API, HSC, or FTP integration.  “Guests”, “Tables”, “Entrees”, “Deliveries”, and “Products”.
dataTypedriverTypeType of driver requested. Allowed types are “ACTUAL”, “ADJ_FORECASTED”, and “PRE_ADJ_FORECASTED”.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vol="http://services.hotschedules.com/api/services/VolumeService">
   <soapenv:Header/>
   <soapenv:Body>
      <vol:getDriversByInterval>
         <concept>8436</concept>
         <storeNum>23</storeNum>
         <startDate>
            <day>10</day>
            <month>5</month>
            <year>2017</year>
         </startDate>
         <endDate>
            <day>11</day>
            <month>5</month>
            <year>2017</year>
         </endDate>
         <volumeType>PRODUCTS</volumeType>
         <dataType>ACTUAL</dataType>
      </vol:getDriversByInterval>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:getDriversByIntervalResponse xmlns:ns1="http://services.hotschedules.com/api/services/VolumeService">
         <return>
            <item>
               <companyExtRef>260146</companyExtRef>
               <conceptExtRef>8436</conceptExtRef>
               <driverAmount>0.0</driverAmount>
               <driverClass>PRODUCTS</driverClass>
               <driverType>ACTUAL</driverType>
               <intervalEndDate>
                  <day>10</day>
                  <month>5</month>
                  <year>2017</year>
               </intervalEndDate>
               <intervalEndTime>
                  <hours>0</hours>
                  <militaryTime>true</militaryTime>
                  <minutes>30</minutes>
                  <seconds>0</seconds>
               </intervalEndTime>
               <intervalStartDate>
                  <day>10</day>
                  <month>5</month>
                  <year>2017</year>
               </intervalStartDate>
               <intervalStartTime>
                  <hours>0</hours>
                  <militaryTime>true</militaryTime>
                  <minutes>0</minutes>
                  <seconds>0</seconds>
               </intervalStartTime>
               <storeExtRef>23</storeExtRef>
            </item>
            </return>
      </ns1:getDriversByIntervalResponse>
   </soap:Body>
</soap:Envelope>

getGuestCounts

This method will take a concept ID, store number, start and end dates and return a list of guest counts for the date range requested.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
All
conceptintThe identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the store. Must be unique within the concept.
startdateTimeStart date for the range of data requested. This is a basic dateTime object.
enddateTimeEnd date for the range of data requested. This is a basic dateTime object.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
All
return wsGuestCountsArray Returns a wsGuestCountsArray object, which is an array of wsGuestCountsArray objects.
Each wsGuestCounts object contains
- a businessDate
- a dateTime
- a guestCount
- a rvcExtID which represents the numeric revenue center ID associated with the guest.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:vol="http://services.hotschedules.com/api/services/VolumeService">
  <soapenv:Header/>
  <soapenv:Body>
    <vol:getGuestCounts>
      <concept>1</concept>
      <storeNum>1</storeNum>
      <startDate>2014o09o24T00:00:00</startDate>
      <endDate>2014o09o25T00:00:00</endDate>
    </vol:getGuestCounts>
  </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:getGuestCountsResponse
      xmlns:ns1="http://services.hotschedules.com/api/services/VolumeService">
      <return>
        <item>
          <businessDate>2014o09o24T00:00:00o05:00</businessDate>
          <dateTime>2014o09o24T06:35:00o05:00</dateTime>
          <guestCount>1.0</guestCount>
          <rvcExtId>4</rvcExtId>
        </item>
        <item>
          <businessDate>2014o09o24T00:00:00o05:00</businessDate>
          <dateTime>2014o09o24T06:38:00o05:00</dateTime>
          <guestCount>1.0</guestCount>
          <rvcExtId>4</rvcExtId>
        </item>
        <item>
          <businessDate>2014o09o24T00:00:00o05:00</businessDate>
          <dateTime>2014o09o24T06:41:00o05:00</dateTime>
          <guestCount>1.0</guestCount>
          <rvcExtId>4</rvcExtId>
        </item>

getVolumeCounts

This method will take a concept ID, store number, start and end dates and a volume type and return a list of volume counts for the date range requested.

Supported Volume Types are: “TABLE”, “ENTRÉE”, “GUESTS”, “DELIVERIES”, “PRODUCTS”, and “TRANSACTIONS”

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
All
conceptintThe identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the store. Must be unique within the concept.
volumeTypevolumeTypeSupported Volume Types are: “TABLE”, “ENTRÉE”, “GUESTS”, “DELIVERIES”, “PRODUCTS”, and “TRANSACTIONS”
starthsSimpleDateStart date for the range of data requested
endhsSimpleDateEnd date for the range of data requested

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
All
return wsVolumeCountsArray Returns a wsVolumeCounts object, which is an array of wsVolumeCounts objects.
Each wsLaborJob object contains
- a businessDate
- a dateTime
- a volumeType
- a volumeCount
- a rvcExtID which represents the numeric revenue center ID associated with the count.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:vol="http://services.hotschedules.com/api/services/VolumeService">
  <soapenv:Header/>
  <soapenv:Body>
    <vol:getVolumeCounts>
      <concept>1</concept>
      <storeNum>101</storeNum>
      <volumeType>GUESTS</volumeType>
      <startDate>2014o09o24T00:00:00</startDate>
      <endDate>2014o09o25T00:00:00</endDate>
    </vol:getVolumeCounts>
  </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ns1:getGuestCountsResponse
      xmlns:ns1="http://services.hotschedules.com/api/services/VolumeService">
      <return>
        <item>
          <businessDate>2014o09o24T00:00:00o05:00</businessDate>
          <dateTime>2014o09o24T06:35:00o05:00</dateTime>
          <volumeType>GUESTS</volumeType>
          <volumeCount>1.0</volumeCount>
          <rvcExtId>4</rvcExtId>
        </item>
        <item>
          <businessDate>2014o09o24T00:00:00o05:00</businessDate>
          <dateTime>2014o09o24T06:38:00o05:00</dateTime>
          <volumeType>GUESTS</volumeType>
          <volumeCount>1.0</volumeCount>
          <rvcExtId>4</rvcExtId>
        </item>
        <item>
          <businessDate>2014o09o24T00:00:00o05:00</businessDate>
          <dateTime>2014o09o24T06:41:00o05:00</dateTime>
          <volumeType>GUESTS</volumeType>
          <volumeCount>1.0</volumeCount>
          <rvcExtId>4</rvcExtId>
        </item>

setForecastDrivers

This method takes in a concept ID, store ID, workweek startdate and enddate , starttime and endtime, volume amount, volume type, and a revenue center for the purpose of submitting forecasted volume drivers to HotSchedules from a third party system or point of sale. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains volume driver counts for a range of dates, corresponding to the start and end dates. The serveroside logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the guest are already in the HS database and do not need to be updated, then nothing will change.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
All
conceptintThe identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the store. Must be unique within the concept.
WorkWeekStartDatehsSimpleDateDay, Month and Year
rvcExtIDintNumeric ID for the revenue center associated with the transaction
DriverAmountIntValue of the driver amount for the transaction
volumeTypevolumeTypeSupported Volume Types are: “TABLE”, “ENTRÉE”, “GUESTS”, “DELIVERIES”, “PRODUCTS”, and “TRANSACTIONS”

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
All
return wsReturn WSReturn objects.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vol="http://services.hotschedules.com/api/services/VolumeService">
   <soapenv:Header/>
   <soapenv:Body>
      <vol:setForecastDrivers>
         <concept>8436</concept>
         <storeNum>23</storeNum>
         <workweekStartDate>
            <day>28</day>
            <month>8</month>
            <year>2017</year>
         </workweekStartDate>
         <driverData>
            <!--Zero or more repetitions:-->
            <item>
               <driverAmount>1000</driverAmount>
               <!--Optional:-->
               <intervalEndDate>
                  <day>28</day>
                  <month>8</month>
                  <year>2017</year>
               </intervalEndDate>
               <!--Optional:-->
               <intervalEndTime>
                  <!--Optional:-->
                  <amPm>1</amPm>
                  <hours>6</hours>
                  <militaryTime>false</militaryTime>
                  <minutes>30</minutes>
                  <seconds>0</seconds>
               </intervalEndTime>
               <!--Optional:-->
               <intervalStartDate>
                  <day>28</day>
                  <month>8</month>
                  <year>2017</year>
               </intervalStartDate>
               <!--Optional:-->
               <intervalStartTime>
                  <!--Optional:-->
                  <amPm>1</amPm>
                  <hours>6</hours>
                  <militaryTime>false</militaryTime>
                  <minutes>0</minutes>
                  <seconds>0</seconds>
               </intervalStartTime>
               <rvcId>4</rvcId>
               <!--Optional:-->
               <volumeType>SALES</volumeType>
            </item>
         </driverData>
      </vol:setForecastDrivers>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:setForecastDriversResponse xmlns:ns1="http://services.hotschedules.com/api/services/VolumeService">
         <return>
            <failCount>0</failCount>
            <success>true</success>
            <successCount>1</successCount>
         </return>
      </ns1:setForecastDriversResponse>
   </soap:Body>
</soap:Envelope>

setForecastDriversV2

This method takes in a concept ID, store ID, workweek, startdate, enddate, starttime, endtime, volume amount, volume type, and a revenue center for the purpose of submitting forecasted volume drivers to HotSchedules from a third party system or point of sale. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains volume driver counts for a range of dates, corresponding to the start and end dates. The server side logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the guest are already in the HS database and do not need to be updated, then nothing will change.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
concept int The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum int Numeric (integer) identifier for the store. Must be unique within the concept.
Day int Day formatted dd
Month int Month formatted mm
Year int Year formated yyyy

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
concept int The identifier for the location’s concept. Must be unique within the company, contact HotSchedules if you’re not sure about this value.
storeNum int Numeric (integer) identifier for the store. Must be unique within the concept.
workweekStartDate hsSimpledate Start date of the work week
driverAmount int Quantity of driver for interval expressed in the record
intervalStartTime dateTime The hour, minutes, and seconds corresponding to the start of the interval expressed in the record. Interval times are local to the store’s time zone.
intervalEndTime dateTime The hour, minutes, and seconds corresponding to the end of the interval expressed in the record. Interval times are local to the store’s time zone.
intervalStartDate hsSimpledate The date corresponding to the start of the interval expressed in the record
intervalEndDate hsSimpledate The date corresponding to the end of the interval expressed in the record
rvcId int Numeric ID for the revenue center associated with the location within the restaurant
volumeType String Classification of driver requested. Allowed types would be all of the classifications supported from API, HSC, or FTP integration. “Guests”, “Tables”, “Entrees”, “Deliveries”, “Transactions” and “Products”.

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vol="http://services.hotschedules.com/api/services/VolumeService">
   <soapenv:Header/>
   <soapenv:Body>
      <vol:setForecastDriversV2>
         <concept>8436</concept>
         <storeNum>23</storeNum>
         <workweekStartDate>
            <day>28</day>
            <month>8</month>
            <year>2017</year>
         </workweekStartDate>
         <driverData>
            <!--Zero or more repetitions:-->
            <item>
               <driverAmount>500</driverAmount>
               <!--Optional:-->
               <intervalEndDate>
                  <day>28</day>
                  <month>8</month>
                  <year>2017</year>
               </intervalEndDate>
               <!--Optional:-->
               <intervalEndTime>
                  <!--Optional:-->
                  <amPm>1</amPm>
                  <hours>6</hours>
                  <militaryTime>false</militaryTime>
                  <minutes>30</minutes>
                  <seconds>0</seconds>
               </intervalEndTime>
               <!--Optional:-->
               <intervalStartDate>
                  <day>28</day>
                  <month>8</month>
                  <year>2017</year>
               </intervalStartDate>
               <!--Optional:-->
               <intervalStartTime>
                  <!--Optional:-->
                  <amPm>1</amPm>
                  <hours>6</hours>
                  <militaryTime>false</militaryTime>
                  <minutes>0</minutes>
                  <seconds>0</seconds>
               </intervalStartTime>
               <rvcId>4</rvcId>
               <!--Optional:-->
               <volumeType>GUESTS</volumeType>
            </item>
         </driverData>
      </vol:setForecastDriversV2>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:setForecastDriversV2Response xmlns:ns1="http://services.hotschedules.com/api/services/VolumeService">
         <return>
            <failCount>0</failCount>
            <success>true</success>
            <successCount>1</successCount>
         </return>
      </ns1:setForecastDriversV2Response>
   </soap:Body>
</soap:Envelope>

setGuestCounts

This method takes in a concept ID, store ID, business date, date time, guest count and a revenue center for the purpose of submitting actual guest count drivers to HotSchedules from a third party system or point of sale. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains guest counts for a range of dates, corresponding to the start and end dates. The serveroside logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the guest are already in the HS database and do not need to be updated, then nothing will change. This method returns a WSReturn object.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
All
conceptintThe identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the store. Must be unique within the concept.
businessDatehsSimpleDateBusiness date of transaction
dateTimedateTimeDate Time of the transaction
guestCountIntNumber of guests for the transaction
rvcExtIDintNumeric ID for the revenue center associated with the transaction

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
All
return wsReturn WSReturn object

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vol="http://services.hotschedules.com/api/services/VolumeService">
   <soapenv:Header/>
   <soapenv:Body>
      <vol:setGuestCounts>
         <concept>3714</concept>
         <storeNum>98</storeNum>
         <guests>
            <!--Zero or more repetitions:-->
            <item>
               <!--Optional:-->
               <businessDate>2017-03-05T00:00:00</businessDate>
               <!--Optional:-->
               <dateTime>2017-03-05T06:41:00-05:00</dateTime>
               <guestCount>18</guestCount>
               <rvcExtId>1</rvcExtId>
            </item>
         </guests>
      </vol:setGuestCounts>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:setGuestCountsResponse xmlns:ns1="http://services.hotschedules.com/api/services/VolumeService">
         <return>
            <failCount>0</failCount>
            <success>true</success>
            <successCount>1</successCount>
         </return>
      </ns1:setGuestCountsResponse>
   </soap:Body>
</soap:Envelope>

setVolumeCounts

This method takes in a concept ID, store ID, business date, date time, volume amount, volume type, and a revenue center for the purpose of submitting actual volume drivers to HotSchedules from a third party system or point of sale. Using the authentication from the username token and the concept and store IDs, the server will resolve which HotSchedules client this sync is for. The array contains volume driver counts for a range of dates, corresponding to the start and end dates. The serveroside logic can handle overlapping data (i.e. if you sync 7 days worth of time cards, every day, 6 days of it will be “overlapping” data) and will insert and update data as needed. If the guest are already in the HS database and do not need to be updated, then nothing will change. This method returns a WSReturn object.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
All
conceptintThe identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the store. Must be unique within the concept.
businessDatehsSimpleDateBusiness date of transaction
dateTimedateTimeDate Time of the transaction
rvcExtIDintNumeric ID for the revenue center associated with the transaction
volumeAmountIntValue of the volume count for the transaction
volumeTypevolumeTypeSupported Volume Types (UPPERCASE): “TABLE”, “ENTRÉE”, “GUESTS”, “DELIVERIES”, “PRODUCTS”, and “TRANSACTIONS”

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
All
return wsReturn WSReturn object

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
<soapenv:Envelope
  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:vol="http://services.hotschedules.com/api/services/VolumeService">
  <soapenv:Header/>
  <soapenv:Body>
    <vol:setVolumeCounts>
      <concept>1</concept>
      <storeNum>1</storeNum>
      <volumeData>
        <item>
          <businessDate>2014o10o05T00:00:00</businessDate>
          <dateTime>2014o10o05T06:41:00o05:00</dateTime>
          <rvcExtId>4</rvcExtId>
          <volumeAmount>1</volumeAmount>
          <volumeType>GUESTS</volumeType>
        </item>
      </volumeData>
    </vol:setVolumeCounts>
  </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:setVolumeCountsResponse xmlns:ns1="http://services.hotschedules.com/api/services/VolumeService">
         <return>
            <failCount>0</failCount>
            <success>true</success>
            <successCount>1</successCount>
         </return>
      </ns1:setVolumeCountsResponse>
   </soap:Body>
</soap:Envelope>

setVolumeCountsV3

All behavior is the same as setVolumeCounts, however you can use a string value in either UPPER or lower case for the volumeTypeName object.

Input (Literal) The inputs of this method are the arguments defined by the following table.

Argument Type Description
All
conceptintThe identifier for the location’s concept. Must be unique within the company. Contact HotSchedules if you’re not sure about this value.
storeNumintNumeric (integer) identifier for the store. Must be unique within the concept.
businessDatehsSimpleDateBusiness date of transaction
dateTimedateTimeDate Time of the transaction
rvcExtIDintNumeric ID for the revenue center associated with the transaction
volumeAmountIntValue of the volume count for the transaction
volumeTypeNamevolumeTypeSupported Volume Types: “Sales”, “Guests”, “Tables”, “Entrees”, “Deliveries”, “Products”, “Transactions”, “Plates”, “KitchenUnits”, “LBW”, “Items”, “TFE”, “Member Check In”.

Output (Literal) The outputs of this method are the arguments defined by the following table.

Argument Type Description
All
return wsReturn WSReturn object

EXAMPLE:

<?xml version="1.0" encoding="UTF•8"?>
   <soapenv:Body>
      <vol:setVolumeCountsV3>
         <concept>8436</concept>
         <storeNum>23</storeNum>
         <volumeData>
            <!--Zero or more repetitions:-->
            <item>
               <businessDate>2017-10-05T00:00:00</businessDate>
               <dateTime>2017-10-05T06:41:00-05:00</dateTime>
               <rvcExtId>4</rvcExtId>
               <volumeAmount>4</volumeAmount>
               <volumeType>
                  <volumeTypeName>GUESTS</volumeTypeName>
               </volumeType>
            </item>
         </volumeData>
      </vol:setVolumeCountsV3>
   </soapenv:Body>
</soapenv:Envelope>

EXAMPLE RESPONSE:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:setVolumeCountsV3Response xmlns:ns1="http://services.hotschedules.com/api/services/VolumeService">
         <return>
            <failCount>0</failCount>
            <success>true</success>
            <successCount>1</successCount>
         </return>
      </ns1:setVolumeCountsV3Response>
   </soap:Body>
</soap:Envelope>

HotSchedules Community

Do you have questions, comments or suggestions on improviements to this documentation? Please subscribe to the HotSchedules Community.

HotSchedules Community