Introduction

This describes the public resources that make up the official Juice API version v11.5.0. If you have any problems or requests please contact support@utiliflex.com. Through out this document the domain api.utiliflex.com is used purely as an example placeholder and will differ from system to system.

JuiceAPI Basic Information

This section describes the basics of working with the JuiceAPI in regards authorize requesting a specific API version, if available, the header and general body schema returned by the API, as well as details regarding error codes that may be returned by the API.

General Integration Information

The JuiceAPI is a HTTP RESTful interface that depending on the endpoint transfers data via URI parameters and query strings, or in a POST body with either JSON or CSV. The output of each call will ether be an empty body, in such cases the HTTP status code should be checked for success or failure or will be a JSON body following our Generic return structure format defined later in this section.

HTTP Header Schema

curl https://api.utiliflex.com/auth-test

HTTP/1.1 200 OK
Date: Fri, 12 Oct 2012 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive Status: 200 OK
X-Juice-Media-Type: juice.v1
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff

All API access is over HTTPS, and accessed from the https://api.utiliflex.com/. For all requests the API will return the Content-Type, Status, X-Juice-Media-Type, Content-Length, and Cache-Control headers.

The body of the response is in JSON with all timestamps, with the exception of the header, are in RFC3339 format: YYYY-MM-DDTHH:MM:SSZHH:MM

Parameters

curl "https:api.utiliflex.com/juicecards/verify?portal=foo"

Many API methods take additional parameters via the URI. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameters.

In this example, the verify value is provided for the :method parameters in the path while :portal is passed in the query string. For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’.

Generic Return Structure

All data returned from the API is wrapped in the same JSON envelope which consists of three fields.

Field	Type	Description
error	int	The error code, if any, for the request. If no error this field will be 0. See the section on Client Errors to see a list of possible error codes
error_message	string	Plain text error message describing the error. This field is omitted if there was no error processing the request.
data	object	The return data specific to the called method, see the appropriate document for the method being called for details on what may be in this field. This field may be omitted if there was an error.

Health Check

curl --request GET --url api.utiliflex.com:8080/health-check

{
  "error":0,
  "data":{
    "alive":true,
    "server_time":"2018-07-20T14:33:31.850901852-04:00"
  }
}

The health check endpoint does not require authentication, and can be used to check the current status of the API. This also causes the API to test its connection to the DataBase. If everything checks out this endpoint returns with the values alive: true and returns the current system time.

Handling Authentication to the API

There are two ways to authenticate with JuiceAPI, either with Basic Auth or using an API Token. Throughout the remaining of this document it is assumed that all calls use one of these authentication methods unless specified otherwise. The USERNAME and PASSWORD is the same credentials that are used to authenticate to the main Juice application, the API TOKEN is the system user’s API token that was generated by the system.

Authentication Checking (Basic Auth)

curl --request GET \
  --user USERNAME:PASSWORD \
  --url api.utiliflex.com:8080/auth-test

{
  "error":0,
  "data":{
    "status":"OK"
  }
}

Basic authentication sends the username and password as a Base64 encoded string in the HTTP headers, and is generally supported by most if not all tools and frameworks natively.

HTTP Request

Authorization: Basic dGVzdDoxMjPCow==

GET /auth-test

You must replace dGVzdDoxMjPCow== with the Base64 encoded version of your username and password, in username:password format.

Authentication Checking (OAuth)

curl --request GET \
  --url 'api.utiliflex.com:8080/auth-test' \
  --header 'Authorization: token jsmith:56d2bf16-9881-4e5d-bbeb-c79a72225a5b'

{
  "error":0,
  "data":{
    "status":"OK"
  }
}

Using a API token the username and the API token must be in the Authorization header field in the form of token USERNAME:TOKEN for the system to recognize the token and attempt to validate it.

HTTP Request

Authorization token USERNAME:TOKEN

GET /auth-test

Metering Functions

Getting List of Supported Meter Com Types

curl --request GET \
  --url 'api.utiliflex.com:8080/meters/com-types/get-supported'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/com-types/get-supported');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error":0,
  "data":{
    "AMR":{
      "com":"AMR"
    },
    "ByBot":{
      "com":"ByBot",
      "source":[
        {
          "name":"bybot",
          "pull_reads":true
        }
      ]
    },
    "DLMS":{
      "com":"DLMS",
      "source":[
        {
          "name":"microstar",
          "pull_reads":false
        }
      ]
    },
    "MAS":{
      "com":"MAS",
      "source":[
        {
          "name":"mas",
          "pull_reads":true
        }
      ]
    },
    "MultiSpeak":{
      "com":"MultiSpeak",
      "source":[
        {
          "name":"multispeak",
          "pull_reads":true
        }
      ]
    },
    "NES":{
      "com":"NES"
    }
  }
}

The JuiceAPI supports querying a list of supported meter communication types supported by Juice. The value of the com field is the name used by Juice to identify the specific communication type used by the meter(s), in cases where this communication method is an industry accepted standard the com type will be the name of that standard, e.g. MultiSpeak, the com type may also be specifically named for a meter manufacturer, e.g. NightHawk, for a communication type only used for meters by that company, or the com type may be integration specific to be able to work with a custom headend/MDM system.

The source → name field is the name used internally by the API when referring to incoming data, such as incoming meter reads, to denote the source of the data. The source → pull_reads field is used internally to determine if Juice needs to trigger the batch read requests or not.

HTTP Request

GET /meters/com-types/get-supported

Getting List of Meters

curl --requst GET \
  --url 'api.utiliflex.com:8080/meters/get-meters?portal=example&com=MultiSpeak'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/get-meters?portal=example&com=MultiSpeak');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error":0,
  "data":{
    "meters":[
      {
        "serial_number":"1234abcde",
        "com_type":"MultiSpeak"
      },
      {
        "serial_number":"AMI1234",
        "com_type":"MultiSpeak"
      }
    ]
  }
}

The JuiceAPI supports getting a list of all meters currently in the system for a specific portal, and optionally filtered by a specific communication type. This endpoint does not require authentication to use.

HTTP Request

GET /meters/get-meters?portal=<portal>&com=<com>

Query Parameters

Parameter	Description	Required
portal	The portal to query meters for	Yes
com	a specific com type to return values for	No

Getting Meter Details

curl --requst GET \
  --url 'api.utiliflex.com:8080/meters/get-meter?portal=example&serialnumber=1234abcde'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/get-meter?portal=example&serialnumber=1234abcde');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": {
    "portal": "test",
    "loc_id": "L03281",
    "account": "03280",
    "id": "1234abcde",
    "serial_number": "1234abcde",
    "name": "",
    "com": "MultiSpeak",
    "tariff": "SBT",
    "subtariff": "PrePaid",
    "type_id": "",
    "status_type_id": "",
    "service_status": 0,
    "sgc": "",
    "kva_demand_rating": 0,
    "vendable": 1,
    "meter_location": "",
    "misc_data": "",
    "meter_state": "DISCONNECTING",
    "installer": "",
    "units": "kWh",
    "factor": 1,
    "phases": 1,
    "ststi": "",
    "sts_key_rev": "",
    "sts_exp_num": 255,
    "sts_base_date": 0,
    "sts_version": 0,
    "disco_profile": "PendingAny",
    "breaker": "",
    "comments": "",
    "created": "2017-10-19T13:46:40-04:00",
    "last_mod": "2019-01-29T13:09:21-05:00",
    "type": "57",
    "form_factor": "",
    "wiring": "-",
    "current_per_phase": 0,
    "voltage_per_phase": 0,
    "frequency": 0,
    "ami_wallet": "units"
  }
}

This endpoint allows fetching basic meter details for a given meter, including the location ID and customer account it may or may not be attached to.

HTTP Request

GET /meters/get-meter?portal=<portal>&serialnumber=<serialnumber>

Query Parameters

Parameter	Description	Required
portal	The portal to query meters for	Yes
serialnumber	The meter serial number to fetch details for	Yes

Callback Response

curl --request POST \
  --url 'api.utiliflex.com:8080/meters/ami-control/callback?portal=examlpe&source=multispeak'
  --data '{
	"uuid": "6bce3e16-b6f9-418e-9751-44888850bbdf",
	"command": "READ",
	"result": "success",
	"error_code": 0,
	"error_msg": "",
	"data": [{
		"serial_number": "1234abcde",
		"reading": 100.24,
		"read_timestamp": "2019-05-08T22:50:10Z",
		"meter_state": "connected"
	}]
}'

<?php

$data = '{
	"uuid": "6bce3e16-b6f9-418e-9751-44888850bbdf",
	"command": "READ",
	"result": "success",
	"error_code": 0,
	"error_msg": "",
	"data": [{
		"serial_number": "1234abcde",
		"reading": 100.24,
		"read_timestamp": "2019-05-08T22:50:10Z",
		"meter_state": "connected"
	}]
}';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/ami-control/callback?portal=examlpe&source=multispeak');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

When Juice makes a request to the AMI/AMR headend/MDM system and the end results are posted in a separate REST call, the end results should be set to the callback endpoint or to an alternative callback URL that is provided by Utiliflex that takes in the POST body from the 3rd party headend system/MDM and translates the data to send to this endpoint.

This section is only relevant if not using an alternative callback URL, as that alternative endpoint will handle processing the data from the format sent by the headend/MDM system and will convert it to the following format and sent the data to the API automatically.

HTTP Request

POST /meters/ami-control/callback?portal=<portal>&source=<source>

Query Parameters

Parameter	Description	Required
portal	The portal for the meter(s) referenced in the response	Yes
source	A unique identifier specifying the source of the information coming back. The source should be present in the list of supported com types	Yes

Body

Name	Type	Description	Required
uuid	string	The unique identifier for the request that was generated by Juice	Yes
command	string	The command that was sent in the original request	Yes
result	string	Whether the result of the request was `success` or `fail`	No
error_code	int	The error code from the headend system (if any)	No
error_msg	string	The error message from the headend system (if any)	No
data	array of objects	Additional information regarding the request (see definition below)	No

Data Object

Name	Type	Description	Required
serial_number	string	The serial number of the meter	Yes
reading	float64	The current reading of the meter in Wh	No
read_timestamp	datetime	The time the reading was taken for the meter	No
meter_state	string	The state of the meter relay as reported by the headend system	No

Working With Meter Reads with JuiceAPI

Adding New Readings

metername,serialnumber,deviceid,datetime,multiplier,sumforwardactive,sumreverseactive,sumforwardreactive,sumreversereactive,meterstate
,1234abcde,,2017-11-16T07:00:00Z04:00,1.0,108.8,0,0,0,connected

[
  {
    "metername":"",
    "serialnumber":"1234abcde",
    "deviceid":"",
    "datetime":"2017-11-16T07:00:00-04:00",
    "multiplier":1.0,
    "sumforwardactive":0,
    "sumreverseactive":0,
    "sumforwardreactive":0,
    "sumreversereactive":0,
    "meterstate":"connected"
  }
]

curl --request POST \
  --url 'api.utiliflex.com:8080/meters/reads/insert?source=multispeak&format=CSV' \
  --data 'metername,serialnumber,deviceid,datetime,multiplier,sumforwardactive,sumreverseactive,sumforwardreactive,sumreversereactive,meterstate
,1234abcde,,2017-11-16T07:00:00Z04:00,1.0,108.8,0,0,0,connected'

<?php

$data = 'metername,serialnumber,deviceid,datetime,multiplier,sumforwardactive,sumreverseactive,sumforwardreactive,sumreversereactive,meterstate\n';
$data .= ',1234abcde,,2017-11-16T07:00:00Z04:00,1.0,108.8,0,0,0,connected';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, '');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
  "error":0,
  "data":{
    "parsed_reads":1
  }
}

In order to add new meter reads in a scheduled read scenario the follow data must be posted to the system in either CSV or JSON format.

This section is only relevant if not using an alternative URL, as that alternative endpoint will handle processing the data from the format sent by the headend/MDM system and will convert it to the following format and sent the data to the API automatically.

HTTP Request

POST /meters/reads/insert?portal=<portal>&source=<source>&watts=<watts>&volts=<volts>&format=<format>

Query Parameters

Parameter	Default	Description	Required
portal	''	The portal that the meter belongs to	No
source	''	The source of the readings	Yes
watts	false	If the value of the active fields are in watt hours (Wh) set to true for the value to be converted during import	No
volts	false	If the value of the reactive fields are in volt-ampere reactive (var) set to true for the value to be converted during import	No
format	''	Format of the body value, valid formats are CSV and JSON	Yes

POST Body

Field	Type	Description
metername	string	A descriptive name for the meter if any is provided
serialnumber	string	The unique serial number of the meter
deviceid	string	The unique ID of the meter/com device if different from the serial number
datetime	string	The effective date time for the meter reading, in `RFC3339` format
multiplier	double	Special multiplier for the meter/reading, defaults to 1.0
sumforwardactive	float	Positive active energy, default is for reading to be in kilowatt hours (kWh)
sumreverseactive	float	Negative active energy, default is for the reading to be in kilowatt hours (kWh)
sumforwardreactive	float	Positive reactive energy, default is for the reactive reading to be in Kilovolt-amperes reactive (kvar)
sumreversereactive	float	Negative reactive energy, default is for the reactive reading to be in Kilovolt-amperes reactive (kvar)
meterstate	string	The state of the meter relay at the time of the reading if reported by the headend/mdm system

Fetching Meter Reads For a Meter

curl --request GET \
  --url 'api.utiliflex.com:8080/meters/reads/get?serialnumber=AMI1234'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/reads/get?serialnumber=AMI1234');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": [
    {
      "portal": "example",
      "account": "03283",
      "locid": "L03290",
      "serialnumber": "AMI1234",
      "datetime": "2019-02-08T12:30:00-05:00",
      "multiplier": 1,
      "deviceid": "AMI1234",
      "source": "multispeak",
      "status": "U:67",
      "timezoneindex": 11,
      "lastmod": "2019-03-08T15:41:28-05:00",
      "sumforwardactive": 100000,
      "toubucket1wh": 100000
    },
    {
      "portal": "example",
      "account": "03283",
      "locid": "L03290",
      "serialnumber": "AMI1234",
      "datetime": "2019-03-08T15:00:00-05:00",
      "multiplier": 1,
      "deviceid": "AMI1234",
      "source": "jsmith",
      "status": "U:71",
      "timezoneindex": 11,
      "lastmod": "2019-03-08T15:42:02-05:00",
      "sumforwardactive": 200000,
      "usagediff": 100000,
      "toubucket1wh": 200000
    }
  ]
}

This endpoint returns a list of all meter reads in Juice for a given meter, optionally filtered to return reads only within a given date range.

HTTP Request

GET /meters/reads/get?serialnumber=<serialnumber>&from=<from date>&to=<to date>

Query Parameters

Field	Type	Description	Required
serialnumber	string	The serial number of the meter to fetch meter reads for	Yes
from	date	The beginning date for reads to fetch, in `YYYY-MM-DD` format	No
to	date	If used in conjunction with `from` sets an end date to fetch reads for, also in `YYYY-MM-DD`	No

JuiceAPI Flat File Importer

This section describes working with JuiceAPI’s flat file importer to import and update various information in the system. The format used by the Flat File Importer is CSV and supports both Unix and DOS line endings.

File Syntax

field1,field2
normal string,"quoted-field"

field1,field2
"the ""word"" is true","a ""quoted-field"""

field1,filed2
"Multi-line
field","comma is ,"

The file format is CSV, with Unix or DOS line endings. Fields may contain commas (,) and newlines (\n) only if the field is quoted in the source file with double quotes, fields may also contain double quotation marks only if they are properly escaped. Carriage returns (\r), used in DOS/Windows and Mac OS 9 and below line ending formats are silently ignored by the parser thus meaning if they are present in the source file it will not make a difference when parsing. Any lines that begin with # will be ignored by the parser, useful for adding line comments to the file. Line comments do not need to conform to CSV syntax rules.

Note: Per RFC 4180 double quotation marks are escaped with double quotation marks.

Trinity Data File Importer

The act of importing and/or updating customer, location, and meter information is done with the trinity data importer.

Location Import/Update File

locname,locaddr1,locaddr2,loccity,locstate,loczip,loclat,loclong,meterinstalldate,contract,serialnum
1009001,557-2026 Purus St.,,Watertown,TN,07367,,,2018-07-01,unassigned,unassigned

To import new location information into Juice or to update existing location information the following fields are used in the flat file:

Field	Type	Description	Blank	Updatable
locname	string	Unique identifiable name for the location e.g. CIS key	No	No
locaddr1	string	Location street address	No	Yes
locaddr2	string	Additional location street address information	Yes	Yes
loccity	string	Location city name	No	Yes
locstate	string	Location state name	No	Yes
loczip	string	Location Postal/Zip code	No	Yes
loclat	float	Location latitude information	Yes	Yes
loclong	float	Location longitude information	Yes	Yes
meterinstalldate	date	Date that the most recent meter install was, if there is a meter no meter on this location past or present enter `0000-00-00` for year-month-day	No	Yes
contract	string	Customer ID to attach to location	No	Yes
serialnum	string	Meter ID to attach to location	No	Yes

Note: Fields that indicate that they can be left blank still requires that the field be present in the file, just the value can be blank. If there is no meter and/or customer to assign to the customer then instead of leaving those fields blank indicate it by using unassigned as the field value.

Meter Import/Update File

serialnum,deviceid,comtype,tariff,sgc,ti,keyrev,keyexp,basedate,sts_version,maxpower,addactiveread,server,wallet,contract,locname
7084636088,7084636088,STS,SBT,600403,01,1,255,1993,4,,0,primary,currency,unassigned,unassigned
1234abcde,1234abcde,MultiSpeak,SBT,,,,,,,,0,primary,units,unassigned,1009001

To import new meter information into Juice or to update the existing meter information the following fields are used in the flat file:

Field	Type	Description	Blank	Updatable
serialnum	string	Meter serial number	No	No
deviceid	string	Meter ID number if different from serial number	Yes	Yes
comtype	string	Meter communication type, see Getting List of Supported Meter Com Types	No	Yes
tariff	string	Juice tariff for the meter	Yes	Yes
sgc	int	Supply Group Code for meter if STS meter	Yes	Yes
ti	string	Tariff index for meter if STS meter	Yes	Yes
keyrev	int	Key Revision Number if STS meter	Yes	Yes
keyexp	int	STS Key Expiry Number	Yes	Yes
basedate	int	Base date for STS TID rollover (4 digit year)	Yes	Yes
sts_version	int	STS protocol version (STS 4 or STS 6)	Yes	Yes
maxpower	int	Max power setting for meter if STS meter	Yes	Yes
addactiveread	float	Current reading on meter or Headend/MDM to import into Juice. If adding a zero read for a new meter set to `0`. Leave blank for STS	Yes	Yes
server	string	The key/identifier for the Headend system to use for this meter	Yes	Yes
wallet	string	The type of wallet in Juice that should be used to hold prepaid balance. Valid options are: `currency` and `units`	No	Yes
contract	string	Customer to attach to the meter	No	Yes
locname	string	Location to attach to the meter	No	Yes

Customer Import/Update File

contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum
5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,1009001,1234abcde

To import new customer information into Juice or update existing customer information the following fields are used in the flat file:

Field	Type	Description	Blank	Updatable
contract	string	Account/Contract ID from legacy system	No	No
name	string	Full name of customer	No	Yes
phone1	string	Preferred number to use for IVR notifications	No	Yes
phone2	string	Secondary number to use for IVR notifications	Yes	Yes
sms1	string	Preferred number for SMS notifications	No	Yes
sms2	string	Secondary number to use for SMS notifications	Yes	Yes
email	string	Email address to use for email notifications	No	Yes
address1	string	Street address for customer billing address	Yes	Yes
address2	string	Additional street address information	Yes	Yes
city	string	Name of city for customer billing address	Yes	Yes
state	string	Name of state/province for customer billing address	Yes	Yes
postalcode	int	Postal/Zip code for customer billing address	Yes	Yes
locname	string	ID of location in Juice to attache to customer	No	Yes
serialnum	string	ID of meter in Juice to attach to customer	No	Yes

Adding New Trinity Records

curl --request POST \
  --url 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=locations' \
  --data 'locname,locaddr1,locaddr2,loccity,locstate,loczip,loclat,loclong,meterinstalldate,contract,serialnum
1009001,557-2026 Purus St.,,Watertown,TN,07367,,,2018-07-01,unassigned,unassigned'

<?php

$data = 'locname,locaddr1,locaddr2,loccity,locstate,loczip,loclat,loclong,meterinstalldate,contract,serialnum';
$data .= '1009001,557-2026 Purus St.,,Watertown,TN,07367,,,2018-07-01,unassigned,unassigned';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=locations');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
  "error":0,
  "data":{
    "records_imported":1,
    "record_keys":[
      {
        "juice_key":"L03291",
        "external_key":"1009001"
      }
    ]
  }
}

curl --request POST \
  --url 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=meters' \
  --data 'serialnum,deviceid,comtype,tariff,sgc,ti,keyrev,keyexp,basedate,sts_version,maxpower,addactiveread,server,wallet,contract,locname
  1234abcde,1234abcde,MultiSpeak,SBT,,,,,,,,0,primary,units,unassigned,1009001'

<?php

$data = 'serialnum,deviceid,comtype,tariff,sgc,ti,keyrev,keyexp,basedate,sts_version,maxpower,addactiveread,server,wallet,contract,locname';
$data .= '1234abcde,1234abcde,MultiSpeak,SBT,,,,,,,,0,primary,units,unassigned,1009001';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=meters');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
  "error":0,
  "data":{
    "records_imported":1
  }
}

curl --request POST \
  --url 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=customers' \
  --data 'contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum
5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,L03291,0cb4fce5'

<?php

$data = 'contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum\n';
$data .= '5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,L03291,0cb4fce5';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=customers');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
  "error":0,
  "data":{
    "records_imported":1,
    "record_keys":[
      {
        "juice_key":"03284",
        "external_key":"5004000"
      }
    ]
  }
}

HTTP Request

POST /file-importer/trinity/import?portal=<portal>&table=<table>

Query Parameters

Parameter	Description	Required
portal	The name of the portal to import records information	Yes
table	The base table that these records should be inserted into. Valid options include: `customers`, `locations`, and `meters`	Yes

Requesting Import Key Mapping

curl --request GET \
  --url 'api.utiliflex.com:8080/file-importer/trinity/get-keys?portal=example&table=customers'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/get-keys?portal=example&table=customers');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": [
    {
      "juice_key": "00001",
      "external_key": "1005088"
    },
    {
      "juice_key": "00002",
      "external_key": "1024732"
    },
    {
      "juice_key": "00003",
      "external_key": "1024760"
    },
    {
      "juice_key": "00004",
      "external_key": "1020485"
    },
    {
      "juice_key": "00005",
      "external_key": "1020522"
    }
  ]
}

While JuiceAPI is capable of preforming lookups on foreign keys during the import/update process, it is also possible to have JuiceAPI return a list containing Juice’s internal key and the vendor provided external key during the initial import. This works on a per-table bases, and only for the customers and locations table.

HTTP Request

GET /file-importer/trinity/get-keys?portal=<portal>&table=<table>

Query Parameters

Parameter	Description	Required
portal	The name of the Juice portal to get keys for	Yes
table	The name of the table to get keys for, valid options are `customers` and `locations`	Yes

Update Existing Trinity Records

curl --request POST \
  --url 'api.utiliflex.com:8080/file-importer/trinity/update?portal=example&table=customers' \
  --data 'contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum
5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,1009001,0cb4fce5'

<?php

$data = 'contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum\n';
$data .= '5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,1009001,0cb4fce5';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/update?portal=example&table=customers');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
    "error": 0,
    "data": {
      "records_updated": 1,
        "record_keys": [
            {
                "juice_key": "03284",
                "external_key": "5004000"
            }
        ]
    }
}

Using the flat file importer it is also possible to update a subset of the trinity data (Customer, Location, Meter).

HTTP Request

POST /file-importer/trinity/update?portal=<portal>&table=<table>

Query Parameters

Parameter	Description	Required
portal	The name of the portal to update the records of	Yes
table	The base table to update. Valid options are: `customers`, `locations`, and `meters`	Yes

Bulk Balance Adjustment File Importer

Using the Bulk Balance Adjustment File Importer it is possible to import things like arrears as will as adjustments to a customers wallet balance within the system.

Adjustment File Definition

Both arrears and wallet adjustments use the same file definition

Field	Type	Description	Blank
account	string	Account number to apply the adjustment to, can be Juice key or foreign key if `foreignkeys=true`	No
startdate	datetime	When the arrears should take affect on the account, date must be in `RFC3339` format e.g. `YYYY-MM-DDTHH:MM:SSZhh:mm`. The `T` is the date and time separator and the `Z` denotes the offset from UTC. For wallet adjustments, both currency and unit, this field is unused and can be left blank.	Yes
amount	float	Amount to adjust wallet by or create a new arrears for. The amount must be represented without any kind of sign ($/+/-). For arrears and currency adjustments this value is a currency value, for unit wallet adjustments this value is in kWh.	No
paid	float	Sum currency amount already paid towards the arrears, for wallet adjustments leave blank.	Yes
payplan	string	Must be a numeric number followed with a percent sign (`%`) represented as a string value. If blank defaults to `100%`. For wallet adjustments, both currency and unit, this field is unused.	Yes

Importing Arrears Adjustment Data

curl --request POST \
  --url 'api.utiliflex.com/file-importer/balance-adj/arrears?portal=example' \
  --data 'account,startdate,amount,paid,payplan
03284,2018-07-23T00:00:00Z04:00,100.00,0.00,100%'

<?php

$data = 'account,startdate,amount,paid,payplan\n';
$data .= '03284,2018-07-23T00:00:00Z04:00,100.00,0.00,100%';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com/file-importer/balance-adj/arrears?portal=example');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
  "error":0,
  "data":{
    "records_imported":1,
    "customers":[
      {
        "account":"03284",
        "arrears_amount":"$100.00"
      }
    ]
  }
}

HTTP Request

POST /file-importer/balance-adj/arrears?portal=<portal>&debit=<debit>&credit=<credit>&foreignkeys=<fkeys>

Query Parameters

Parameter	Default	Description	Required
portal	''	The name of the portal to import the adjustments into	Yes
debit	1100	The Juice COA to debit in the GL entries, defaults to `1100` if left blank	No
credit	9100	The Juice COA to credit in the GL entries, defaults to 9100 if left blank	No
foreignkeys	false	Whether to use Juice Keys or foreign keys for account lookup, default is to use Juice keys	No

Importing Unit Wallet Adjustments

curl --request POST \
  --url 'api.utiliflex.com:8080/file-importer/balance-adj/units/fund?portal=example' \
  --data 'account,startdate,amount,paid,payplan
03284,,10,,'

<?php

$data = 'account,startdate,amount,paid,payplan';
$data .= '03284,,10,,';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/balance-adj/units/fund?portal=example');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
  "error":0,
  "data":{
    "imported":1
  }
}

HTTP Request

POST /file-importer/balance-adj/units/<type>?portal=<portal>

Query Parameters

Parameter	Description	Required
portal	The name of the portal to import the unit wallet adjustments into	Yes

Adjustment Types

The following adjustment types are currently supported:

Type	Description
fund	Adds the given amount to the customers wallet balance as a free issue
debit	Subtracts the given amount from the customers wallet balance

Importing Currency Wallet Adjustments

curl --request POST \
  --url 'api.utiliflex.com:8080/file-importer/balance-adj/currency/fund?portal=example' \
  --data 'account,startdate,amount,paid,payplan
03284,,10,,'

<?php

$data = 'account,startdate,amount,paid,payplan';
$data .= '03284,,10,,';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/balance-adj/currency/fund?portal=example');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
  "error":0,
  "data":{
    "imported":1
  }
}

HTTP Request

POST /file-importer/balance-adj/currency/<type>?portal=<portal>

Query Parameters

Parameter	Description	Required
portal	The name of the portal to import the currency wallet adjustments into	Yes

Adjustment Types

The following adjustment types are currently supported:

Type	Description
fund	Adds the given amount to the customers wallet balance as a free issue
debit	Subtracts the given amount from the customers wallet balance

Customers

Getting basic customer information

curl --request GET \
  --url 'api.utiliflex.com:8080/customers/get-customer?portal=example&account=03280'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/get-customer?portal=example&account=03280');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": {
    "account": "03280",
    "contract": "5003986",
    "portal": "test",
    "name": "Ringo Starr",
    "last_name": "Starr",
    "first_name": "Ringo",
    "phone_1": "14235290856",
    "phone_2": "",
    "sms_1": "14235290856",
    "sms_2": "",
    "email_1": "ringo@example.com",
    "email_2": "",
    "address_1": "3131 Mountain Creek RD",
    "address_2": "Apt 14A2",
    "city": "Chattanooga",
    "state": "TN",
    "postal_code": "37415",
    "created": "2017-10-19T13:47:09-04:00",
    "last_mod": "2019-04-16T15:58:28-04:00",
    "notify_days": 3,
    "email_notify": 1,
    "sms_notify": 0,
    "phone_notify": 0
  }
}

This endpoint allows fetching basic customer account information.

HTTP Request

GET /customers/get-customer?portal=<portal>&account=<account>

Query Parameters

Parameter	Description	Required
portal	The portal to query information for	Yes
account	The Juice account number for the customer to get details for	Yes

Getting a customers wallet balance

curl --request GET \
  --url 'api.utiliflex.com:8080/customers/wallet/get-value?portal=example&account=03280&serialnumber=1234abcde'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/wallet/get-value?portal=example&account=03280&serialnumber=1234abcde');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": {
    "account": "03280",
    "meter": {
      "1234abcde": {
        "unit_balance": 0.58,
        "units": "kWh",
        "est_amt": "$0.17"
      }
    }
  }
}

{
  "error": 0,
  "data": {
    "account": "03284",
    "meter": {
      "14155008478": {
        "currency_balance": "$30.00"
      }
    }
  }
}

This endpoint allows fetching a customer’s wallet balance, either the currency wallet or unit wallet depending on which one is used for the given meter. By default this endpoint returns the customer’s current wallet balance but can optionally return the balance at a given point.

HTTP Request

GET /customers/wallet/get-value?portal=<portal>&account=<account>&serialnumber=<serialnumber>&end_date=<datetime>

Query Parameters

Parameter	Description	Required
portal	The portal to query information for	Yes
account	The Juice account number for the customer to get the balance for	Yes
serialnumber	The meter serial number attached to the customer to get effective balance for	Yes
end_date	The cutoff date for wallet balances, used to fetch the balance at certain point. The datetime must be in `RFC3339` format	No

Getting multiple customers wallet balance

curl --request GET \
  --url 'api.utiliflex.com:8080/customers/wallet/get-values?portal=example&account=03280|03283|03284'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/wallet/get-values?portal=example&account=03280|03283|03284');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": [
    {
      "account": "03284",
      "meter": {
        "14155008478": {
          "currency_balance": "$30.00"
        }
      }
    },
    {
      "account": "03280",
      "meter": {
        "1234abcde": {
          "unit_balance": 0.58,
          "units": "kWh",
          "est_amt": "$0.17"
        }
      }
    },
    {
      "account": "03283",
      "meter": {
        "58027013": {
          "unit_balance": 238.78,
          "units": "kWh",
          "est_amt": "$20.05"
        },
        "AMI1234": {
          "unit_balance": 238.78,
          "units": "kWh",
          "est_amt": "$20.05"
        }
      }
    }
  ]
}

This endpoint allows fetching the wallet balance of one or more customer accounts limited to a max of 200 accounts per request. If any of the requested accounts have multiple meters attached this will report the effective wallet balance for each meter. By default this endpoint returns the customer’s current wallet balance but can optionally return the balance at a given point.

HTTP Request

GET /customers/wallet/get-value?portal=<portal>&account=<account>&end_date=<datetime>

Query Parameters

Parameter	Description	Required
portal	The portal to query information for	Yes
account	A list of Juice account numbers, separated with vertical bars `\|` limited to 200 accounts per request, of the customers to get the balance for	Yes
end_date	The cutoff date for wallet balances, used to fetch the balance at certain point. The datetime must be in `RFC3339` format	No

Managing Customer Arrears

This section documents managing a customers arrears through the use of the JuiceAPI, this involves listing current arrears owed by customers and in future updates directly managing the arrears balance, or creating new arrears directly

Getting A List of All Customer Accounts With Current Arrears

curl --request GET \
  --url 'api.utiliflex.com:8080/customers/arrears/all-owed-arrears?portal=example&details=true'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/arrears/all-owed-arrears?portal=example&details=true');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);


  "error": 0,
  "data": {
    "customers": [
      {
        "account": "00001",
        "arrears_amount": "-$12.50"
      },
      {
        "account": "00002",
        "arrears_amount": "-$1,765.75"
      },
      {
        "account": "00003",
        "arrears_amount": "-$445.16"
      },
      {
        "account": "00004",
        "arrears_amount": "-$330.30"
      },
      {
        "account": "00005",
        "arrears_amount": "-$681.77"
      }
    ]
  }
}

The all owed arrears endpoint returns a list of all customer accounts in Juice that have outstanding arrears balances, and the total for all their outstanding balance.

HTTP Request

GET /customers/arrears/all-owed-arrears?portal=<portal>

Query Parameters

Parameter	Description	Required
portal	The name of the portal to query arrears data for	Yes

Getting A List of Arrears By Arrears Type

curl --request GET \
  --url 'api.utiliflex.com:8080/customers/arrears/get-arrears/by-type?portal=example&arrears_coa=9100&details=true'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/arrears/get-arrears/by-type?portal=example&arrears_coa=9100&details=true');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": {
    "customers": {
      "03283": [
        {
          "account": "03283",
          "arrears_id": 5,
          "issued_date": "2019-04-18T14:31:41-04:00",
          "start_date": "2019-04-18T00:00:00-04:00",
          "arrears_type": "CIStransfer",
          "pay_plan": "100%",
          "arrears_amount": "-$100.00",
          "paid_amount": "$0.00",
          "outstanding_amount": "-$100.00"
        }
      ],
      "03284": [
        {
          "account": "03284",
          "arrears_id": 85,
          "issued_date": "2019-04-01T09:17:17-04:00",
          "start_date": "2019-04-01T00:00:00-04:00",
          "arrears_type": "CIStransfer",
          "pay_plan": "25%",
          "arrears_amount": "-$20.00",
          "paid_amount": "$20.00",
          "outstanding_amount": "$0.00",
          "payments": [
            {
              "created": "2019-04-04T10:32:44-04:00",
              "trans": 245,
              "type": "payment",
              "amount": "$12.50"
            },
            {
              "created": "2019-04-04T16:03:21-04:00",
              "trans": 252,
              "type": "payment",
              "amount": "$3.33"
            },
            {
              "created": "2019-04-04T16:03:21-04:00",
              "trans": 253,
              "type": "payment",
              "amount": "$0.25"
            },
            {
              "created": "2019-04-25T15:35:15-04:00",
              "trans": 291,
              "type": "writeoff",
              "amount": "$3.92"
            }
          ]
        }
      ]
    }
  }
}

Through the API it is also possible to get a list of all customer accounts that have an outstanding balance for a particular arrears type. As well as optionally show each payment details for each payment towards that arrears

HTTP Request

GET /customers/arrears/get-arrears/by-type?portal=<portal>&arrears_coa=<coa>&details=<details>

Query Parameters

Parameter	Type	Description	Required
portal	string	The system portal to get arrears list for	Yes
arrears_coa	string	The COA for the arrears type to return	Yes
details	bool	If set to `true` will return a list of payments made towards each arrears (default: `false`)	No

Getting A List of Arrears For A Customer

curl --request GET \
  --url 'api.utiliflex.com:8080/customers/arrears/get-arrears/for-customer?portal=example&account=03285&details=true'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/arrears/get-arrears/for-customer?portal=example&account=03285&details=true');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": {
    "customers": {
      "03285": [
        {
          "account": "03285",
          "arrears_id": 2,
          "issued_date": "2019-04-25T14:23:32-04:00",
          "start_date": "1970-01-01T00:00:00-05:00",
          "arrears_type": "Gimme5",
          "pay_plan": "100%",
          "arrears_amount": "-$0.44",
          "paid_amount": "$0.00",
          "outstanding_amount": "-$0.44"
        },
        {
          "account": "03285",
          "arrears_id": 1,
          "issued_date": "2019-04-25T14:22:44-04:00",
          "start_date": "2019-04-25T00:00:00-04:00",
          "arrears_type": "CIStransfer",
          "pay_plan": "25%",
          "arrears_amount": "-$1,000.00",
          "paid_amount": "$0.00",
          "outstanding_amount": "-$1,000.00"
        }
      ]
    }
  }
}

Through the API it is also possible to get a list of all arrears for a customer. As well as optionally show each payment details for each payment towards that arrears

HTTP Request

GET /customers/arrears/get-arrears/for-customer?portal=<portal>&account=<account>&details=<details>

Query Parameters

Parameter	Type	Description	Required
portal	string	The system portal to get arrears list for	Yes
account	string	The Juice account number for the customer to fetch arrears data for	Yes
details	bool	If set to `true` will return a list of payments made towards each arrears (default: `false`)	No

Arrears Management

This section describes the available endpoint for managing arrears and arrears types in Juice.

List Arrears Types

curl --request GET \
  --url 'api.utiliflex.com:8080/arrears/list-types?portal=example'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/arrears/list-types?portal=example');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": [
    {
      "portal": "%",
      "arrears_type": "Recovery ",
      "description": "Initial Meter Recovery",
      "coa": "1101",
      "last_mod": "2016-09-12T11:53:01-04:00",
      "selectable": true
    },
    {
      "portal": "%",
      "arrears_type": "PostPaid",
      "description": "PostPaid Recovery",
      "coa": "1102",
      "last_mod": "2016-09-12T11:53:01-04:00",
      "selectable": true
    },
    {
      "portal": "example",
      "arrears_type": "CIStransfer",
      "description": "Transfer from legacy CIS system",
      "coa": "9100",
      "last_mod": "2017-01-30T19:58:57-05:00",
      "selectable": true
    },
    {
      "portal": "%",
      "arrears_type": "FundsRecovery",
      "description": "Bad Funds Recovery",
      "coa": "9110",
      "last_mod": "2016-09-12T11:53:01-04:00",
      "selectable": true
    },
    {
      "portal": "%",
      "arrears_type": "FundsRecoveryFee",
      "description": "Bad Funds Recovery Fee/Fine",
      "coa": "4950",
      "last_mod": "2016-09-12T11:53:01-04:00",
      "selectable": true
    },
    {
      "portal": "%",
      "arrears_type": "TamperFine",
      "description": "Tamper Fine",
      "coa": "4959",
      "last_mod": "2016-09-12T11:53:01-04:00",
      "selectable": true
    },
    {
      "portal": "%",
      "arrears_type": "Installation",
      "description": "Installation",
      "coa": "4955",
      "last_mod": "2016-09-12T11:53:01-04:00",
      "selectable": true
    }
  ]
}

This endpoint returns a list of all arrears types that are available to any portal in the system as well as portal specific arrears types.

HTTP Request

GET /arrears/list-types?portal=<portal>

Query Parameters

Parameter	Description	Required
portal	The name of the portal to query arrears data for	Yes

Entries that have a portal value of % are available to any portal in the system.

Locations

Get Location Details

curl --request GET \
  --url 'api.utiliflex.com:8080/location/get-location?portal=example&locid=L03281'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/location/get-location?portal=example&locid=L03281');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": {
    "portal": "example",
    "loc_id": "L03281",
    "serial_number": "1234abcde",
    "account": "03280",
    "loc_name": "10029384",
    "loc_address_1": "3131 Mountian Creek Rd",
    "loc_address_2": " Apt 14A2",
    "loc_city": "Chattanooga",
    "loc_state": "TN",
    "loc_zip": "37415",
    "loc_lat": "",
    "loc_long": "",
    "substation": "",
    "transformer": "",
    "module": "",
    "socket": 0,
    "meter_installed": "2015-05-01T00:00:00-04:00",
    "created": "2017-10-19T13:46:00-04:00",
    "last_mod": "2017-12-19T13:37:17-05:00",
    "voltage": "120V",
    "kva": 0,
    "tariff": "SBT",
    "subtariff": "PrePaid",
    "type": "ANSI",
    "form_factor": "1S",
    "wiring": "2W",
    "current_per_phase": 100,
    "feeder": "",
    "unit": ""
  }
}

This endpoint allows fetching basic location information.

HTTP Request

GET /location/get-location?portal=<portal>&locid=<locid>

Query Parameters

Parameter	Description	Required
portal	The portal to query meters for	Yes
locid	The Juice location id for the location to get details for	Yes

Tariff Management

Create a new tariff

curl --request POST \
  --url 'api.utiliflex.com:8080/tariff/create' \
  --data '{
    "portal": "example",
    "name": "TestTariff",
    "desc": "An example flat rate tariff",
    "muni": "",
    "rate": 0.043,
    "units": "kWh",
    "type": 1,
    "fuel_charge": true,
    "levy1": false,
    "levy2": false,
    "levy3": false,
    "taxable": true,
    "fixed": false,
    "kva_fixed": false
}'

<?php

$data = '{
    "portal": "example",
    "name": "TestTariff",
    "desc": "An example flat rate tariff",
    "muni": "",
    "rate": 0.043,
    "units": "kWh",
    "type": 1,
    "fuel_charge": true,
    "levy1": false,
    "levy2": false,
    "levy3": false,
    "taxable": true,
    "fixed": false,
    "kva_fixed": false
}';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/tariff/create');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

This endpoint allows for the creating of a new tariff in Juice.

HTTP Request

`POST /tariff/create

POST Body fields

The post body must be an json encoded string with the following fields:

Field	Type	Description	Required
portal	string	The Juice portal for the tariff.	Yes
name	string	The name of the new tariff.	Yes
desc	string	Human readable description of the tariff.	Yes
muni	string	The municipality the tariff is valid for, if any.	No
rate	float	The base rate for all blocks on the tariff.	Yes
units	string	The units of measure this tariff is valid for, example units: `kWh`, `kL`, `BTU`, `kVAR`, `kVa`, etc…	Yes
type	int	The type of tariff to be created. See the Allowed Tariff Types table.	Yes
fuel_charge	bool	If the tariff should include fuel charges.	Yes
levy1, levy2, levy3	bool	If the tariff should include any additional levys.	Yes
taxable	bool	If the tariff should include taxes as part of the calculation.	Yes
fixed	bool	If the tariff should include any monthly fixed charges.	Yes
kva_fixed	bool	If the tariff should include any monthly kVa fixed charges.	Yes

Allowed Tariff Types

Key	Tariff Type
0	Time of Use Tariff, supports up to 9 buckets
1	Simple linear tariff
2	Block Tariff with 2 blocks
3	Block Tariff with 3 blocks
4	Block Tariff with 4 blocks
5	Block Tariff with 5 blocks
6	Block Tariff with 6 blocks
7	Block Tariff with 7 blocks
8	Block Tariff with 8 blocks
9	Block Tariff with 9 blocks

Listing Current Tariffs In Juice

curl --request GET \
  --url 'api.utiliflex.com:8080/tariff/all/get?portal=example'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/tariff/all/get?portal=example');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);

{
  "data" : [
    {
      "desc" : "Example Block Tariff",
      "id" : 2,
      "meter_count" : 1,
      "portal" : "example",
      "rate" : [
        {
          "ar_coa" : 1102,
          "coa" : 4000,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 64,
          "last_mod" : "2021-04-27T14:52:38-03:00",
          "rate" : 0.86,
          "rate_plan_desc" : "Fuel Charge",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "taxable" : true,
          "tier" : "A",
          "units" : "kWh",
          "usage_base_start" : 0
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 65,
          "last_mod" : "2019-06-10T16:36:43-03:00",
          "rate" : 1.4,
          "rate_plan_desc" : "Block 1",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B1",
          "units" : "kWh",
          "usage_base_start" : 0
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 66,
          "last_mod" : "2019-06-10T16:36:43-03:00",
          "rate" : 0.0456,
          "rate_plan_desc" : "Block 2",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B2",
          "units" : "kWh",
          "usage_base_start" : 75
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 67,
          "last_mod" : "2019-06-10T16:36:43-03:00",
          "rate" : 0.457,
          "rate_plan_desc" : "Block 3",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B3",
          "units" : "kWh",
          "usage_base_start" : 150
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 68,
          "last_mod" : "2019-06-10T16:36:43-03:00",
          "rate" : 0.045,
          "rate_plan_desc" : "Block 4",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B4",
          "units" : "kWh",
          "usage_base_start" : 400
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 69,
          "last_mod" : "2019-06-10T16:36:43-03:00",
          "rate" : 0.044,
          "rate_plan_desc" : "Block 5",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B5",
          "units" : "kWh",
          "usage_base_start" : 500
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 70,
          "last_mod" : "2019-06-10T16:36:43-03:00",
          "rate" : 0.043,
          "rate_plan_desc" : "Block 6",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B6",
          "units" : "kWh",
          "usage_base_start" : 600
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 71,
          "last_mod" : "2019-06-10T16:36:43-03:00",
          "rate" : 0.0429,
          "rate_plan_desc" : "Block 7",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B7",
          "units" : "kWh",
          "usage_base_start" : 700
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 72,
          "last_mod" : "2019-06-10T16:36:43-03:00",
          "rate" : 0.042951,
          "rate_plan_desc" : "Block 8",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B8",
          "units" : "kWh",
          "usage_base_start" : 800
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2050-01-01T23:59:59-03:00",
          "id" : 73,
          "last_mod" : "2019-06-10T16:36:43-03:00",
          "rate" : 0,
          "rate_plan_desc" : "Levy",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "tier" : "L",
          "units" : "kWh",
          "usage_base_start" : 0
        }
      ],
      "tariff" : "COMMERCIAL"
    },
    {
      "desc" : "Standard Block Tariff",
      "fixed" : [
        {
          "amount" : 12.5,
          "ar_coa" : "1102",
          "coa" : "4900",
          "desc" : "Fixed Charge",
          "id" : 1,
          "portal" : "example",
          "tariff" : "SBT",
          "taxable" : true
        }
      ],
      "id" : 3,
      "meter_count" : 2,
      "portal" : "example",
      "rate" : [
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2022-04-23T23:59:59-03:00",
          "id" : 82,
          "last_mod" : "2021-04-23T15:07:40-03:00",
          "rate" : 0.3573,
          "rate_plan_desc" : "Foo",
          "service" : "Electricity",
          "start_date" : "2021-04-22T00:00:00-03:00",
          "tier" : "B1",
          "units" : "kWh",
          "usage_base_start" : 0
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2022-04-23T23:59:59-03:00",
          "id" : 83,
          "last_mod" : "2021-04-23T15:07:40-03:00",
          "rate" : 0.357202,
          "rate_plan_desc" : "Bar",
          "service" : "Electricity",
          "start_date" : "2021-04-22T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B2",
          "units" : "kWh",
          "usage_base_start" : 500
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2022-04-23T23:59:59-03:00",
          "id" : 84,
          "last_mod" : "2021-04-23T15:07:40-03:00",
          "rate" : 0.3,
          "rate_plan_desc" : "Baz",
          "service" : "Electricity",
          "start_date" : "2021-04-22T00:00:00-03:00",
          "taxable" : true,
          "tier" : "B3",
          "units" : "kWh",
          "usage_base_start" : 1000
        }
      ],
      "tariff" : "SBT"
    }
  ],
  "error" : 0
}

This endpoint returns all tariffs configured in Juice with their currently active rates, as well as any associated fixed charges for each tariff.

HTTP Request

GET /tariff/all/get?portal=<portal>&selectmuni=<muni>&searchfor=<string>

Query Parameters

Parameter	Description	Required
portal	The Juice Portal to fetch tariff details for	Yes
selectmuni	Limit tariffs returned to this municipality	No
searchfor	Limit tariffs to those with this name	No

Fetching Current Details For a Single Tariff

curl --request GET \
  --url 'api.utiliflex.com:8080/tariff/current/get?portal=example&tariff=RESIDENTIAL'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/tariff/current/get?portal=example&tariff=RESIDENTIAL');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);

{
   "data" : {
      "desc" : "Residential rate",
      "id" : 1,
      "meter_count" : 3,
      "muni" : "Chattanooga",
      "portal" : "example",
      "rate" : [
         {
            "ar_coa" : 1102,
            "coa" : 4005,
            "end_date" : "2030-12-31T23:59:00-03:00",
            "id" : 1,
            "last_mod" : "2016-09-12T14:18:13-03:00",
            "rate" : 0.084,
            "service" : "Electricity",
            "start_date" : "2012-10-01T15:00:00-03:00",
            "taxable" : true,
            "tier" : "B1",
            "units" : "kWh",
            "usage_base_start" : 0
         },
         {
            "ar_coa" : 1102,
            "coa" : 4005,
            "end_date" : "2030-12-31T23:59:00-03:00",
            "id" : 2,
            "last_mod" : "2016-09-12T14:18:13-03:00",
            "rate" : 0.072,
            "service" : "Electricity",
            "start_date" : "2012-10-01T15:01:00-03:00",
            "taxable" : true,
            "tier" : "B2",
            "units" : "kWh",
            "usage_base_start" : 1200
         }
      ],
      "tariff" : "RESIDENTIAL"
   },
   "error" : 0
}

This endpoint returns the requested tariff with its currently active rates, as well as any associated fixed charges for the tariff.

HTTP Request

GET /tariff/current/get?portal=<portal>&tariff=<tariff>

Query Parameters

Parameter	Description	Required
portal	The Juice Portal to fetch tariff details for	Yes
tariff	The name of the tariff to fetch	Yes

Fetching Historical Details For a Single Tariff

curl --request GET \
  --url 'api.utiliflex.com:8080/tariff/historical/get?portal=example&tariff=SBT'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/tariff/historical/get?portal=example&tariff=SBT');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);

{
      "data" : {
      "desc" : "Standard Block Tariff",
      "fixed" : [
        {
          "amount" : 12.5,
          "ar_coa" : "1102",
          "coa" : "4900",
          "desc" : "Fixed Charge",
          "id" : 1,
          "portal" : "example",
          "tariff" : "SBT",
          "taxable" : true
        }
      ],
      "id" : 3,
      "meter_count" : 2,
      "portal" : "example",
      "rate" : [
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2021-04-21T23:59:59-03:00",
          "id" : 58,
          "last_mod" : "2021-04-21T16:04:46-03:00",
          "rate" : 0.3573,
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "tier" : "B1",
          "units" : "kWh",
          "usage_base_start" : 0
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2021-04-21T23:59:59-03:00",
          "id" : 59,
          "last_mod" : "2021-04-21T16:04:46-03:00",
          "rate" : 0.357202,
          "rate_plan_desc" : "Block 2",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "tier" : "B2",
          "units" : "kWh",
          "usage_base_start" : 500
        },
        {
          "ar_coa" : 1102,
          "coa" : 4005,
          "end_date" : "2021-04-21T23:59:59-03:00",
          "id" : 60,
          "last_mod" : "2021-04-21T16:04:46-03:00",
          "rate" : 0.3,
          "rate_plan_desc" : "Block 3",
          "service" : "Electricity",
          "start_date" : "2019-07-01T00:00:00-03:00",
          "tier" : "B3",
          "units" : "kWh",
          "usage_base_start" : 1000
        }
      ],
      "tariff" : "SBT"
    },
    "error" : 0
}

This endpoint returns the requested tariff with previous rates.

HTTP Request

GET /tariff/historical/get?portal=<portal>&tariff=<tariff>

Query Parameters

Parameter	Description	Required
portal	The Juice Portal to fetch tariff details for	Yes
tariff	The name of the tariff to fetch	Yes

Fetching Future Details For a Single Tariff

curl --request GET \
  --url 'api.utiliflex.com:8080/tariff/future/get?portal=example&tariff=SBT'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/tariff/future/get?portal=example&tariff=SBT');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);

{
   "data" : {
      "desc" : "Standard Block Tariff",
      "fixed" : [
         {
            "amount" : 12.5,
            "ar_coa" : "1102",
            "coa" : "4900",
            "desc" : "Fixed Charge",
            "id" : 1,
            "portal" : "test",
            "tariff" : "SBT",
            "taxable" : true
         }
      ],
      "id" : 3,
      "meter_count" : 2,
      "portal" : "test",
      "rate" : [
         {
            "ar_coa" : 1102,
            "coa" : 4005,
            "end_date" : "2042-04-24T23:59:59-03:00",
            "id" : 88,
            "last_mod" : "2021-04-23T15:07:40-03:00",
            "rate" : 0.3573,
            "rate_plan_desc" : "Foo",
            "service" : "Electricity",
            "start_date" : "2022-04-24T00:00:00-03:00",
            "tier" : "B1",
            "units" : "kWh",
            "usage_base_start" : 0
         },
         {
            "ar_coa" : 1102,
            "coa" : 4005,
            "end_date" : "2042-04-24T23:59:59-03:00",
            "id" : 89,
            "last_mod" : "2021-04-23T15:07:40-03:00",
            "rate" : 0.33,
            "rate_plan_desc" : "Bar",
            "service" : "Electricity",
            "start_date" : "2022-04-24T00:00:00-03:00",
            "tier" : "B2",
            "units" : "kWh",
            "usage_base_start" : 500
         },
         {
            "ar_coa" : 1102,
            "coa" : 4005,
            "end_date" : "2042-04-24T23:59:59-03:00",
            "id" : 90,
            "last_mod" : "2021-04-23T15:07:40-03:00",
            "rate" : 0.3,
            "rate_plan_desc" : "Baz",
            "service" : "Electricity",
            "start_date" : "2022-04-24T00:00:00-03:00",
            "tier" : "B3",
            "units" : "kWh",
            "usage_base_start" : 1000
         }
      ],
      "tariff" : "SBT"
   },
   "error" : 0
}

This endpoint returns the requested tariff with future rates.

HTTP Request

GET /tariff/future/get?portal=<portal>&tariff=<tariff>

Query Parameters

Parameter	Description	Required
portal	The Juice Portal to fetch tariff details for	Yes
tariff	The name of the tariff to fetch	Yes

Adding a Future Rate Plan to a Tariff

curl --request POST \
  --url 'api.utiliflex.com:8080/tariff/future/create' \
  --data '{
  "portal":"test",
  "tariff":"SBT",
  "start_date":"2019-05-01T00:00:00Z",
  "end_date":"2040-12-31T23:59:59Z",
  "service":"Electricity",
  "tier":"B1",
  "rate":0.3572,
  "usage_base_start":0,
  "units":"kWh",
  "coa":4005,
  "ar_coa":1102
}'

<?php

$data = '{
  "portal":"test",
  "tariff":"SBT",
  "start_date":"2019-05-01T00:00:00Z",
  "end_date":"2040-12-31T23:59:59Z",
  "service":"Electricity",
  "tier":"B1",
  "rate":0.3572,
  "usage_base_start":0,
  "units":"kWh",
  "coa":4005,
  "ar_coa":1102
}';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/tariff/future/create');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": [
    {
      "id": 56,
      "service": "Electricity",
      "tier": "B1",
      "rate": 0.3572,
      "start_date": "2019-05-01T00:00:00Z",
      "end_date": "2040-12-31T23:59:59Z",
      "last_mod": "2019-04-05T13:30:00-04:00",
      "usage_base_start": 0,
      "units": "kWh",
      "coa": 4005,
      "ar_coa": 1102
    }
  ]
}

This endpoint allows scheduling a future rate plan in Juice. If there is already a rate plan currently active on the tariff for the given tier then the end date for the current rate plan is updated so it expires when the new one should take effect. If the rate plan being added is a new tier/block for the tariff then it will be scheduled to go live on the start date without changing the other tiers.

HTTP Request

POST /tariff/future/create

POST Body fields

The post body must be an json encoded string with the following fields:

Field	Type	Description	Required
portal	string	The Juice portal for the tariff	Yes
tariff	string	The Tariff name to schedule the new rate plan for	Yes
start_date	datetime	The datetime when the rate plan should become active, the time stamp is in `RFC3339` format.	Yes
end_date	datetime	The datetime when the rate plan should expire, the time stamp is in `RFC3339` format	Yes
service	string	The type of utility this tariff rate is valid for. e.g. “Electricity”	Yes
tier	string	The tier/block for the rate, valid tiers are “B1” to “B8”, “A”, and “L”	Yes
rate	float	The rate that should be applied when applying the tariff during a purchase	Yes
usage_base_start	int	The point, in units, when this rate should kick in	Yes
units	string	The units being purchased, e.g. “kWh”, “kL”	Yes
coa	int	The COA Ledger that should be used when the tariff is used during a purchase. Default 4005	Yes
ar_coa	int	The COA Ledger that should be used for arrears against the tariff. Default 1102	Yes

If needing to add multiple rate blocks for a tariff, do so in seperate requests, setting the values of tier, rate, and usage_base_start for each block

Transactions

JuiceAPI exposes various endpoints and methods for working with Transaction data from Juice.

Exporting Transactions Data

curl --request GET \
  --url 'api.utiliflex.com:8080/transactions/dump?portal=example&end_date=2019-03-08T23:59:59-04:00'

<?php

$endDate = '2019-03-08T23:59:59-04:00';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, "api.utiliflex.com:8080/transactions/dump?portal=example&end_date=$endDate");
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": [
    {
      "vendor_number": "CEC",
      "login": "cashier1",
      "customer": {
        "account": "03284",
        "contract": "5004000",
        "name": "Palmer Guy",
        "serial_number": "14155008478"
      },
      "transaction": {
        "id": 230,
        "type": "cash",
        "trans_date": "2019-03-08T15:32:43-05:00",
        "arrears_payment": 10,
        "amount": 10,
        "kwh": 27.996,
        "check": {
          "number": 0,
          "name": ""
        }
      }
    },
    {
      "vendor_number": "",
      "login": "auto",
      "customer": {
        "account": "03283",
        "contract": "03283",
        "name": "Fred Fredburger",
        "serial_number": "AMI1234"
      },
      "transaction": {
        "id": 233,
        "type": "wallet",
        "trans_date": "2019-03-08T16:32:59-05:00",
        "arrears_payment": 0,
        "amount": 0.45,
        "kwh": 5.102,
        "check": {
          "number": 0,
          "name": ""
        }
      }
    }
  ]
}

It is possible to get to get a dump of all transactions within a 24 hour window of a given date time using the transaction dump endpoint. This endpoint expects two URL parameters, the name of the Juice portal to fetch data for and the ending date time in ISO-8601 format, the start date is calculated automatically.

To get a full days worth of transaction data use an end date similar to 2019-03-25T23:59:59-04:00, This will return all transactions between 2019-03-25 00:00:00 and 2019-03-25 23:59:59.

HTTP Request

GET /transactions/dump?portal=<portal>&end_date=<date>

Query Parameters

Parameter	Description	Required
portal	The Juice Portal to fetch transactions for	Yes
end_date	The cut off date for transaction dump in ISO-8601 format	Yes

Adjusting Customer Account Balance

curl --request POST \
  --url 'api.utiliflex.com:8080/transactions/adjust?portal=example' \
  --data 'account,startdate,amount,paid,payplan
03284,,10.25,,
03285,2019-04-04T10:14:00-04:00,-100,0,25%'

<?php

$data = 'account,startdate,amount,paid,payplan
03284,,10.25,,
03285,2019-04-04T10:14:00-04:00,-100,0,25%';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, "api.utiliflex.com:8080/transactions/adjust?portal=example");
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
  "error": 0,
  "data": {
    "processed": [
      "account 03284 credited $10.25",
      "account 03284 new arrears for -$100.00"
    ],
    "arrears_data": [
      {
        "account": "03284",
        "arrears_id": 298,
        "arrears_amount": "$100.00",
        "start_date": "2019-04-29T10:14:00-04:00",
        "arrears_type": "FundsRecovery"
      }
    ],
    "error": null
  }
}

Using this endpoint it is possible to Credit or Debit a customers account, in the form of currency wallet credits or the issuing of arrears. This endpoint takes in a CSV file of the same layout as defined in the Bulk Balance Adjustment File Importer section of this doc. The only difference in the file format in the file specification is that the amount field can have a negative number to denote that record is for an arrears creation rather than a wallet credit.

HTTP Request

POST /transactions/adjust?portal=<portal>

Query Parameters

Parameter	Description	Required
portal	The Juice Portal post adjustments for	Yes

Reversing Transactions

curl --request POST \
  --url 'api.utiliflex.com:8080/transactions/reverse' \
  --data '{"portal":"example","id":100,"life_note":"Transaction preformed on wrong account"}'

<?php

$data = '{"portal":"example","id":100,"life_note":"Transaction preformed on wrong account"}';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, "api.utiliflex.com:8080/transactions/reverse");
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);

{
    "data": {
        "account": "03280",
        "amount": "$10.00",
        "id": 595,
        "original_created":"2020-07-15T12:50:08-04:00",
        "type": "cash"
    },
    "error": 0
}

This endpoint allows for reversing transactions in Juice. The about which transaction to reverse for a portal must be sent in as JSON.

HTTP Request

POST /transactions/reverse

JSON Request

Key	Type	Description	Required
portal	string	The Juice portal the transaction is under	Yes
id	int	The Juice transaction ID to be reversed	Yes
life_note	string	The reason why the reversal should be done	Yes

System User Management

Generating a API Token for a User

curl --request GET \
  --url 'api.utiliflex.com:8080/systemuser/token/generate?portal=example&user=jsmith'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/token/generate?portal=example&user=jsmith');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
    "error": 0,
    "data": {
        "portal": "example",
        "user": "jsmith",
        "token": "7bac4120-8b8d-4c55-b47a-57349b8bd3c2"
    }
}

This endpoint generates a new API token for the given user.

HTTP Request

GET /systemuser/token/generate?portal=<PORTAL>&user=<USER>

Query Parameters

Parameter	Description	Required
portal	The name of the system portal to act on	Yes
user	The login for the system user to generate a token for	Yes

Creating a New System User

curl --request POST \
  --url 'api.utiliflex.com:8080/systemuser/create' \
  --data '{"portal":"example","login":"swarren","name":"Sarah Warren","phone_1":"15558675409","phone_2":"","sms_1":"15558675409","sms_2":"","email":"swarren@example.com","system_role":"CSR","external_vendor":false,"vendor_number":"CEC","vendor_limit":{"amount":1000000,"currency":"USD"},"special_limit":{"amount":100000,"currency":"USD"},"blocked_accounts":""}'

<?php

$data = '{"portal":"example","login":"swarren","name":"Sarah Warren","phone_1":"15558675409","phone_2":"","sms_1":"15558675409","sms_2":"","email":"swarren@example.com","system_role":"CSR","external_vendor":false,"vendor_number":"CEC","vendor_limit":{"amount":1000000,"currency":"USD"},"special_limit":{"amount":100000,"currency":"USD"},"blocked_accounts":""}';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/create');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close();

{
    "data": {
        "active": true,
        "blocked_accounts": "",
        "email": "swarren@example.com",
        "external_vendor": false,
        "login": "swarren",
        "name": "Sarah Warren",
        "phone_1": "15558765309",
        "phone_2": "",
        "portal": "example",
        "sec_level": 60,
        "sms_1": "15558765309",
        "sms_2": "",
        "special_limit": {
            "amount": 100000,
            "currency": "USD"
        },
        "system_role": "VENDOR",
        "vending_limit": {
            "amount": 1000000,
            "currency": "USD"
        },
        "vendor_number": "CEC"
    },
    "error": 0
}

This endpoint allows creating new system users in Juice, upon creation it returns basic user information similar to the Get Basic Information for User.

HTTP Request

POST /systemuser/create

Request Parameters

The request should be sent as a JSON encoded string with the following fields.

Field	Type	Description	Required
portal	string	The Juice portal for the new user	Yes
login	string	The login for the new Juice user	Yes
name	string	The name for the new Juice user	Yes
phone_1	string	The primary phone number for the user. This field should only contain digits only no formatting	No
phone_2	string	The secondary phone number for the user. This field should only contain digits only no formatting	No
sms_1	string	The primary mobile number for the user. This field should only contain digits only no formatting	No
sms_2	string	The secondary mobile number for the user. This field should only contain digits only no formatting	No
email	string	The email address for the user.	No
system_role	string	The system role for the new user. See Default System Roles for a list of supported roles.	Yes
external_vendor	bool	If set to `true` the new user will be created as an external vendor, otherwise it will be created as an internal user	Yes
vendor_number	string	The Juice vendor number the user belongs to.	Yes
vending_limit	Limit	The total amount that a user can vend to customers before needing to close out their batch	Yes
special_limit	Limit	The max amount the user can write off, reverse, debit/credit per action	Yes
blocked_accounts	string	A list of customer account numbers separated by commas (`,`). A wildcard (`*`) can be used to block access to all accounts.	Yes

Limit Object

Field	Type	Description	Required
amount	int	The limit amount in the smallest denomination for the currency e.g. $1,000.00 -> 100000	Yes
currency	string	The 3 character ISO 4217 code for the currency	Yes

Fetching Basic Information for a User

curl --request GET \
  --url 'api.utiliflex.com:8080/systemuser/get?portal=example&user=swarren'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/get?portal=example&user=swarren');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);

{
    "data": {
        "active": true,
        "blocked_accounts": "",
        "email": "swarren@example.com",
        "external_vendor": false,
        "login": "swarren",
        "name": "Sarah Warren",
        "phone_1": "15558765309",
        "phone_2": "",
        "portal": "example",
        "sec_level": 60,
        "sms_1": "15558765309",
        "sms_2": "",
        "special_limit": {
            "amount": 100000,
            "currency": "USD"
        },
        "system_role": "VENDOR",
        "vending_limit": {
            "amount": 1000000,
            "currency": "USD"
        },
        "vendor_number": "CEC"
    },
    "error": 0
}

This endpoint fetches basic information for a system user in Juice.

HTTP Request

GET /systemuser/get?portal=<PORTAL>&user=<LOGIN>

Query Parameters

Parameter	Description	Required
portal	The name of the system portal to act on	Yes
user	The login for the system user to fetch information for	Yes

Updating User Information

curl --request POST \
  --url 'api.utiliflex.com:8080/systemuser/update' \
  --data '{"portal":"example","login":"swarren","name":"Sarah Warren","phone_1":"15558675409","phone_2":"","sms_1":"15558675409","sms_2":"","email":"swarren@example.com","system_role":"CSR","external_vendor":false,"vendor_number":"CEC","vendor_limit":{"amount":1000000,"currency":"USD"},"special_limit":{"amount":1000000,"currency":"USD"},"blocked_accounts":""}'

<?php

$data = '{"portal":"example","login":"swarren","name":"Sarah Warren","phone_1":"15558675409","phone_2":"","sms_1":"15558675409","sms_2":"","email":"swarren@example.com","system_role":"CSR","external_vendor":false,"vendor_number":"CEC","vendor_limit":{"amount":1000000,"currency":"USD"},"special_limit":{"amount":1000000,"currency":"USD"},"blocked_accounts":""}';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/update');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close();

{
    "error": 0
}

This endpoint allows updating system users in Juice.

HTTP Request

POST /systemuser/update

Request Parameters

The request should be sent as a JSON encoded string with the following fields.

Field	Type	Description	Required
portal	string	The Juice portal for the user	Yes
login	string	The login for the Juice user	Yes
name	string	The name for the Juice user	Yes
phone_1	string	The primary phone number for the user. This field should only contain digits only no formatting	No
phone_2	string	The secondary phone number for the user. This field should only contain digits only no formatting	No
sms_1	string	The primary mobile number for the user. This field should only contain digits only no formatting	No
sms_2	string	The secondary mobile number for the user. This field should only contain digits only no formatting	No
email	string	The email address for the user.	No
system_role	string	The system role for the user. See Default System Roles for a list of supported roles.	Yes
external_vendor	bool	If set to `true` the user will be created as an external vendor, otherwise it will be created as an internal user	Yes
vendor_number	string	The Juice vendor number the user belongs to.	Yes
vending_limit	Limit	The total amount that a user can vend to customers before needing to close out their batch	Yes
special_limit	Limit	The max amount the user can write off, reverse, debit/credit per action	Yes
blocked_accounts	string	A list of customer account numbers separated by commas (`,`). A wildcard (`*`) can be used to block access to all accounts.	Yes

Limit Object

Field	Type	Description	Required
amount	int	The limit amount in the smallest denomination for the currency e.g. $1,000.00 -> 100000	Yes
currency	string	The 3 character ISO 4217 code for the currency	Yes

Fetching Permission List for a User

curl --request GET \
  --url 'api.utiliflex.com:8080/systemuser/perms/get?login=jsmith'

<?php

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/perms/get?login=jsmith');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close();

{
  "error": 0,
  "data": {
    "role": "VENDOR",
    "perms": [
      {
        "category": "Account",
        "name": "passwd",
        "description": "Change Password"
      },
      {
        "category": "Account",
        "name": "balance",
        "description": "Drawer Balance and Batch"
      },
      {
        "category": "Account Screen",
        "name": "tabcoms",
        "description": "Coms: SMS/Email/IVR/Issues",
        "long_description": "Allows access to Com tab showing all Juice generated customer communications."
      },
      {
        "category": "Account Screen",
        "name": "tabcontrol",
        "description": "Control Tab",
        "long_description": "Allows access to manage tariff, location, meter, vending, and more. Commercial services agents and customer service managers should have access and review training documents before using."
      }
    ]
  }
}

This endpoint returns a detailed list of all enabled permissions for the given user.

HTTP Request

GET /systemuser/perms/get?login=<LOGIN>

Query Parameters

Parameter	Description	Required
login	The login for the system user to fetch permissions for	Yes

Updating Permission List for User

curl --request POST \
  --url 'api.utiliflex.com:8080/systemuser/perms/update' \
  --data '{"portal":"example","login":"jsmith","vendor_number":"CEC","perms":[{"name":"passwd","action":"keep"},{"name":"balance","action":"keep"},{"name":"tabcoms","action":"remove"},{"name":"tabcontrol","action":"keep"},{"name":"vendcash","action":"add"}]}'

<?php

$data = '{"portal":"example","login":"jsmith","vendor_number":"CEC","perms":[{"name":"passwd","action":"keep"},{"name":"balance","action":"keep"},{"name":"tabcoms","action":"remove"},{"name":"tabcontrol","action":"keep"},{"name":"vendcash","action":"add"}]}';

$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/perms/update');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close();

{
  "error": 0,
  "data":  {
    "role": "VENDOR",
    "perms": [
      {
        "category": "Account",
        "name": "passwd",
        "description": "Change Password"
      },
      {
        "category": "Account",
        "name": "balance",
        "description": "Drawer Balance and Batch"
      },
      {
        "category": "Account Screen",
        "name": "tabcontrol",
        "description": "Control Tab",
        "long_description": "Allows access to manage tariff, location, meter, vending, and more. Commercial services agents and customer service managers should have access and review training documents before using."
      },
      {
        "category": "Vending",
        "name": "vendcash",
        "description": "Vend Cash",
        "long_description": "Allows user to vend power with cash payment."
      }
    ]
  }
}

This endpoint allows updating the set permissions for the user. After the update is done, it returns the new list of permissions.

HTTP Request

POST /systemuser/perms/update

Request Parameters

The request should be sent as a JSON encoded string with the following fields.

Field	Type	Description	Required
portal	string	The Juice portal the user belongs to.	Yes
login	string	The login for the system user to update permissions for.	Yes
vendor_number	string	The Juice vendor number the user belongs to.	Yes
perms	[]Perm	Array of perms to enact on.	Yes

Perm Object

Field	Type	Description	Required
name	string	Name of the permission.	Yes
action	string	Action to take for the perm. Valid options are: `add`, `remove`, `keep`	Yes

If a permission should not be changed it can be omitted from the perms array.

Default System Roles

Juice has the following system roles:

Role	Description
CSR	Standard Customer Service Representative / Cashier
CSR2	Customer Service Representative / Cashier level 2
CSR3	Customer Service Representative / Cashier level 3
ComMGR	Commercial Manager
VENDOR	Standard External Vendor
VENDORADM	External Vendor Admin
Engineer	Standard Utility Engineer
Accounting	Accounting / Finance Team Member
SysAdmin	Juice System Admin

Client Error Codes

JuiceAPI uses the following error codes in the error field of the returned JSON. These error codes are used in tandem with the appropriate HTTP error code.

Error Code	Meaning
100	Invalid or no credentials passed to the system.
101	User lacks the required permissions for action.
200	Unknown or invalid method or endpoint
201	Invalid or missing parameter given, more details provided in error_message field.
300	General application error, more details provided in error_message field.

Errors

The JuiceAPI uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request is invalid.
401	Unauthorized – Your API key is wrong.
403	Forbidden – You do not have the required permissions to access the requested resource.
404	Not Found – The specified resource could not be found.
405	Method Not Allowed – The request method is not allowed for this endpoint.
406	Not Acceptable – Either the request or the given parameters are invalid.
410	Gone – The requested resource no longer exists.
418	I’m a teapot.
429	Too Many Requests – You’re making to many requests within a short period of time! Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

HTTP Verbs

Where possible API strives to use appropriate HTTP verbs for each action.

Verb	Description
HEAD	Can be issued against any resource to get just the HTTP header info.
GET	Used for retrieving resources
POST	Used for creating resources
PATCH	Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.
PUT	Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE	Used for deleting resources

Note: Currently only POST and GET methods are fully supported by the API. The PUT, PATCH, HEAD, and DELETE methods may not be supported or implemented by the specific endpoint. This is by design as not all endpoints will support the PUT, PATCH, and DELETE methods, support for HEAD method is currently pending and may not get implemented in version 1 of the API.

HTTP Redirects

JuiceAPI uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests.

Status Code	Description
301	Permanent redirection. The URI you used to make the request has been superseded by the one specified in the `Location` header field. This and all future requests to this resource should be directed to the new URI.
302 - 307	Temporary redirection. The request should be repeated verbatim to the URI specified in the `Location` header field but clients should continue to use the original URI for future requests.