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

The platform is built around a set of core technology concepts that you will work with when integrating your solutions with the platform:

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

We support 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 the platform at no additional cost is our Connect component. 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 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 the platform.

1. Log into your account for the first time

Arcadia will create a tenant in our infrastructure and send an email to you to enable access to the platform.
The email will direct you to the Dashboard (https://dashboard.arcadia.com) where you will set your password. The email and updated password will be what you use to access the Dashboard as well as authenticate against the API.
You can update your admin password at any time in the Dashboard by clicking the Reset password link on https://dashboard.arcadia.com.

2. Test your API access

The platform uses bearer tokens to authenticate API requests. To obtain a token and verify you have API access, use: POST /auth/login with the username (or email) 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 }

3. Configure your webhook endpoint

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.
In the Dashboard, you input your webhook URL on the Webhook configuration page . Alternatively, you can perform this action via API by Patch Organization/{organizationId}.

4. Add additional user accounts to your organization

Open organization-wide configuration settings by clicking on the gear icon in the Dashboard top nav bar.
Create additional user accounts at on the Team members page. You will be prompted to provide their Name, their Email address, and Role. Their Role is one of: Admin, Standard or No Access. Admin allows for full system access including APIs and the ability to add and delete users. Standard User allows for view only access in the Dashboard.
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.
You can delete users or change their Role on the same Team members page.
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
)

5. Create sites

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.
You can create a new site in the Dashboard at on the Consumption tab.
Sites have a predefined set of commonly used custom data fields: siteCode, region, subregion, and facilityType. These fields are optional, the data for these site fields is provided by you and is used to organize and associate platform data with your own reference data.
Please note that creating your own sites is optional. You can also modify site information and reassign the associated meter data amongst sites as necessary. See section 9 below for additional steps.
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)
)

6. Configure Connect

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 the platform.
You access Connect settings in the Connect configuration section. This is where you can
access and copy the Connect URL. This URL cannot be changed, and it is specific to your organization.
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 link in Connect asking that users agree to these documents.
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 Connect configuration 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.
Note also that Connect supports the passing of URL parameters. For example, https://connect.urjanet.com/yourspecificURL?correlationId=CUST123. The above example will set the correlationID for this linked account to “CUST123”.

7. Connect your utility accounts

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.
You can manually create credentials in the Dashboard on the Credentials page 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.
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.
Once credentials are successfully created, 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) on that Credential's detail page on the Dashboard.
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.
You can programmatically 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 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"
}

8. Upload utility statement files

We 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 on the Bill Uploader page.
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)

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>"'

9. Map meters to sites

You can assign meters to sites on the Consumption tab. Once a site is created as described in step 5, you can assign meters by selecting them in the table on the Meters tab, and then clicking the button to assign to a site. You'll then need to search for the site name you'd like to use, select the site, and confirm your choice.
Moving meters to a 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)
)

10. Test using the API to retrieve data

Verify webhooks: Investigate your webhook endpoint to confirm you are receiving events from the platform. You should see events for any new credentials that you created in step 7. Events will continually be sent for various status changes and action required alerts. Information on webhook events is here.
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 the platform uses pagination. Additional details can be found here.