1. 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 Users.

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 Accountobject 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 Accounts.

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 Users, 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.

Screenshot

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.