JSON RPC auto-generated documentation

To call any of these methods, send a POST request to this url with encoded JSON according to the JSON RPC 2.0 spec.

The 'params' value should be specified by-name (i.e. as a JS object).

Batch requests are supported.

Test Form

Use the following form to send JSONRPC requests




                

Methods

The following methods are available

ack_alert

Parameters
Parameter Purpose Default Required?
alert_id Yes
dismiss False No
sessionkey A session key returned from login Yes

add

Add a and b together and return the result.

This is a dumb method for debugging. Requires a valid sessionkey, so use this to test logging in.

Parameters
Parameter Purpose Default Required?
a First number Yes
b Second number 0 No
sessionkey A session key returned from login Yes

add_reg_ids

Parameters
Parameter Purpose Default Required?
id_type String. One of android, ios, ms_mobile or ms_win Yes
reg_id Yes
sessionkey A session key returned from login Yes

boom

Test for error handling, this method attempts to divide by zero

No parameters

change_tag_pin

Changes the tag pin

Parameters
Parameter Purpose Default Required?
new_pin New pin number Yes
old_pin Current pin number Yes
sessionkey A session key returned from login Yes

get_alerts

Gets a list of alert objects for the companies devices. Make the same queries as the front page.

Parameters
Parameter Purpose Default Required?
company uid of the company to filter by Yes
limit Number of objects in each page null No
page Pagination page, index starts at 1 null No
sessionkey A session key returned from login Yes

get_companies

Get a list of companies that may be managed by the user.

Companies are returned as a list of objects containing the name, company key and logo url.

e.g. [{"name":"Microsoft", "key":10}, {"name":"Sony", "key":20, "image_url": "example.com/images/logo.png"}]

Parameters
Parameter Purpose Default Required?
sessionkey A session key returned from login Yes

get_device

Gets a single device

Parameters
Parameter Purpose Default Required?
device_key The device key Yes
sessionkey A session key returned from login Yes

get_device_with_uid

Gets a single device

Parameters
Parameter Purpose Default Required?
device_uid The device uid Yes
sessionkey A session key returned from login Yes

get_devices_with_locations

Parameters
Parameter Purpose Default Required?
company uid of the company to filter by null No
sessionkey A session key returned from login Yes

get_product_types

Gets all product types as enum labels and values in a dict

No parameters

get_tag_types

Gets all tag types as enum labels and values in a dict

No parameters

get_tank_samples

Get a range of tank dips for a given device from start to end. If start is omitted then the start will be from the first available sample, if end is omitted, samples up to the most recent will be returned.

Samples are returned as a list of tuples where each tuple contains the timestamp and volume.

Parameters
Parameter Purpose Default Required?
end End date of sample range (as seconds since epoch) null No
sessionkey A session key returned from login Yes
start Start date of sample range (as seconds since epoch) null No
tank_uid A tank uid Yes

hello

Sends a greeting to who.

This is a test method, meant as a debugging aid.

Parameters
Parameter Purpose Default Required?
who Name to greet Yes

hydip_get_customer_transactions

Gets customer transactions for the hydip app

Parameters
Parameter Purpose Default Required?
filters {} No
limit 10 No
page 1 No
sessionkey A session key returned from login Yes
tag_id Yes

hydip_get_tag_detail

Returns the data for the logged in tag

Parameters
Parameter Purpose Default Required?
sessionkey A session key returned from login Yes

hydip_get_tags

Returns tags for a hydip user

Parameters
Parameter Purpose Default Required?
filters {} No
limit 10 No
page 1 No
sessionkey A session key returned from login Yes

hydip_tag_add_mobile_reg

Adds the mobile reg id to the tag object

Parameters
Parameter Purpose Default Required?
id_type Yes
reg_id Yes
sessionkey A session key returned from login Yes

hydip_tag_login

Parameters
Parameter Purpose Default Required?
pin Tag pin number Yes
tag Tag name Yes

hydip_user_add_mobile_reg

Adds the mobile reg id to the EndUser object

Parameters
Parameter Purpose Default Required?
id_type Yes
reg_id Yes
sessionkey A session key returned from login Yes

hydip_user_login

Parameters
Parameter Purpose Default Required?
custid Customer id Yes
pin Customer pin number Yes

hydip_user_mute_all

Mutes notifications for a user

Parameters
Parameter Purpose Default Required?
mute True No
sessionkey A session key returned from login Yes

keep_alive

Does nothing except extend the session for another hour.

Parameters
Parameter Purpose Default Required?
sessionkey A session key returned from login Yes

login

Log in a user with credentials username and password.

Most of the json rpc methods require a login, so this should be the first call before anything else. If login is successful, this method will return a string containing the session key, this value should be passed to the other methods as a parameter called sessionkey.

If login is not successful this method will return an error state.

Sessions are automatically logged out, 60 minutes after the last request.

Parameters
Parameter Purpose Default Required?
password Password Yes
username Username Yes

logout

Log out a given session. Subsequent calls to methods requiring a login will fail.

Not really required, since sessions expire after 60 minutes, but this is good house-keeping, and can protect against potential exploits.

Parameters
Parameter Purpose Default Required?
sessionkey A session key returned from login Yes

sites.get_networks

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
sessionkey A session key returned from login Yes

sites.get_site_groups

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
network_key The uid of the network Yes
sessionkey A session key returned from login Yes

auth.connect_device

Connect a device with a user, and return an auth key.

Parameters
Parameter Purpose Default Required?
device_name Name of the device (max 100 chars). This text should be recognizable to the user. e.g. "Will's iPhone" Yes
device_token An ID to identify the device (max 40 chars). Yes
password User's password Yes
username User's username Yes

auth.login

Log in a user with credentials username and password.

Most of the json rpc methods require a login, so this should be the first call before anything else. If login is successful, this method will return a string containing the session key, this value should be passed to the other methods as a parameter called sessionkey.

If login is not successful this method will return an error state.

Sessions are automatically logged out, 60 minutes after the last request.

Parameters
Parameter Purpose Default Required?
password Password Yes
username Username Yes

auth.logout

Log out a given session. Subsequent calls to methods requiring a login will fail.

Not really required, since sessions expire after 60 minutes, but this is good house-keeping, and can protect against potential exploits.

Parameters
Parameter Purpose Default Required?
sessionkey A session key returned from login Yes

devices.get_devices_by_asset_tag

Parameters
Parameter Purpose Default Required?
asset_tag Asset tag of a device Yes
company_key The uid of the company Yes
network_key The uid of the network Yes
sessionkey A session key returned from login Yes

network.get_network_transactions

Get a list of transactions, with an option date range. If start and end are supplied, they should be given as seconds since the epoch.

A transaction contains the following information:

{
"tag": <string tag id>,
"device": <device key>,
"customer": <string customer id>,
"id": <string unique identifier for this transaction>,
"start": <float start time>, # as seconds since the epoch)
"stop": <float stop time>, # as seconds since the epoch
"seq_num": <integer sequence number>,
"product": <integer product enum (see fueltracking.import)>,
"volume": <float volume dispensed>,
"price": <float price of transaction>,
"unit_price": <float price per unit of volume>,
"status": <integer transaction status bits (see below)>
"dispenser_index": <integer index of dispense>,
"credit": <float credit applied>,
"debit": <float debit applied>,
"source": <integer source enum>,
"odometer": <integer value of odometer>,
"userid": <integer user ID>,
"hosenumber": <integer index of hose>,
"network_uid": <uuid uid of network>,
"currency_display": <string currency>,
"units_display": <string units of measurement (e.g litres)>,
"device_name": <string device name>,
"product_name": <string readable product label from enum>,
"credit_type": <string readable credit type label from enum>,
"dispenser_index": <string hose number>,
"user_friendly_tagid": <string user friendly tag id>
}

Transaction status bits:

INVALID_ID = 1 << 0
ID_SEARCH_FAIL = 1 << 1
OUT_OF_CREDIT = 1 << 2
PIN_INCORRECT = 1 << 3
PIN_ENTRY_TIMEOUT = 1 << 4
DISPENSE_TIME_EXCEEDED = 1 << 5
COMM_ERR = 1 << 6
PWR_FAIL = 1 << 7
BCB_COMM_FAIL = 1 << 8
USER_ID_ENTRY_TIMEOUT = 1 << 9
ODOMETER_ENTRY_TIMEOUT = 1 << 10
RESTRICTED_FUEL_BIT = 1 << 11
CREDIT_CHECK = 1 << 12

Transaction source enum:

UNKNOWN = 0 (not used)
DEVICE = 1 (transaction was a device)
ADMIN = 100 (transaction was from admin)

Parameters
Parameter Purpose Default Required?
end end time of transaction, or to last transaction if null null No
network_uid The uid of the network Yes
sessionkey A session key returned from login Yes
start start time of transaction range, or from earliest transaction if null null No

network.get_new_transactions

Get new transactions since a previous call.

This method retrieves new transaction based on an update_index. On the first call to this method, update_index should be 0, which will return all transactions. A new value for update_index will be returned along with the transactions. Subsequent calls should use the update_index from the previous calls. This ensures that only new transactions will be returned.

This method returns the following response. The list of transactions is in the same format as the get_network_transactions method.

{
"update_index": <integer update index>,
"transactions": <list of transactions>
}

Parameters
Parameter Purpose Default Required?
network_uid The uid of the network Yes
sessionkey A session key returned from login Yes
update_index The update index returned from a previous export, (send 0 first time) 0 No

network.get_recent_transactions

Get a list of recent transactions, default limit of 50.

A transaction contains the following information:

{
"tag": <string tag id>,
"device": <device key>,
"customer": <string customer id>,
"id": <string unique identifier for this transaction>,
"start": <float start time>, # as seconds since the epoch)
"stop": <float stop time>, # as seconds since the epoch
"seq_num": <integer sequence number>,
"product": <integer product enum (see fueltracking.import)>,
"volume": <float volume dispensed>,
"price": <float price of transaction>,
"unit_price": <float price per unit of volume>,
"status": <integer transaction status bits (see below)>
"dispenser_index": <integer index of dispense>,
"credit": <float credit applied>,
"debit": <float debit applied>,
"source": <integer source enum>,
"odometer": <integer value of odometer>,
"userid": <integer user ID>,
"hosenumber": <integer index of hose>,
"network_uid": <uuid uid of network>,
"currency_display": <string currency>,
"units_display": <string units of measurement (e.g litres)>,
"device_name": <string device name>,
"product_name": <string readable product label from enum>,
"credit_type": <string readable credit type label from enum>,
"dispenser_index": <string hose number>,
"user_friendly_tagid": <string user friendly tag id>
}

Transaction status bits:

INVALID_ID = 1 << 0
ID_SEARCH_FAIL = 1 << 1
OUT_OF_CREDIT = 1 << 2
PIN_INCORRECT = 1 << 3
PIN_ENTRY_TIMEOUT = 1 << 4
DISPENSE_TIME_EXCEEDED = 1 << 5
COMM_ERR = 1 << 6
PWR_FAIL = 1 << 7
BCB_COMM_FAIL = 1 << 8
USER_ID_ENTRY_TIMEOUT = 1 << 9
ODOMETER_ENTRY_TIMEOUT = 1 << 10
RESTRICTED_FUEL_BIT = 1 << 11
CREDIT_CHECK = 1 << 12

Transaction source enum:

UNKNOWN = 0 (not used)
DEVICE = 1 (transaction was a device)
ADMIN = 100 (transaction was from admin)

Parameters
Parameter Purpose Default Required?
company uid of the company to filter by Yes
limit Number of objects in a page. Default 50, max 1000 50 No
sessionkey A session key returned from login Yes

network.import

Import tag database. On success this method returns a dictionary containing statistics regarding the number of objects that were newly imported, modified or suspended. If the import fails for some reason an error code 7 will be returned, along with a (hopefully) helpful error message.

Customers and tags are given as a list of objects. Any enduser or tag that was previously imported, but not in this call will be marked as 'suspended'.

A customer should contain one or more of the following fields:

{
"id": <string customer id (required)>,
"name": <string customer name>,
"address1": <string address line 1>,
"address2": <string address line 2>,
"address3": <string address line 3>,
"zipcode": <string zipcode>,
"tel": <string telephone number>,
"mobile": <string mobile number>,
"notes": <string free notes field>,
"suspended": <boolean true if user is suspended>,
"balances": <list of balances, where a balance is a list of [<product enum>, <product value>]>,
"daily_limits": <list of balances, as balances, but the value may also be null>,
"payment_type": <integer payment type enum> (see below)
}

Payment type enum:

PRE_PAY = 0
DAILY_LIMIT = 1

The following is an example value for balances, were water is 100 liters and ADBLUE is 300 liters:

[[1, 100], [6, 300]]

A tag should contain one or more of the following fields:

{
"id": <string tag id (required)>,
"customer": <string id of customer who has this tag>,
"tag_type": <integer TAG=1, CARD=2, ODOM_REQ=3, UID_REQ=4, UID_ODOM_REQ=5 (required)>,
"credit_type": <integer CASH=1, VOLUME=2>,
"product_mask": <list of integers (see products enum below)>
"pin": <string for PIN number, or null for no PIN>,
"suspended": <boolean true if this card may not be used>,
"daily_limits": <list of per-tag daily limits, given as a list of [<product enum>, <product value>] (value may be null to indicate no limit)>,
"metered_product_daily_limit": <number for daily limit for volume tags with multiple products, or null>,
"vehicle_reg": <user defined vehicle reg number>,
"vehicle_model": <user defined vehicle model>,
"vehicle_fleet_no": <user defined vehicle fleet number>
}

Product enum:

RESERVED_0 = 0
WATER = 1
DIESEL = 2
PREMIUM_UNLEADED = 3
UNLEADED = 4
LEADED = 5
ADBLUE = 6
OIL = 7
LPG = 8
KEROSENE = 9
AVGAS = 10
JETA1 = 11
CNG = 12
MPD = 13
RESERVED_1 = 14
RESERVED_2 = 15

Parameters
Parameter Purpose Default Required?
customers A list of customers to import null No
network_uid The uid of the network Yes
sessionkey A session key returned from login Yes
tags A list of tags to add/modify null No

networks.get_networks

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
sessionkey A session key returned from login Yes

pricezones.get_pricezone

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
network_key The uid of the network Yes
pricezone_key The uid of the pricezone Yes
sessionkey A session key returned from login Yes

pricezones.get_pricezones

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
network_key The uid of the network Yes
sessionkey A session key returned from login Yes

pricezones.set_pricezone

The price_data parameter should be in the following format: { "water": "1.234", "diesel": "1.234", "premium_unleaded": "1.234", "unleaded": "1.234", "leaded": "1.234", "adblue": "1.234", "oil": "1.234", "lpg": "1.234", "kerosene": "1.234", "avgas": "1.234", "jeta1": "1.234", "cng": "1.234", "mpd": "1.234" }

You don't have to add every price, you can just include the ones that you want to change.

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
network_key The uid of the network Yes
price_data Dictionary of prices Yes
pricezone_key The uid of the priczone to update Yes
sessionkey A session key returned from login Yes

sites.get_site_objects

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
sessionkey A session key returned from login Yes
site_key The uid of the site Yes

sites.get_sites

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
network_key The uid of the network Yes
sessionkey A session key returned from login Yes
site_group_key The uid of the site group (optional) null No

sites.get_sites_with_objects_gps

Gets a list of sites in a network, and the gps coords of the site, devices and tanks

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
network_key The uid of the network Yes
sessionkey A session key returned from login Yes

sites.get_tank_samples

Get a range of tank dips for a given device from start to end. If start is omitted then the start will be from the first available sample, if end is omitted, samples up to the most recent will be returned.

Samples are returned as a list of tuples where each tuple contains the timestamp and volume.

Parameters
Parameter Purpose Default Required?
end End date of sample range (as seconds since epoch) null No
sessionkey A session key returned from login Yes
start Start date of sample range (as seconds since epoch) null No
tank_uid A tank uid Yes

sites.get_tanks_by_asset_tag

Parameters
Parameter Purpose Default Required?
asset_tag Asset tag of a device Yes
company_key The uid of the company Yes
network_key The uid of the network Yes
sessionkey A session key returned from login Yes

tanks.get_tank_groups

Gets the tank groups that the user has permission to see

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
network_key The uid of the network Yes
sessionkey A session key returned from login Yes

tanks.get_tanks

Get tank objects for network and company

Parameters
Parameter Purpose Default Required?
company_key The uid of the company Yes
network_key The uid of the network Yes
sessionkey A session key returned from login Yes
tank_group_key The uid of the tank group (optional) null No