API Documentation

Overview

This documentation explains how to integrate with SolarFax using our API.

Technology

Our API is RESTful using JSON.  All endpoints have a base URL of:
https://api.solardatapros.com/api/v1/

Authentication

To use our API, you need to request an Api-Key and Access-Token pair from support.  These are sent with each API endpoint as headers.  If your keys are compromised, contact support for replacements.

Example usage:

curl -H 'Api-Key: KEY' -H 'Access-Token: TOKEN' 'https://api.solardatapros.com/api/v1/accounts

Formats

Responses

All responses return success which is true or false.  Additional information will be returned as message.  Example:

{"success":false,"message":"invalid api_key: KEY"}

Timestamps

All date and datetime fields will be in ISO 8601 format.  Example:
2011-11-04
2011-11-04T00:05:23

---

API Endpoints

There are four ways to search accounts:

1. Text based search.  The fields that are searched are: user.full_name and address.address_one.
   Example request:
   

   accounts?search_term=123+East+St

   Example response:
   

   {
     "success": true,
     "message": "", 
     "company": "Company Name", 
     "count": 1, 
     "accounts": [
       {
         "id": 0, 
         "inverter": "SolarEdge", 
         "utility": "PG&E"
         "address": {
           "address_one": "123 Easy St", 
           "address_two": "", 
           "city": "Mountain View", 
           "state": "CA", 
           "zip_code": "94043",
           "latitude": 37.3927515, 
           "longitude": -122.0682099, 
         }, 
         "user": {
           "id": 4, 
           "first_name": "Adam", 
           "last_name": "Ant", 
           "email": "easy@email.com", 
           "phone": "408-555-5555"
         }, 
       }, 
     ], 
   }

2. Geolocation based search via latitude/longitude.  Provide a latitude/longitude pair and a distance (in miles) and we return accounts within that parameter.
   Added response include distance and geocode.
   Example request:
   

   accounts?geocode=37.3927515,-122.0682099&distance=2

3. Geolocation based search via address.  Provide address (like google map search) and a distance (in miles) and we return accounts within that parameter.
   Added response include distance and geocode.
   Example request:
   

   accounts?address=123+Easy+St,+Mountain+View,+CA+94043&distance=2

4. ID lookup.  This lets you get a specific account.
   Example request:
   

   accounts?id=0

Parameters: 

Restrictions: supports up to 12 months per call

Example request:

intervals?account_id=0&date_start=5/1/2023&date_end=5/1/2023

Example response:

{
  "success": true, 
  "message": "", 
  "company": "Company Name", 
  "account": {
    "date_data_first": "2015-05-05T00:00:00", 
    "date_data_last": "2023-05-31T23:45:00", 
    "id": 0
  }, 
  "user": {
    "first_name": First", 
    "last_name": "Last", 
    "id": 0
  }, 
  "date_end": "2023-05-01", 
  "date_start": "2023-05-01", 
  "type": "Electricity", 
  "units": "uWh"
  "count": 24, 
  "intervals": [
    {
      "date": "2023-05-01", 
      "time_end": "01:00", 
      "time_start": "00:00", 
      "usage_in": 421200, 
      "usage_out": 0,
      "usage_net": 421200, 
    }, 
    {
      "date": "2023-05-01", 
      "time_end": "02:00", 
      "time_start": "01:00", 
      "usage_in": 402400, 
      "usage_out": 0,
      "usage_net": 402400, 
    }, 
...
    {
      "date": "2023-05-01", 
      "time_end": "00:00", 
      "time_start": "23:00", 
      "usage_in": 681300, 
      "usage_out": 0,
      "usage_net": 681300, 
    }
  ], 
}

Example "max interval" request:

intervals?account_id=0&date_start=5/1/2023&date_end=5/1/2023&max=1

Example "max interval" response:

{
  "success": true, 
  "message": "", 
  "company": "Company Name", 
  "account": {
    "utility_data_date_first": "2025-01-01T00:00:00", 
    "utility_data_date_last": "2026-01-31T23:45:00", 
    "id": 0
  }, 
  "user": {
    "first_name": First", 
    "last_name": "Last", 
    "id": 0
  }, 
  "date_end": "2023-05-01", 
  "date_start": "2023-05-01", 
  "type": "Electricity", 
  "units": "uWh"
  "max": {
    "value": 1940000, 
    "date": "2023-05-31T07:00:00", 
    "duration": 15
  }, 
}

Note that the max interval (minutes) is returned with whatever duration the interval data is, which is typically 15 minutes 1 hour.  To convert to "max hour":

value = (value / duration) * 60

Parameters: JSON object data

Fields:

Example request:

curl -H 'Content-Type: application/json' -H 'Api-Key: KEY' -H 'Access-Token: TOKEN' -X POST -d '{"user": {"firstName": "fname", "lastName": "lname", "email": "x@t.com", "enableAccess": "0", "enableEmails": "0"}, "account": {"phone": "PHONE", "addressOne": "STREET", "city": "CITY", "state": "STATE", "zip": "ZIP", "isLead": "0"}, "test": "1"}' https://api.solardatapros.com/api/v1/users

Example response:

{
  "success": true, 
  "message": "User 'User Name' created", 
  "action": "created", 
  "account_id": ID, 
  "user_id": ID, 
  "company": "Company Name", 
}

The SolarFax system can notify your server when key events happen.  To start receiving webhook notifications, send your receiver_url to support to get setup. 

Example receiver_url:
https://api.company.com/webhook
An HTTP POST request will be sent with a JSON payload in the request body to the receiver_url.
This endpoint should return an HTTP status code of 200.

Supported Events:

Example webhook payload:

{
  "event": "intervals_added",
  "created_on": "2026-02-14T12:34:56",
  "data": {
     "intervals": {
       "type": "utility",
       "provider": "PG&E",
       "date_first": "2025-01-01T00:00:00",
       "date_last": "2026-01-31T23:45:00",
     },
     "account": {
       "id": 0,
     },
     "user": {
       "id": 0,
       "first_name": "First",
       "last_name": "Last",
     },
  },
}

Webhook signature validation

We include a signature (HMAC SHA-256) in the X-Webhook-Signature HTTP header for each webhook event.  This allows you to verify that the webhook was genuinely sent by SolarFax.  This is optional but recommended.

Example signature verification (Python):

import hmac
import hashlib
import json

def is_valid_signature(api_key, payload, header_signature):
    signature = hmac.new(
        api_key.encode('utf-8'),
        json.dumps(payload).encode('utf-8'),
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, header_signature)

def webhook():
    if request.method == 'POST':
        header_signature = request.headers.get('X-Webhook-Signature', None)
        payload = request.json
        api_key = 'API_KEY'
        valid = verify_json_signature(header_signature, api_key, payload)
        return f'Webhook signature was {'valid' if valid else 'invalid'}', 200

Webhook Test

You can send a webhook for a user using the /users API with "webhook_test": "1".  Example:

curl -H 'Content-Type: application/json' -H 'Api-Key: API_KEY' -H 'Access-Token: ACCESS_TOKEN' -X POST -d '{"user": {"firstName": "first", "lastName": "last", "email": "email@company.com"}, "webhook_test": "1"}' https://api.solardatapros.com/api/v1/users

This will trigger the webhook for the user with that email address.  The company webhook endpoint must be setup, and this user must be connected to a utility.