NAV Navbar
cURL
  • Introduction
  • Authentication
  • Identity
  • Projects
  • Users
  • 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.