SmartIce API v1

API Endpoint

https://api.mysmartice.com/v1

The SmartIce API enables more advanced integrations with the SmartIce platform. If you need assistance please contact SmartIce@IceHouseAmerica.com

Authentication ¶

Every API request must be authenticated using ONE of the following methods:

Authentication via HTTP Headers

Include the 2 HTTP headers below with each request:

X-User-Username: <USERNAME>
X-User-Token: <API_TOKEN>

Authentication via HTTP Query Parameters

Include user_username and user_token in the Query String

?user_username=USERNAME&user_token=API_TOKEN

Authentication via HTTP Post Parameters

Include user_username and user_token in the JSON body

{
    "user_username": "randy",
    "user_token": "SxL3oY3tKJdYnQuNx5WL",
    // other params...
}

Machines ¶

GET https://api.mysmartice.com/v1/machines

Responses200

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "name": "QT 0003",
      "serial_number": "96-0043K - P16-0108",
      "customer_number": "96-0043K",
      "address": "5020 E. 146th Street",
      "city": "Collinsville",
      "state": "OK",
      "postal_code": "74021",
      "status": "ok",
      "bin_level": 2389
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Machine's name."
          },
          "serial_number": {
            "type": "string",
            "description": "Machine's serial number."
          },
          "customer_number": {
            "type": "string",
            "description": "Machine's customer number."
          },
          "address": {
            "type": "string",
            "description": "Machine's address."
          },
          "city": {
            "type": "string",
            "description": "Machine's city."
          },
          "state": {
            "type": "string",
            "description": "Machine's state."
          },
          "postal_code": {
            "type": "string",
            "description": "Machine's postal code."
          },
          "status": {
            "type": "string",
            "description": "Machine's status."
          },
          "bin_level": {
            "type": "number",
            "description": "Machine's bin level."
          }
        }
      },
      "description": "Machine data."
    }
  }
}

List All Machines
GET`/machines`

Returns a list of machines.

Alerts ¶

GET https://api.mysmartice.com/v1/alerts?started_at=2018-09-04&ended_at=2018-09-12&machines=96-0043K,96-0044K&status=active

Responses200

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "machine_serial_number": "96-0043K",
      "machine_name": "QT 0003",
      "alerts": [
        {
          "started_at": "2018-09-04T15:03:07Z",
          "ended_at": "2018-09-04T16:05:27Z",
          "label": "Ice Maker #1 Not Running",
          "event_code": "38",
          "event_value": "1",
          "status": "active"
        }
      ]
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    }
  }
}

List All Alerts
GET`/alerts{?started_at,ended_at,machines,status}`

URI Parameters

HideShow

started_at

string (optional) Default: 24 hours ago Example: 2018-09-04

Start date for alerts.

ended_at

string (optional) Default: Now Example: 2018-09-12

End date for alerts.

machines

string (optional) Default: All machines available for current user Example: 96-0043K,96-0044K

List of machine serial numbers

status

string (optional) Default: all Example: active

Choices: all active ended

Events ¶

GET https://api.mysmartice.com/v1/events?occurred_at_gteq=2024-10-18T08:30:00&occurred_at_lteq=2024-10-18T09:30:00&machines=96-0043K,96-0044K

Responses200

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "machine": {
        "name": "123 Example Machine",
        "mac_address": "00:E0:62:22:01:17",
        "serial_number": "99-9999",
        "customer_number": "C123456",
        "zip_code": "12345"
      },
      "events": [
        {
          "id": "1234567890",
          "occurred_at": "2024-10-16T12:20:37-05:00",
          "created_at": "2024-10-16T13:20:45-04:00",
          "name": "1 gal.",
          "label": "1 gal.",
          "code": "82",
          "value": "1",
          "category_label": "Vend",
          "vendor_label": "Water",
          "command_label": null,
          "product_type_label": "Water",
          "product_label": "1 gal.",
          "product_vend_price": "0.35",
          "product_amount_collected": "0.45",
          "machine_mac_address": "00:E0:62:22:01:17",
          "comment": null
        }
      ]
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    }
  }
}

List All Events
GET`/events{?occurred_at_gteq,occurred_at_lteq,machines}`

URI Parameters

HideShow

occurred_at_gteq

string (optional) Default: 1 hour ago Example: 2024-10-18T08:30:00

Date/time start range for event in iso8601 format

occurred_at_lteq

string (optional) Default: Now Example: 2024-10-18T09:30:00

Date/time end range for event in iso8601 format

machines

string (optional) Default: All machines available for current user Example: 96-0043K,96-0044K

List of machine serial numbers comma-separated

Service Counters ¶

GET https://api.mysmartice.com/v1/service_counters?machines=96-0043K,96-0044K

Responses200

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "machine_serial_number": "96-0043K",
      "machine_name": "QT 0003",
      "service_counters": [
        {
          "name": "carbon_filter_days",
          "label": "Carbon Filter",
          "value": 41,
          "threshold": 90
        }
      ]
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    }
  }
}

List All Service Counters
GET`/service_counters{?machines}`

URI Parameters

HideShow

machines

string (optional) Default: All machines available for current user Example: 96-0043K,96-0044K

List of machine serial numbers

Vends ¶

GET https://api.mysmartice.com/v1/vends?date=2019-07-12&machines=96-0043K,96-0044K

Responses200

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "machine_serial_number": "96-0043K",
      "machine_name": "QT 0003",
      "vends": [
        {
          "occurred_at": "2019-07-12T19:55:17.000-04:00",
          "vendor": "Ice",
          "label": "Vend Bag",
          "product_group": "Ice",
          "product": "20 lb. Bag",
          "vend_price": "1.75",
          "weather_conditions": "Clear sky",
          "weather_temperature": 70
        }
      ]
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    }
  }
}

List All Vends
GET`/vends{?date,machines}`

Returns a list of vends grouped by machine. Only returns 1 day of vends per request.

URI Parameters

HideShow

date

string (optional) Default: 1 day ago Example: 2019-07-12

Date for vends.

machines

string (optional) Default: All machines available for current user Example: 96-0043K,96-0044K

List of machine serial numbers

Daily Totals ¶

GET https://api.mysmartice.com/v1/daily_totals?start=2019-07-12&end=2019-07-12&machines=96-0043K,96-0044K

Responses200

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "date": "2019-07-12",
      "total_vends": 70,
      "total_ice_vends": 61,
      "total_water_vends": 9,
      "total_free_ice_vends": 3,
      "total_free_water_vends": 1,
      "total_revenue": "80.75",
      "total_ice_revenue": "76.25",
      "total_water_revenue": "4.50"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "Date."
          },
          "total_vends": {
            "type": "number",
            "description": "Total # vends for the day."
          },
          "total_ice_vends": {
            "type": "number",
            "description": "Total # Ice vends for the day."
          },
          "total_water_vends": {
            "type": "number",
            "description": "Total # Water vends for the day."
          },
          "total_free_ice_vends": {
            "type": "number",
            "description": "Total # Free Ice vends for the day."
          },
          "total_free_water_vends": {
            "type": "number",
            "description": "Total # Free Water vends for the day."
          },
          "total_revenue": {
            "type": "string",
            "description": "Total $ revenue for the day."
          },
          "total_ice_revenue": {
            "type": "string",
            "description": "Total $ Ice revenue for the day."
          },
          "total_water_revenue": {
            "type": "string",
            "description": "Total $ Water revenue for the day."
          }
        }
      }
    }
  }
}

List Daily Totals
GET`/daily_totals{?start,end,machines}`

Returns a list of daily vend and revenue totals, grouped by date. Max of 180 days for a single request.

URI Parameters

HideShow

start

string (optional) Default: Yesterday Example: 2019-07-12

Start date.

end

string (optional) Default: Yesterday Example: 2019-07-12

End date.
Single-request limit of 180 day range.

machines

string (optional) Default: All machines available for current user Example: 96-0043K,96-0044K

List of machine serial numbers

Commands ¶

GET https://api.mysmartice.com/v1/commands?machines=96-0043K,96-0044K

Responses200

Headers

Content-Type: application/json

Body

{
  "data": {
    "machine_serial_number": "96-0043K",
    "machine_name": "QT 0003",
    "commands": [
      {
        "name": "soft_reset",
        "label": "Soft Reset"
      }
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "machine_serial_number": {
          "type": "string",
          "description": "Machine's serial number."
        },
        "machine_name": {
          "type": "string",
          "description": "Machine's name."
        },
        "commands": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Command name."
              },
              "label": {
                "type": "string",
                "description": "Command label."
              }
            }
          },
          "description": "List of commands supported by each machine"
        }
      }
    }
  }
}

List All Commands
GET`/commands{?machines}`

URI Parameters

HideShow

machines

string (optional) Default: All machines available for current user Example: 96-0043K,96-0044K

List of machine serial numbers

Command ¶

POST https://api.mysmartice.com/v1/command

Requestsexample 1

Headers

Content-Type: application/json

Body

{
    "machine": "96-0043K",
    "command": "soft_reset",
}

Responses200

Headers

Content-Type: application/json

Body

{
  "data": {
    "machine": "96-0043K",
    "command": "soft_reset",
    "command_result": {}
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "machine": {
          "type": "string",
          "description": "Serial number of the machine that should execute this command"
        },
        "command": {
          "type": "string",
          "description": "Command name to execute"
        },
        "command_result": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "machine",
        "command"
      ],
      "description": "Submitted command."
    }
  }
}

Execute Command
POST`/command`

Instructs SmartIce to execute a remote command on the specified machine.

The value returned in the command_result varies by command.

Many commands will return true on success, but some commands do not return anything, even on success.

Users ¶

User Status ¶

GET https://api.mysmartice.com/v1/user_status?username=user1&oauth_uid=123-45678-91011"

Responses200

Headers

Content-Type: application/json

Body

{
  "data": {
    "username": "user1",
    "status": "disabled",
    "oauth": {
      "uid": "123-45678-91011",
      "provider": "disabled"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "username": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "oauth": {
          "type": "object",
          "properties": {
            "uid": {
              "type": "string"
            },
            "provider": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Get User Status
GET`/user_status{?username,oauth_uid}`

Query user status, providing either the username or the oauth_uid (if user is SSO/OAuth enabled)

URI Parameters

HideShow

username

string (optional) Example: user1

SmartIce username.

oauth_uid

string (optional) Example: 123-45678-91011"

OAuth / SSO user unique identifier.

PUT https://api.mysmartice.com/v1/user_status

Requestsexample 1example 2

Headers

Content-Type: application/json

Body

{
    "username": "user1",
    "status": "disabled",
}

Responses200

Headers

Content-Type: application/json

Body

{
  "data": {
    "username": "user1",
    "status": "disabled"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "username": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      }
    }
  }
}

Headers

Content-Type: application/json

Body

{
    "oauth_uid": "123-45678-91011",
    "status": "disabled",
}

Responses200

Headers

Content-Type: application/json

Body

{
  "data": {
    "username": "user1",
    "status": "disabled",
    "oauth": {
      "uid": "123-45678-91011",
      "provider": "disabled"
    }
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "username": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "oauth": {
          "type": "object",
          "properties": {
            "uid": {
              "type": "string"
            },
            "provider": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Update User Status
PUT`/user_status`

Update a user’s status by providing the username or oauth_uid (if SSO enabled) and the new status (active or disabled) in the request body.

Generated by aglio on 24 Apr 2025

API Endpoint

Authentication ¶

Authentication via HTTP Headers ¶

Authentication via HTTP Query Parameters ¶

Authentication via HTTP Post Parameters ¶

Machines ¶

Machines ¶

Headers

Body

Schema

List All MachinesGET/machines

Alerts ¶

Headers

Body

Schema

List All AlertsGET/alerts{?started_at,ended_at,machines,status}

Events ¶

Headers

Body

Schema

List All EventsGET/events{?occurred_at_gteq,occurred_at_lteq,machines}

Service Counters ¶

Headers

Body

Schema

List All Service CountersGET/service_counters{?machines}

Vends ¶

Headers

Body

Schema

List All VendsGET/vends{?date,machines}

Daily Totals ¶

Headers

Body

Schema

List Daily TotalsGET/daily_totals{?start,end,machines}

Commands ¶

Headers

Body

Schema

List All CommandsGET/commands{?machines}

Command ¶

Headers

Body

Headers

Body

Schema

Execute CommandPOST/command

Users ¶

User Status ¶

Headers

Body

Schema

Get User StatusGET/user_status{?username,oauth_uid}

Headers

Body

Headers

Body

Schema

Headers

Body

Headers

Body

Schema

Update User StatusPUT/user_status

Authentication via HTTP Headers

Authentication via HTTP Query Parameters

Authentication via HTTP Post Parameters

List All Machines
GET`/machines`

List All Alerts
GET`/alerts{?started_at,ended_at,machines,status}`

List All Events
GET`/events{?occurred_at_gteq,occurred_at_lteq,machines}`

List All Service Counters
GET`/service_counters{?machines}`

List All Vends
GET`/vends{?date,machines}`

List Daily Totals
GET`/daily_totals{?start,end,machines}`

List All Commands
GET`/commands{?machines}`

Execute Command
POST`/command`

Get User Status
GET`/user_status{?username,oauth_uid}`

Update User Status
PUT`/user_status`