API Connect Flow

Written by Brad Pirtle
Updated 2 weeks ago

Overview

This documentation explains how to use the SolarFax API to connect an account to a provider (utility or solar) to get actual usage data.  This allows you to initiate a connection from an external website or web product, uses browser redirects to manage the user through the flow (including entering credentials on a provider website), and ends back at the external website or web product.

For the basics on using the SolarFax API, refer to this article: API Documentation.

In SolarFax, we have users that identify a person (email address, etc) and accounts that identify the site (address).  A user can have multiple accounts, and an account can have multiple users, but the basic setup is one user with one account.  Data connections are specifically for an account.  In these instructions, we will refer to this user/account combination as the account.

Step 1: Create a User in SolarFax

You can either create a user/account in SolarFax using the /users endpoint (docs), or lookup an existing account with the /accounts endpoint (docs).  What you need is an account_id.

Step 2: Select a Provider (Utility or Solar) to Connect

You can get a list of providers that are available for an account (based on address) using the /providers endpoint (docs).  This endpoint can be passed an account_id instead of a profile_id when using the connect flow, and the type ("utility" or "solar").  Each provider has a can_connect field which tells you if you can use the Connect Flow to connect and get data.  Not all providers can be connected, but we are constantly adding more.  The connect_method field tells you the method used, which is either "oauth" (the flow will redirect to the provider website for authorization) or "fields" (you must provide the needed field values).

Step 3: Initialize the Connection

To initialize the connection, you need to provide a redirect_url, the URL that we will redirect to at the end of the connection flow.  This URL will be passed back the connect parameters, and if the connection succeeded.

POST connect - initialize a connection

Parameters: 

account_id ID of the account
user_id (Optional) ID of the user
provider_id ID of the provider to connect
redirect_url URL to redirect to once connected
xid (Optional) ID from your system
connect_fields ("fields" connection method only) field values - see "Connect Method: Fields" below
demo (Optional) connect demo data for the provider immediately

Example request:

curl -H 'Content-Type: application/json' -H 'Api-Key: KEY' -H 'Access-Token: TOKEN' -X POST -d '{"account_id": 0, "provider_id": 0, "redirect_url": "https://mysite.com/solarfax-redirect"}' https://api.solardatapros.com/api/v1/connect

Example response:

{
  "success": true, 
  "message": "", 
  "connect_method": "oauth", 
  "redirect_url": "https://api.solardatapros.com/api/v1/connect_flow?token=TOKEN", 
  "provider_id": 0, 
  "third_party_id": 0, 
}

Step 4: Redirect the User

Send the user's browser to the redirect_url returned in Step 3 (for example with a link, a browser redirect, or a popup window).

  • oauth: The URL is /api/v1/connect_flow?token=TOKEN. SolarFax checks the token and redirects the user to the provider website, where they sign in and authorize access to their data. The provider then returns the user to SolarFax, which forwards them to your redirect_url.
  • fields: If you don't collect and supply the fields, the URL is /api/v1/connect_landing?token=TOKEN. This is a SolarFax hosted page (with your company name and logo) where the user enters the needed fields. Once submitted and connected, the user is returned to your redirect_url. The page also has a cancel option that returns to your redirect_url.

The token is valid for 1 hour. After that, the URL returns "Connect token has expired", and you need to call POST connect again to get a new URL.

Step 5: Handle the Return to Your redirect_url

At the end of the flow, the user is redirected to your redirect_url with these query parameters added:

success "1" if connected, "0" if not
message A message describing the result (for example the error, or "PG&E connected successfully")
account_id ID of the account
user_id ID of the user
provider_id ID of the provider
redirect_url URL to redirect to once connected
xid ID from your system, if you passed one in Step 3

Success example:

https://mysite.com/solarfax-redirect?success=1&user_id=0&account_id=0&provider_id=0&message=PG%26E+connected+successfully

Cancel example:

https://mysite.com/solarfax-redirect?success=0&user_id=0&account_id=0&provider_id=0&message=Connection+cancelled

Connect Method: Fields

Some providers (for example Smart Meter Texas, Qcells, and some utilities connected by username and password) do not use OAuth, and instead need field values. For these providers, connect_method is "fields", and the connect_fields list (returned by /providers and by POST connect) describes each field.  Example:

"connect_fields": [
  {"name": "email", "label": "Email", "type": "email", "required": true, "help": "Email used for Smart Meter Texas agreement notifications."},
  {"name": "esiid", "label": "ESIID", "type": "text", "required": true},
  {"name": "meter", "label": "Meter Number", "type": "text", "required": true}
]

You have two options:

Option 1: Let the user enter the fields on the SolarFax page. Call POST connect without connect_fields and redirect the user to the returned redirect_url, as in Steps 4 and 5.

Option 2: Provide the fields yourself. Collect the values in your own product and pass them in connect_fields (using the field name values). The connection happens immediately, with no browser redirects:

curl -H 'Content-Type: application/json' -H 'Api-Key: KEY' -H 'Access-Token: TOKEN' -X POST -d '{"account_id": 0, "provider_id": 0, "redirect_url": "https://mysite.com/solarfax-redirect", "connect_fields": {"email": "user@example.com", "esiid": "ESIID", "meter": "METER"}}' https://api.solardatapros.com/api/v1/connect

Example response:

{
  "success": true,
  "message": "SMT connected successfully",
  "connected": true,
  "connect_method": "fields",
  "user_id": 0,
  "account_id": 0,
  "provider_id": 0,
  "third_party_id": 0,
  "redirect_url": "https://mysite.com/solarfax-redirect?success=1&user_id=0&account_id=0&provider_id=0&message=SMT+connected+successfully"
}

In this case, the returned redirect_url is just your redirect_url with the result parameters added, for your convenience. SolarFax does not redirect the user. If required fields are missing, the response has success: false, a missing list of field names, and the connect_fields list.

Step 6: Get the Data

Once connected, SolarFax starts pulling historical data from the provider in the background. 

  • When the data has arrived, you will be notified via webhook (docs)
  • You can use the /intervals endpoint (docs) with the account_id and type ("utility" or "solar") to get the data
Did this answer your question?