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