Introduction

Version

The API is currently at version 1.0.0

URL

All API endpoints begin with the following:

https://observer.getpylon.com/api/v1/

Contacts

For technical support or issues with the API, please contact daniel@getpylon.com.

For billing or business issues with the API, please contact nelson@getpylon.com.

Conventions

REST-ish

Authentication

Pass your token in the Authorization header:

curl "https://observer.getpylon.com/api/v1/identity" \
  --header "Authorization: Bearer <token>"

Make sure to replace <token> with your API token.

The Observer API is secured using tokens. Every request to the API must include this token in the Authorization header as shown to the right.

You can create API tokens in the Observer webapp on the API settings page. You can create multiple tokens, and revoke them at any time. Tokens are associated with your team and the user who created them.

Identity

Get information about the token currently being used:

curl "https://observer.getpylon.com/api/v1/identity" \
  -H "Authorization: Bearer <token>"

The above command returns JSON similar to this:

{
  "token": {
    "uid": "oWHIv40R",
    "permissions": ["projects:read"],
    "name": "Example Application",
    "created_at": "2018-05-15 05:50:10"
  },
  "team": {
    "uid": "b3GefjyU",
    "name": "Example Solar"
  },
  "user": {
    "uid": "51TJ90ei",
    "full_name": "Joe Blake",
    "email": "joeblake@example.com"
  },
}

You can use this endpoint to determine which token is being used to access the API, and find information about the team and user it is associated with.

HTTP request

GET http://observer.getpylon.com/api/v1/identity

Response parameters

Parameter	Type	Description
token	object	The token which is being used to access the API.
token.permissions	array of strings	Permissions the token was granted.
token.name	string	The name the token was given on creation.
team	object	The team associated with the current token.
user	object	The user who created the token.

Projects

Permissions

All Projects endpoints require your token to have the projects:read permission.

List projects

Get the first page of projects for the team:

curl "https://observer.getpylon.com/api/v1/projects" \
  -H "Authorization: Bearer <token>"

The above command returns JSON similar to this:

{
  "current_page": 1,
  "per_page": 20,
  "last_page": 7,
  "total": 123,
  "data": [
    {
      "uid": "ndd1MMGi",
      "site_address": "19 Goodwin St",
      "site_address_line_2": "",
      "site_city": "Glen Iris",
      "site_state": "Victoria",
      "site_zip": "3147",
      "site_country": "Australia",
      "site_latitude": -37.85127,
      "site_longitude": 145.074846,
      "customer_name": "Calamity Jane",
      "customer_phone": "0421114219",
      "customer_email": "jane@example.com",
      "reference_number": null,
      "creator_uid": "4cnNOft8",
      "created_at": "2017-12-07 00:42:44"
    },
    ...
  ]
}

Get the second page of projects for the team:

curl "https://observer.getpylon.com/api/v1/projects?page=2" \
  -H "Authorization: Bearer <token>"

The above command returns JSON similar to this:

{
  "current_page": 2,
  "per_page": 20,
  "last_page": 7,
  "total": 123,
  "data": [
    ...
  ]
}

Get archived projects with a large page size:

curl "https://observer.getpylon.com/api/v1/projects?archived=true&per_page=200" \
  -H "Authorization: Bearer <token>"

The above command returns JSON similar to this:

{
  "current_page": 1,
  "per_page": 200,
  "last_page": 1,
  "total": 18,
  "data": [
    ...
  ]
}

Get projects with designs attached:

curl "https://observer.getpylon.com/api/v1/projects?include=designs" \
  -H "Authorization: Bearer <token>"

The designs relationship will be included in each project result:

{
  ...
  "data": [
    {
      "uid": "ndd1MMGi",
      "site_address": "19 Goodwin St",
      ...
      "designs": [
        {
          "uid": "TQ3YtwhB",
          "settings": {
            ...
          },
          "summary": {
            ...
          },
          "image": "https://static.getpylon.com/images/designs/ph7xzt7/ndd1MMGi/TQ3YtwhB/1516686385.png"
        },
        ...
      ]
    },
    ...
  ]
}

The projects endpoint lists all projects in the team's account. It is paginated for performance reasons and to align with usage in an external frontend. Once you have selected a project, you can access its details by using its UID with the single project endpoint.

HTTP request

GET http://observer.getpylon.com/api/v1/projects

Request parameters

You can control the pagination and projects to be displayed using the following parameters. These parameters should be passed as query strings, as shown in the examples to the right. All parameters are optional.

Parameter	Type	Description
page	int	Which page to fetch, beginning at 1. Defaults to 1.
per_page	int	How many results per page. Defaults to 20.
archived	boolean	If omitted, all projects are shown. If `true`, only archived projects will be returned. If `false`, archived projects are not returned.
reference_number	string	If provided, results are limited to only those with the given `reference_number`.
include	string	Related resources to include. See Relationships below.

Response parameters

Parameter	Type	Description
current_page	int	Page requested through `page` request parameter.
per_page	int	How many results per page. Same as the `per_page` request parameter.
last_page	int	The maximum page number.
total	int	How many total results match the request in all pages.
data	array of objects	The projects in the current page. See single project for a description of project properties.

Relationships

You can add a request parameter to include additional related resources in each project response. The include parameter should be a comma-separated list of relationship types chosen from the options below.

Relationship	Description
designs	Each design represents a different solar system that may be sold for this project. The fields included are a subset of those included in the `designs` parameter of the single project endpoint response.
e_signature_requests	Each item is a request for the customer to sign a proposal using Pylon e-signatures.

Show single project

Get the details of a single project:

curl "https://observer.getpylon.com/api/v1/projects/ndd1MMGi" \
  -H "Authorization: Bearer <token>"

The above command returns JSON similar to this:

{
  "uid": "ndd1MMGi",
  "site_address": "19 Goodwin St",
  "site_address_line_2": "",
  "site_city": "Glen Iris",
  "site_state": "Victoria",
  "site_zip": "3147",
  "site_country": "Australia",
  "site_latitude": -37.85127,
  "site_longitude": 145.074846,
  "customer_name": "Calamity Jane",
  "customer_phone": "0421114219",
  "customer_email": "jane@example.com",
  "reference_number": null,
  "creator_uid": "4cnNOft8",
  "created_at": "2017-12-07 00:42:44",
  "updated_at": "2017-18-07 09:11:03",
  "designs": [
    {
      "uid": "TQ3YtwhB",
      "settings": {
        ...
      },
      "summary": {
        ...
      },
      "image": "https://static.getpylon.com/images/designs/ph7xzt7/ndd1MMGi/TQ3YtwhB/1516686385.png"
    },
    {
      "uid": "94z3Nl6g",
      "settings": {
        ...
      },
      "summary": {
        ...
      },
      "image": "https://static.getpylon.com/images/designs/ph7xzt7/ndd1MMGi/94z3Nl6g/1512706211.png"
    }
  ],
  "e_signature_requests": [
    {
      "uid": "fyNQBiye",
      "design_uid": "TQ3YtwhB",
      "complete": true,
      "invalid": false,
      "signed_name": "Daniel Buckmaster",
      "email_status": "opened",
      "email_recipient": "daniel@getpylon.com",
      "created_at": "2017-18-07 11:12:16",
      "completed_at": "2017-18-07 12:01:01"
    }
  ]
}

The single project endpoint allows you to get detailed information about a project and its designs.

HTTP request

GET http://observer.getpylon.com/api/v1/projects/<uid>

Request parameters

Parameter	Type	Description
uid	string	The unique ID of the project.

Response parameters

Parameter	Type	Description
uid	string	The unique ID of the project.
site_address	string	The project's street address.
site_address_line_2	string	Optional unit number, subdivision, etc.
site_city	string	City or locality the project is in.
site_state	string	State the project is in.
site_zip	string	Postcode the project is in.
site_country	string	Country the project is in.
site_latitude	decimal	Latitude of the project's location.
site_longitude	decimal	Longitude of the project's location.
customer_name	string	The name of the customer as entered in the project settings.
customer_phone	string	Phone number of the customer.
customer_email	string	Email address of the customer.
reference_number	string	The project's reference number as entered in the project settings.
creator_uid	string	The unique ID of the user who created the project.
created_at	string	The timestamp when the project was created (in UTC).
updated_at	string	The timestamp when the project or one of its designs was last modified (in UTC).
—
designs	array of objects	Designs associated with the project.
designs.uid	string	Unique ID of this design.
designs.image	string	The URL of the design's latest snapshot image.
designs.settings	object	See below for a detailed description of design settings.
designs.summary	object	See below for a detailed description of design summary.
—
e_signature_requests	array of objects	Sent e-signature requests associated with the project.
e_signature_requests.uid	string	Unique ID of this e signature request.
e_signature_requests.created_at	string	When this request was created/sent.
e_signature_requests.completed_at	string or null	When the customer signed the document.
e_signature_requests.complete	boolean	Has the document been signed?
e_signature_requests.invalid	boolean	Has this document been invalidated by a document sent later?
e_signature_requests.signed_name	string	Name the customer entered when they signed.
e_signature_requests.email_status	string	Status of the last email that was sent to this customer.
e_signature_requests.email_recipient	string	Email address the request was sent to.
e_signature_requests.design_uid	string	The UID of the design this request was sent for.

Design settings

An example design settings object:

{
  "locale": {
    "au": {
      "stc_price": 3200,
      "customer_registered_for_gst": false
    }
  },
  "feed_in_tariff": 6,
  "installation_year": 2017,
  "bos_efficiency": 0.87,
  "quarterly_bill": 35000,
  "financial_term": 20,
  "effective_interest_rate": 0.0329,
  "electricity_price": 25,
  "electricity_price_inflation_rate": 0.03763,
  "line_items": [
    {
      "description": "Solar Analytics monitoring device",
      "price": null,
      "quantity": 1
    }
  ]
}

The settings object contains the values that can be edited by the user when creating a solar design. This does not include layout information (i.e. locations of panels). This information can be used when presenting assumptions or detailed information about the design.

Parameter	Type	Description
installation_year	int	Year the system will be installed (for incentive purposes).
bos_efficiency	number	Overall efficiency of the balance-of-system (excluding factors relating to climate or orientation).
quarterly_bill	int	Quarterly bill amount in AU cents.
financial_term	int	Expected lifetime of the system in years.
effective_interest_rate	number	Effective rate of interest for financial return comparisons.
electricity_price	number	Electricity price per kWh in AU cents.
feed_in_tariff	number	Feed in tariff per kWh in AU cents.
electricity_price_inflation_rate	number	Expected annual inflation rate of electricity prices.
line_items	array of objects	Extra items added to the quote page of the proposal.
line_items.description	string	What is the item?
line_items.price	int	Price of this item in AU cents. If `null`, it should be displayed as 'included' in the subtotal.
line_items.quantity	int	How many items are purchased.

Design summary

An example design summary object:

{
  "dpp": 7.185780655317949,
  "irr": 0.15941406250000004,
  "npv": 13513.17420633492,
  "roi": 1.675533069601354,
  "size": 5.6,
  "panel_groups": [
    {
      "azimuth": 7,
      "tilt": 20,
      "sku": "f802b942-a004-5251-af15-2730727c70bb",
      "power": 5.6,
      "count": 20,
      "name": "Jinko Solar Eagle Dual"
    }
  ],
  "price_total": 806500,
  "price_subtotal": 1027582,
  "financing_enabled": false,
  "annual_bill": 145008,
  "self_consumption": 0.5692769336021386,
  "annual_production": 6866.260119043123,
  "monthly_production": [
    955.7473456615731, 724.0024183953874, 627.1433392402473, 432.61484154982566, 290.81087030423276, 238.26680986216957, 266.37089753096683, 364.0714046080199, 504.8327077815876, 709.1287902705216, 814.4382175470489, 938.8324762915428
  ],
  "charts": {
    "yearly_expenses": {
      "with_solar": [
        267, 292.28, 318.73, 346.41, 375.37, 405.67, 437.39, 470.58, 505.31, 541.66, 579.7, 619.5, 661.15, 704.72, 750.32, 798.04, 847.97, 900.21, 954.85, 1012.04
      ],
      "without_solar": [
        1450.08, 1504.65, 1561.27, 1620.02, 1680.98, 1744.23, 1809.87, 1877.97, 1948.64, 2021.97, 2098.06, 2177.01, 2258.93, 2343.93, 2432.13, 2523.65, 2618.62, 2717.16, 2819.4, 2925.5
      ]
    },
    "monthly_expenses": {
      "with_solar": [
        0, 0, 11.96, 45.05, 74.38, 88.68, 89.44, 66.49, 36.3, 0, 0, 0
      ],
      "without_solar": [
        116.67, 117.04, 117.42, 117.8, 123.28, 128.75, 134.23, 127.71, 121.19, 114.66, 115.33, 116
      ]
    }
  },
  "locale": {
    "au": {
      "stc_amount": 92,
      "stc_value": 294400
    }
  }
}

This object contains all the calculated outputs from Observer's solar engine, as well as summarised details of the design layout itself.

Parameter	Type	Description
dpp, npv, irr, roi	number	See financial calculations help article. Note that NPV is expressed in dollars, when most other currency values are in cents.
size	number	The total size of the system in kW.
panel_groups	array of objects	Information about each type of panels used in the design. They are grouped by orientation and SKU.
panel_groups.tilt	number	Tilt angle of the panels from horizontal. A positive tilt means a panel with 0 azimuth will face North.
panel_groups.azimuth	number	Rotation of the panels around the vertical axis, clockwise from North.
panel_groups.sku	string	"Stock keeping unit" code of the panel model.
panel_groups.name	string	Friendly name of the panel model.
panel_groups.count	int	Number of panels in this array group.
panel_groups.power	number	Total power of this group of panels in kW.
self_consumption	number	The proportion of solar production that is self-consumed.
annual_bill	int	Total annual electricity bill estimated from quarterly bill in AU cents at time of project creation.
annual_production	number	Total energy production of the design over a year, in kWh.
monthly_production	array of numbers	Total production through each month of the year, in kWh.
charts.yearly_expenses	object	Yearly expenses chart data, showing forecasted electricity bills over the lifetime of the system.
charts.monthly_expenses	object	Yearly expenses chart data, showing forecasted electricity bills over the first year of the system's life.
locale.au.stc_amount	int	The number of STCs generated by the project.
locale.au.stc_value	int	Total value of all STCs generated by the project, in AU cents at the time of project creation.
price_total	int	Final price the customer pays for the system in AU cents at time of project creation.
price_subtotal	int	Price of system before tax and STC benefits in AU cents at time of project creation.
financing_enabled	boolean	True when the project has financing enabled.

Users

Permissions

All Users endpoints require your token to have the users:read permission.

List users

List all users on the token's current team:

curl "https://observer.getpylon.com/api/v1/users" \
  -H "Authorization: Bearer <token>"

Response for the above request:

{
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 2,
  "data": [
    {
      "uid": "4cnNOft8",
      "full_name": "Daniel Buckmaster",
      "email": "daniel@getpylon.com",
      "role": "admin"
    },
    {
      "uid": "8lhVzLJi",
      "full_name": "Peter Parker",
      "email": "peter@getpylon.com",
      "role": "user"
    }
  ]
}

HTTP request

GET http://observer.getpylon.com/api/v1/users

Request parameters

You can control the pagination of users to be returned using the following parameters. These parameters should be passed as query strings. All parameters are optional.

Parameter	Type	Description
page	int	Which page to fetch, beginning at 1. Defaults to 1.
per_page	int	How many results per page. Defaults to 20.

Response parameters

Parameter	Type	Description
current_page	int	Page requested through `page` request parameter.
per_page	int	How many results per page. Same as the `per_page` request parameter.
last_page	int	The maximum page number.
total	int	How many total results match the request in all pages.
—
data	array of objects	The users returned.
data.uid	string	Unique identifier for this user.
data.full_name	string	The name the user entered when they signed up.
data.email	string	The user's email address.
data.role	string	The user's role on this team. One of `admin`, `super-user` or `user`.