Utility Cloud API Quick Start Guide

Utility Cloud is the software platform you use to automate, standardize, and organize your utility data. In this way, you can easily and accurately calculate carbon impact, optimize sustainability initiatives, analyze costs, identify issues, and create efficient payment processes.

Main Concepts

Utility Cloud (UC) is built around a set of core technology concepts that you will work with when integrating your solutions with UC:

UC provides a REST API that provides a programmatic interface to your utility data. You can see the full API documentation here.

UC supports the use of webhooks, while optional, it is the recommended
implementation pattern. Webhooks are used to send notifications on important events
in the system. For example, a message that new data is available in one of your
accounts, or an alert that a credential status change requires your action.

In addition to API and the Dashboard, also included with UC at no additional cost is our
Connect application. This is a stand-alone hosted web page providing a pre-built user experience that you can style and include in your own application and business process to quickly get up and running. You can embed the experience into an existing web app via iFrame, send the URL via email to internal users to assist in collecting utility portal credentials, or make it accessible to customers as a link or button on an existing web site.

Set-Up Steps

The following guide will help you to set-up your Utility Cloud environment and get started. Example python scripts are shown below to illustrate the key concepts. Sample python scripts are also available for download on GitHub to kick-start your work with Utility Cloud.

Log into your UC tenant for the first time
a. Arcadia will create a tenant in our infrastructure and send an email to you to
enable access to UC.
b. You will receive the email from [email protected] with your username
and a temporary password.
c. The link in the email will send you to the UC Dashboard log-in page at
https://console.urjanet.com/ where you will be prompted to set your permanent password. The username and updated password will be what you use to access the Dashboard as well as authenticate against the API.
d. You can update your admin password at any time in the Dashboard at
MyAccount/MyProfile/ResetPassword. If you have forgotten your
UC access credentials, there are links on the Dashboard log-in page to retrieve
your username and reset password.

Test your API access

a. UC uses bearer tokens to authenticate API requests. To obtain a token and
verify you have API access, use: POST /auth/login with the username
and password you previously set up. Tokens expire after 1 hour. In cases where a request response returns a 401 status code, that is an indication that you will need to obtain a fresh token. Once you obtain a new token, update the header param sent with your API request. For example, in Python:

import json  
import requests

def getToken(username, password, authurl):  
  authdata = { 'username' : username, 'password' : password }
  authreq = requests.post(authurl, data=json.dumps(authdata), verify=False)
  token = None
  if authreq.status_code == 200:  
    response = authreq.json()  
    token = response['token']  
  return token

username = ‘your-username'  
password = 'your-password'  
authurl = '<https://api.urjanet.com/auth/login'>  
token = getToken(username, password, authurl)  
headers = { 'Authorization' : 'Bearer ' + token }

Configure your webhook endpoint

a. Your production webhook end-point needs to be set up in an environment that
you can access and manage. For the initial set up and validation you may
consider using a free service that allows you to inspect and test webhooks, such
as RequestBin, Beeceptor, or Webhook.site.
b. In the Dashboard, you input your webhook URL at
MyAccount/Configurations. Alternatively, you can perform this
action via API by Patch Organization/{organizationId}
Add additional user accounts to your UC tenant

a. UC administrative and configuration settings are accessed under MyAccount.
You open this menu by clicking on Your Name in the Dashboard top nav bar.
b. Create additional user accounts at MyAccount/ManageUsers/AddNewUser. You will be prompted to provide their Name, a Username, their Email address, and Role. Their Role is one of: Admin, Standarad or No Access. Admin allows for full system access including APIs and the ability to add and delete users. Only Admin roles can view sensitive data, including passwords. Also note that this can be disabled as an organization-wide setting. Please contact your Arcadia Success
Representative to learn more about how to manage your organization’s
security options. Standard User allows for view only access in the Dashboard. No Access which creates the account but does not allow for Dashboard or API access.
c. The new user will receive an email with their username, a temporary password,
and a link to Dashboard where they will be prompted to create their permanent
password.
d. You can delete users or change their Role, at MyAccount/ManageUsers.
e. You can also perform these tasks programmatically via API using POST /users, for example to create a new tenant user in python:
```
baseurl = '<https://api.urjanet.com/'>  
headers = { 'Authorization' : 'Bearer ' + token }  
userdata = {
    "accountEnabled": True,  
    "autoGeneratePassword": False,  
    "credentialsExpired": False,  
    "email": "[[email protected]](mailto:[email protected])",  
    "name": "yourname",  
    "organization": “yourorganizationID”,  
    "password": "yourpassword",  
    "passwordConfirm": "yourpassword",  
    "roles": “yourroleID”,  
    "username": "yourusername"
}

userreq = requests.post(
    baseurl+'users',
    headers = headers,
    data=json.dumps(userdata),
    verify=False
)
```
Create custom data fields

a. Custom data fields are optional attributes that are used to associate data in UC
with external data managed in a separate system. The data associated with
these fields is provided by you, stored in UC, and returned in API responses to
enable custom workflows and reporting. For example, it may be a primary key used to associate UC utility account data with a customer ID in a separate CRM system. Or alternatively it may be used as a category or type label to organize UC data according to your own analysis needs.
b. You can create custom fields at MyAccount/CustomData. UC supports up to
ten different variables that can be tracked for Account or Meter level data.
c. You can change custom data field labels at any time. This only affects the field
name itself. Account or meter data previously stored for that variable will not
change.
d. Custom data can be added or modified in the Dashboard for an individual account or meter by selecting one and navigating to its Attributes tab. Typing into the field and saving the result will update that account or meter with the new
information.
e. You can also perform these tasks programmatically via API PATCH /utility/organization, for example in python:
```
datafields = {
  'accountCustomData1Name':  
  'yourfieldname','accountCustomData2Name':  
  'yourfieldname','meterCustomData1Name': 'yourfieldname'
}
customdata = requests.patch(
  baseurl+'utility/organization',
  headers = headers,
  data=json.dumps(datafields)
)
```
Create sites

a. Sites are intended to reflect a real-world location and are used to organize and
aggregate information. A site may be a single address, a specific asset, or some
larger hierarchical grouping (such as a campus, for example). Sites are designed
to be associated with meter-level service addresses. Frequently, especially for
commercial accounts, the service address and the billing mailing address are not the same. Note accordingly, account-level billing addresses are not equivalent to
sites and service location addresses.
b. You can create a new site in the Dashboard at Sites/CreateSite. You can
also import a list of multiple sites to perform this as a bulk action using the
following steps: From the Dashboard Sites/CreateSite/ImportMultipleSites; Download the CSV template from the Import Sites dialog; Fill in the downloaded Sites.csv file; Upload the file; When the sites are created you will receive an email notification, typically within 1 or 2 minutes.
c. Sites have a predefined set of commonly used custom data fields: siteCode,
siteNumber, region, subregion, and facilityType. These labels are fixed and
cannot be updated. Like account and meter level custom fields, these are
optional, the data for these site fields is provided by you and is used to organize
and associate UC data with your own reference data.
d. Please note that creating your own sites is optional. If you do not create custom
sites, UC can be set up to automatically create them for you, each time a new
utility service address is found. You can also modify site information and
reassign the associated meter data amongst sites as necessary. See section 10
below for additional steps.
e. You can create new sites using the API with POST /utility/sites. For
example, in python:
```
sitefields = {
  "city": "yourcity",
  "country": "yourcountry",
  "facilityType": "",
  "postalCode": "yourzip",
  "region": "",
  "siteCode": "",
  "siteName": "yoursitename",
  "siteNumber": "",
  "subRegion": "",
  "state": "yourstate",
  "streetLine1": "yourstreet",
  "streetLine2": ""
}
newsite = requests.post(
  baseurl+'utility/sites',
  headers=headers,
  data=json.dumps(sitefields)
)
```
Configure Connect

a. Connect is a web application that you can optionally use as an out-of-the-box
experience for your end-customers or employees to securely enter utility
account log-in credentials into UC.
b. You access Connect settings at MyAccount/Connect. This is where you can
access and copy the Connect URL. This URL cannot be changed, and it is specific
to your UC tenant.
c. If you wish to include a terms of service or privacy policy in the Connect user
workflow, add a link to your relevant terms and policy. If one or both of these
fields are populated, it will automatically create a required check-box in Connect
asking that users agree to these documents.
d. If you wish to filter specific utilities from being shown to users in Connect, you
can update the criteria atMyAccount/Connect/ChangeConfigurations. UC supports a toggle to hide utilities that are not-RTCV (real time credential validation) enabled, those that have MFA (multi-factor authentication), beta providers (experimental UC utility integrations), and Mock (test) providers.
e. If you wish to change the styling of Connect to reflect your organization’s brand
color scheme you can update the Hex color code. If you wish to use custom CSS
in Connect, please contact your support representative for instructions.
f. In addition to being served as a standalone web page, Connect can be delivered
via an iFrame as part of your web application. The iFrame HTML tag is on the
MyAccount/Connect page. The default size is 800x800 px. The Connect
iFrame can be configured to emit events that can be used to create the ideal
user workflow in conjunction with your own application. Please see this article
for configuration options.
g. Note also that Connect supports the passing of URL parameters. For example, https://connect.urjanet.com/yourspecificURL?correlationId=CUST123&primaryColor=black. The above example will set the correlationID for this linked account to “CUST123” and will change the primary color for the web experience to “Black”
Link your accounts

a. Credentials are the fields necessary to access a utility web portal account.
Typically, it is username and password, but can vary by utility. The required fields
are automatically populated in the Dashboard and Connect for the selected utility.
b. You can manually create credentials in the Dashboard using AddCredentials or at the Connect URL web page. You will be prompted to select the utility and
enter the required web account access credentials. Upon completion you will
see either success, pending or failure in the Dashboard as well as a webhook event.
c. Credentials have their own pre-defined custom data field: correlationId. This is
commonly used to associate utility account log-in credentials with its user
account data maintained in a CRM or customer database.
d. Once credentials are successfully created in UC, the system will continue to
retrieve information from the utility on an ongoing basis. You can unsubscribe/pause utility data collection for the credential, add or modify the correlationId, as well as get a URL link to send to end-users so they can securely update their credentials (ie., in the event the password has changed or expired) at Credentials/{selectedcredential}/Details.
e. Arcadia can help you create, onboard, and manage utility web credentials if you
don’t already have them set up. Arcadia can also support enrollment of
credentials in bulk from a file. Contact Arcadia Customer Success to discuss
various custom support services.
f. Programmatically you can submit credentials via the API using POST /utility/credentials instead of using the Connect end-user application. It
first requires that you pass the utility provider identifier and the required fields
necessary for account access. For example, in python:
```
providerquery = 'providerName==Virginia\*'  
providers = requests.get(
  baseurl+'utility/providers?search='+providerquery,
  headers = headers
)
```
To facilitate finding the utility, the UC API supports RSQL queries. In the example above we are looking for utilities with "Virginia" in the name. For RSQL details see this article. From this, you use the provider GUID to submit the credential, like in the below example.
```
credential = {
  "correlationId": "CUST123",
  "interactive": True,
  "providerId": "yourproviderId",
  "username": "yourusername",
  "username2": "", 
  "username3": "",
  "username4": "",
  "password": "yourpassword",
  "password2": "",
  "password3": "",
  "password4": ""
}

newcredential = requests.post(
  baseurl+'utility/credentials',
  headers=headers,
  data=json.dumps(credential)
)
```
You will receive a webhook response with the status of your new
credential, for example:
```
{
  "credentialId":"https://api.urjanet.com/utility/credentials/{yourcredentialID}",
  "responseUri":"https://api.urjanet.com/utility/credentials//{yourcredentialID}/challengeResponse",
  "created":"2023-0428T13:33:27.545+00:00",
  "correlationId":"{yourcorrelationID}",
  "eventType":"LOGIN_SUCCESS"
}
```
Upload utility statement files

a. UC allows you to manually submit utility invoices in cases where you don’t have,
or don’t wish to provide, utility web portal access credentials. In the Dashboard you can upload one or more pdf formatted statements at Files/UploadFiles.
b. Programmatically you can do this with POST /utility/files. For
example, in python:
```
uploadfile = {'upload_file': open(‘yourfilename.pdf', rb')}  
newfile = requests.post(baseurl+’/utility/files', headers =  
headers, files=uploadfile)
```
c. Alternatively, you can also perform this with Curl:
```
curl --location '<https://api.urjanet.com/utility/files'>  
	--header 'Content-Type: multipart/form-data'  
	--header 'Authorization: Bearer <token>  
	--form 'files=@"<file name>"'
```
Map meters to sites

a. UC will attempt to match the service address shown on the utility statement
for each meter with any of the site addresses you have previously created. This is performed on the first extraction of a statement when you link an account or upload a file. The matching is done across all the service address fields. If there is an exact matching site address for that meter, then the corresponding account, credential, and statement will be associated with that site for ongoing data collection.
b. If there is no matching site for the meter found, then UC can be configured to
automatically create a site for you. You can subsequently modify this site information in the Dashboard at Sites/{selected site}/Attributes
c. To move a meter from one site to another, for example to change it from
an UC auto-created site to one of your custom created sites, in the
Dashboard you make this change inMeters/Details/ReassignSite
d. Moving meters to another site can also be done via API with PATCH /utility/meters/{meterId}. You will need to identify
meterID for the item you wish to move and the siteID of the new site.
You can use RSQL to find the specific meter. For example, in Python this will find the sites with “Campus” in the location name, and all the meters with “Virginia” in the utility name. Note that other fields are searchable as well.
```
sitequery = 'siteName==Campus_'  
sitelist = requests.get(
  baseurl+'utility/sites?search='+sitequery,
  headers=headers
)

providerquery = 'providerName==Virginia_'  
meterlist = requests.get(
  baseurl+'utility/meters?search='+providerquery,
  headers=headers
)
```
After selecting the appropriate meterID to move to a new siteID found from the query above, you can execute this action like:
```
newsite = {"site": "yoursiteID"}
updatedsite = requests.patch(
  baseurl+’utility/meters/'+yourmneterID,
  headers=headers,
  data=json.dumps(newsite)
)
```
Test using the API to retrieve data

a. Verify webhooks: Investigate your webhook endpoint to confirm you are
receiving events from UC. You should see events for any new credentials that you
created in step 8. UC events will continually be sent for various status changes
and action required alerts. Information on webhook events is here.
b. Verify contents: Use the API to GET /meters, /accounts, ‘/statements, ‘/sites, ‘/credentials and other entities within
the system to learn about the available data fields and the structure of
responses. Additionally note that UC uses pagination. Additional details can be found here.

Main Concepts

Set-Up Steps

Log into your UC tenant for the first time

Test your API access

Configure your webhook endpoint

Add additional user accounts to your UC tenant

Create custom data fields

Create sites

Configure Connect

Link your accounts

Upload utility statement files

Map meters to sites

Test using the API to retrieve data