Core Concepts
Data Model
A few models you should know before getting started.
User
The User
model corresponds to a utility login. If your user has multiple utility logins, such as an SCE login and a SoCalGas login, they must go through the Connect flow multiple times. Each of these utility logins will be associated with a Pelm User
, i.e. your user might be associated with multiple different Pelm User
s.
Account
The Account
model corresponds to an account under a utility login. There is typically a one-to-one mapping of Account
to property. If a user has a residential home and a vacation home, these would correspond to two different Account
objects. An Account
object is always tied to a singular User
object.
Usage intervals and bills are queried per Account
.
Common scenarios
Bob owns three houses in the Bay Area. PG&E serves gas and electricity for each of his houses. Bob would need to go through the Connect flow once. Bob is associated with one User
that has three different Account
s.
Alice rents an apartment in Southern California. SCE provides her electricity and SoCalGas provides her gas. Alice would need to go through the Connect flow twice. Alice is associated with two User
s, each with one Account
.
Authorization
Securely access your users’ data.
Access Token
The access_token
grants you access to Alice’s (and only Alice’s) data. When making requests for Alice’s data, the access_token
must be passed in the Authorization
header as Bearer {{access_token}}
.
The access_token
will not expire. Make sure you securely store it in your database.
Connect
Connect is a UI component provded by Pelm that allows your users to seamlessly and securely connect their utility login.
Polling data
We require a few minutes to sync a User’s data after they go through Connect for the first time.
During that period, our endpoints may return the following 500
response:
{
"error_code": "data_unavailable",
"message": "We're currently loading data for this account, please try again in 5 minutes."
}
We recommend polling our endpoints to know when data becomes available.
Coming soon: webhooks.