Pylon API Reference

Introduction

The Pylon API is organized according to REST principles. We use resource-oriented URLs, content negotiation, hypermedia, and informative status codes and headers. Most endpoints accept and return JSON-encoded bodies, though other content types are sometimes available.

The API will evolve over time, but breaking changes will be kept to a minimum and made in consultation with our users.

Not a developer?

Send this page to your IT team or web development contractor. Or check out our Zapier integration (coming soon) to start integrating without needing to write code.

Authentication

To start making requests to the API, you'll need to first create an API token in your API settings area. You can create multiple tokens, and revoke them at any time. Tokens are associated with your team and the user who created them.

Pass your API token in the Authorization header as shown in the example, where $TOKEN should be replaced with your actual secret API token value. You should always use HTTPS when making requests containing sensitive information, and our API will return an error if you use a non-HTTPS URL.

API token security

Your API token is intended for server-side use, and should not be distributed to browsers (e.g. in page HTML or in a JavaScript bundle), nor committed to source control. If you suspect a token has been compromised, revoke it immediately from your API settings.

Do not distribute API tokens using emails, SMS messages, or group chat software. Doing this leaves your API token in history from where it could be leaked. If you need to transmit API tokens between team members or to third parties (e.g. your IT contractor), use a secure ephemeral service. This instance of SnapPass provides such a service.

Delete unused API keys, and keys created for development or testing purposes, to reduce the chance of a leak. Consider regenerating API keys periodically by creating a new key, switching your applications to it, then deleting the old key. Our API logging helps you ensure that you have switched completely before deleting the old key.

Permissions

When you create an API token to make requests with, you can assign it permissions. By creating multiple tokens with appropriate permissions, you can increase the security of your integration.

Permission	Description
`read`	This is implicitly allowed for all API tokens.
`write`	This is required in order to create or update any resources.
`payment`	This permission is required for any billable API calls, as well as API calls which may spend your Pylon Observer credit balance.
`admin`	Certain parts of the API contain more sensitive company information, and to read or write these resources, this additional permission is required.

curl https://api.getpylon.com/v1/users \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

REST Resources

Our API follows a subset of the JSON:API specification. As such, there are several predictable ways all endpoints will behave. Developers are encouraged to use JSON:API-compatible tools and libraries when working with our API.

Content types

When making requests to resource endpoints, your client should specify the Accept: application/vnd.api+json request header. In addition, requests with bodies (e.g. POST, PATCH) should include the header Content-Type: application/vnd.api+json.

All API endpoints which represent resources will respond with the header Content-Type: application/vnd.api+json.

The response content-type has one parameter, ext="https://api.getpylon.com/jsonapi" which describes our extensions to the spec (see below).

Single resources

A response body representing a single resource will contain a data property which is an object containing the resource. All resources contain type, id, attributes and relationships, and usually contain links.

Collection resources

A response body representing a collection of resources will contain a data property which is an array of resource objects. Each object in the array is identical to the individual resource object described above.

See the example belowto the right for an illustration of a typical response body.

Filtering response fields

If you want to reduce the size of response bodies from the API—for example, if you are only interested in one field, not the rest of the response—you may use JSON:API sparse fieldsets to filter response bodies. The general format is to provide a query parameter fields[type]=field1,field2 where the type is the type of an object included in the response body, and field1 and field1 are names of either attributes or relationships of the object.

For example, here is URL for a request to the users API which filters the response fields.

https://api.getpylon.com/v1/users?fields[users]=email

In the response to this request, all objects of the users type will only contain an email attribute, and no relationships:

Pagination

A response body representing a collection will have pagination links in a top-level links property. It will contain information about the entire collection (e.g. its total size) in a top-level meta property. You should not construct paginated URLs manually! Use the links!

{
  "data": [{
    "type": "users",
    "id": "MVGH032m",
    "attributes": {
      "email": "example@getpylon.com",
      "created_at": "2019-04-26T08:19:02+00:00",
    },
    "relationships": {
    },
    "links": {
      "self": "https://api.getpylon.com/v1/users/MVGH032m"
    }
  }],
  "links": {
    "first": "https://api.getpylon.com/v1/users?page[number]=1",
    "last": "https://api.getpylon.com/v1/users?page[number]=1",
    "prev": null,
    "next": null,
    "self": "https://api.getpylon.com/v1/users"
  },
  "meta": {
    "total": 1,
    "page": {
      "current": 1,
      "size": 15,
      "last": 1
    }
  }
}

Billing

Some methods in the API may incur billing charges when used. These methods are marked with a label under their title:

Billable

In order to make billable requests, your API token must be given the payment permission when it is created. This prevents you from accidentally causing billing with API tokens meant for administrative purposes.

Errors

Our API uses HTTP status codes and responses in the problem details format to indicate failures. See documentation for specific error types.

Common status codes

Our API makes use of HTTP response codes to indicate the success or failure of requests. Codes in the 200-299 range represent successes. Codes in the 400-599 range represent errors. Described below are the most common response codes you will encounter.

200: Success. Response body will contain a resource representation.
201: Success. A new resource was created and its representation is included in the response.
204: Success. Response body will be empty.
400: There was a problem with the syntax of your request (e.g., invalid JSON formatting).
401: You did not provide sufficient or correct authentication information.
402: When performing an operation that requires payment, this failure indicates your account has insufficient credit to complete it.
403: You are not permitted to perform the action. For example, maybe the API token being used has only the read permission and you attempted a write. Missing payments permissions will cause 403 errors, not 402 errors.
406: The request used content negotiation incorrectly. This is typically because the request did not specify the Accept: application/vnd.api+json header.
415: The request body content type was not accepted. This is typically because the request did not specify the Content-Type: application/vnd.api+json header.
422: Validation failure. Some properties of the request failed validation. More detail will be provided in the errors property, as in the example response belowto the right.

{
  "type": "https://observer.getpylon.com/docs/errors#validation_error",
  "code": "validation_error",
  "title": "Some parameters failed validation.",
  "status": 422,
  "errors": {
    "email": [
      "The email must be a valid email address."
    ],
    "first_name": [
      "The first name field is required."
    ]
  }
}

Users

Each of your employees should each have a unique account they can log in to Pylon with. Sharing accounts means you will have less accurate control over your employees' access to the software, and less accurate metrics on their usage. Each of these accounts is a User.

The user object

Attributes

full_name: string
email: string
gravatar_url: string; URL of the Gravatar associated with this user's email address.
photo_url: string; URL of the user's uploaded profile image.
created_at: string; Format: date-time
updated_at: string; Format: date-time

{
  "type": "users",
  "id": "PTxzssqg",
  "attributes": {
    "full_name": "Example User",
    "email": "solaruser@example.com",
    "gravatar_url": "https://www.gravatar.com/avatar/eab5a44fcb64a71900d00cd085b15b22?s=300&d=mm&r=PG",
    "photo_url": null,
    "created_at": "2020-01-14T19:00:01+00:00",
    "updated_at": "2020-04-22T01:15:18+00:00"
  },
  "relationships": {},
  "links": {
    "self": "https://api.getpylon.com/v1/users/PTxzssqg"
  },
  "meta": {}
}

Users › List users `read`

This resource lists all users in the team your API token belongs to. This is useful for combining with other resources in this API to get details about users which are referenced by their ID. You can then choose to display details such as their name, email, and profile picture.

Returns

A collection of user objects

curl https://api.getpylon.com/v1/users \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

Users › Show user `read`

Returns

An instance of the user object

curl https://api.getpylon.com/v1/users/$USER \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

{
  "data": {
    "type": "users",
    "id": "0ZH4VQfj",
    "attributes": {
      "full_name": "Example User",
      "email": "solaruser@example.com",
      "gravatar_url": "https://www.gravatar.com/avatar/eab5a44fcb64a71900d00cd085b15b22?s=300&d=mm&r=PG",
      "photo_url": null,
      "created_at": "2020-01-14T19:00:01+00:00",
      "updated_at": "2020-04-22T01:15:18+00:00"
    },
    "relationships": {},
    "links": {
      "self": "https://api.getpylon.com/v1/users/0ZH4VQfj"
    }
  }
}

User reporting Preview

This API is in preview and breaking changes may be made without warning.

This API allows you to get statistics about your users' activity in Pylon. Each call to the API can return information about multiple users. The response contains data that is formatted so it is easy to produce charts or tables from.

User reporting › View report `read`

Currently, in order to make a request to this API, the user_ids query parameter must be a non-empty list. You can find suitable user IDs by calling the list users endpoint.

Available metrics

solar_projects.created: The number of solar projects created.
solar_projects.sold: The number of solar projects marked as sold.
solar_projects.esignature_request_sent: The number of projects for which E-signature requests were sent to customers.
credit_spends.products: The different products that users spent credits on. This includes, e.g., creating projects, unlocking Pro, and sending esignature requests.

Query parameters

start_date: string; Format: date; Start of date range to query in the format YYYY-MM-DD.
end_date: string; Format: date; End of date range to query in the format YYYY-MM-DD.
timezone_name: string; The timezone the above dates are in. For example, Australia/Sydney.
metric_name: string; One of the metrics described above.
user_ids: string; List of user IDs to fetch metrics for separated by commas.

Returns

data: object
data.metric: string; The metric that is being queried
data.chart_data: object; This schema represents data that should be displayed as a chart. It's based on Chart.js's data format, with some changes to make it slightly more generic and. It doesn't pretend to specify an entire chart. For example, this schema doesn't specify whether to display the chart as bars, lines, etc. It needs to be combined with a little knowledge from the client in order to create the final presentation.
data.chart_data.domain_labels: optional array of strings; The domain is the "independent" axis of the chart, usually the X axis. If present, domain_labels must have the same length as all series values arrays.
data.chart_data.domain_labels[*]: string
data.chart_data.range_labels: optional array of strings; The range labels would typically go up the Y axis. This property is not always used, because some charts (e.g. pie charts) won't display an axis for the range.
data.chart_data.range_labels[*]: string
data.chart_data.series: array of objects; The series array contains all the actual data serieses.
data.chart_data.series[*].id: string; Identifier not intended for human consumption.
data.chart_data.series[*].label: optional string; Label of the series. Should be human-readable.
data.chart_data.series[*].values: array; Data values. The values of this array may have any type.

curl https://api.getpylon.com/v1/user_reporting \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/json"

Solar projects

Each solar project is located at one address and represents plans to install a single solar system. This might involve multiple solar arrays, but typically all behind the same meter.

The solar_projects resource represents the project itself, including location and customer details. Each project may have more than one design, as you go through the process of determining the best system to fit your customer's needs. For more details about the solar designs proposed for each project, see the solar designs resource.

The solar project object

Attributes

reference_number: string; This reference number can be used to identify the project in external systems
site_location: array of numbers; [Longutide, latitude] coordinates of this project.
site_location[*]: number
site_address: object; Street address of this project. Note that users can edit some of these properties to make cosmetic corrections.
customer_details: object; Information about the customer which will be displayed in web proposals for this project.
is_archived: boolean; Has this project been archived?
created_at: string; Format: date-time
updated_at: string; Format: date-time

Relationships

owner: A single user

designs: A collection of solar designs

{
  "type": "solar_projects",
  "id": "h9jWV9",
  "attributes": {
    "reference_number": "PYL-0003-7789",
    "site_location": [
      145.0709934,
      -37.8510383
    ],
    "site_address": {
      "line1": "19 Parmesan avenue",
      "line2": "",
      "city": "Glen Iris",
      "state": "Victoria",
      "zip": "3147",
      "country": "Australia"
    },
    "customer_details": {
      "name": "Jill Lepore",
      "phone": "0421 000 111",
      "email": "jill@example.com"
    },
    "is_archived": false,
    "created_at": "2019-11-04T08:56:04+00:00",
    "updated_at": "2020-02-18T13:14:00+00:00"
  },
  "relationships": {
    "owner": {
      "data": {
        "type": "users",
        "id": "SCFPFPuf"
      },
      "links": {
        "related": "https://api.getpylon.com/v1/users/SCFPFPuf"
      }
    },
    "designs": {
      "data": [],
      "links": {
        "related": "https://api.getpylon.com/v1/solar_designs?filter%5Bproject%5D=h9jWV9&fields%5Bsolar_designs%5D=created_at"
      }
    }
  },
  "links": {
    "self": "https://api.getpylon.com/v1/solar_projects/h9jWV9"
  },
  "meta": {}
}

Solar projects › List solar projects `read`

Projects are returned in the order they were created, least recent first. Results include archived projects.

Query parameters

filter: optional object
filter[is_archived]: optional string; Whether to list projects that have been archived. Defaults to false.; Allowed values: "true" "false" "any"
filter[reference_number]: optional string; Return only the project with this reference number, if any.
filter[created_at.gte]: optional string; Format: date-time; List projects created on or after the given timestamp.
filter[created_at.lt]: optional string; Format: date-time; List projects created before the given timestamp.
filter[owner]: optional string; Only projects owned by the user with this id. May be a comma-separated list to include multiple owners.
fields: optional object
fields[solar_projects]: optional string; Limit the fields returned for these projects.
fields[solar_designs]: optional string; These fields will be applied to links to solar design resources from this result.

Returns

A collection of solar project objects

curl https://api.getpylon.com/v1/solar_projects \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

Solar projects › Show solar project `read`

Query parameters

fields: optional object
fields[solar_projects]: optional string; Limit the fields returned for these projects.
fields[solar_designs]: optional string; These fields will be applied to links to solar design resources from this result.

Returns

An instance of the solar project object

curl https://api.getpylon.com/v1/solar_projects/$SOLAR_PROJECT \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

{
  "data": {
    "type": "solar_projects",
    "id": "FEX91hbK",
    "attributes": {
      "reference_number": "PYL-0003-7789",
      "site_location": [
        145.0709934,
        -37.8510383
      ],
      "site_address": {
        "line1": "19 Parmesan avenue",
        "line2": "",
        "city": "Glen Iris",
        "state": "Victoria",
        "zip": "3147",
        "country": "Australia"
      },
      "customer_details": {
        "name": "Jill Lepore",
        "phone": "0421 000 111",
        "email": "jill@example.com"
      },
      "is_archived": false,
      "created_at": "2019-11-04T08:56:04+00:00",
      "updated_at": "2020-02-18T13:14:00+00:00"
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "users",
          "id": "VMbUXZSD"
        },
        "links": {
          "related": "https://api.getpylon.com/v1/users/VMbUXZSD"
        }
      },
      "designs": {
        "data": [],
        "links": {
          "related": "https://api.getpylon.com/v1/solar_designs?filter%5Bproject%5D=FEX91hbK&fields%5Bsolar_designs%5D=created_at"
        }
      }
    },
    "links": {
      "self": "https://api.getpylon.com/v1/solar_projects/FEX91hbK"
    }
  }
}

Solar designs Preview

This API is in preview and breaking changes may be made without warning.

While this API is still in preview, you may wish to use the legacy solar projects API. That API will continue working for the forseeable future.

Each solar design contains a wealth of information about the layout, connection, configuration and pricing of a solar system. We are planning to expose much of this information via the API, but until we decide on the best way to do this, only basic information is available.

The solar design object

Attributes

summary: object; The summary contains high-level information about this design.
summary.dc_output_kw: number; Rated DC output size of the system in kilowatts.
summary.storage_kwh: number; Total storage capacity included in this design, in kilowatt-hours.
summary.web_proposal_url: string; URL of the web proposal associated with this design. This page is accessible without authentication and contains the customer's sensitive information like name and address, so share this URL with care.
summary.latest_snapshot_url: string; URL of the image showing the latest panel snapshot of this design.
pricing: object; Contains data about the pricing inputs for this design.
pricing.total: number; The total cash price (in cents) charged for this design.
pricing.total_includes_tax: boolean; Does the total include any taxes?
pricing.currency: string; The currency all amounts for this design are expressed in. Amounts are expressed in whole numbers of cents, so an amount of 10000 would, in dollars, equate to $100.00.
proposal_quote: object; Contains formatted values displayed to the customer on their proposal.
proposal_quote.currency: string; The currency all amounts on the proposal are expressed in.
proposal_quote.total_tax_formatted: string; The total amount of sales tax included in the price.
proposal_quote.total_price_formatted: string; The total cash price charged for this solar design.
proposal_quote.deposit_amount_formatted: string; The total cash amount required as a deposit.
proposal_quote.financed_amount_formatted: string; The amount that will be financed, and is therefore not payable up-front.
proposal_quote.amount_payable_formatted: string; The total cash price, less the deposit and any financing.
proposal_quote.locale_au: optional object; Quote data specific to Australia.
proposal_quote.locale_au.eligible_for_stcs: boolean; Can this design receive STC incentives?
proposal_quote.locale_au.stc_quantity: optional number; The number of STCs that this design is eligible for.
proposal_quote.locale_au.stc_value_formatted: optional string; The cash value of the STCs this design will generate, given the per-STC price set in the design configuration.
proposal_quote.locale_au.eligible_for_lgcs: boolean; Can this design receive LGC incentives?
proposal_quote.locale_au.lgc_quantity: optional number; The number of LGCs that this design is eligible for.
proposal_quote.locale_au.lgc_value_formatted: optional string; The cash value of the LGCs this design will generate, given the per-LGC price set in the design configuration.
module_types: array of objects; The different kinds of solar module used in this design. Usually there will only be one type.
module_types[*].sku: string; A unique identifier of this hardware. See solar modules for more info.
module_types[*].description: string; A human-readable label for this type of panel. Do not attempt to parse meaningful information from this string; if you need more detail, look up the datasheet using the sku.
module_types[*].quantity: integer; The number of this type of module used in the design
module_types[*].type_url: string; A permalink to this module type's definition
inverter_types: array of objects; The different kinds of inverter used in this design. Usually there will only be one type.

Relationships

project: A single solar project

{
  "type": "solar_designs",
  "id": "eIZC9Bxo",
  "attributes": {
    "summary": {
      "dc_output_kw": 6.49,
      "storage_kwh": 0,
      "web_proposal_url": "https://observer.getpylon.com/proposals/qmw7F396nB",
      "latest_snapshot_url": "https://static.getpylon.com/images/designs/1599550073.jpeg"
    },
    "locale": {
      "au": {
        "stc_quantity": 103,
        "stc_value": 360500
      }
    },
    "module_types": [
      {
        "sku": "779db75d-436a-5631-ba68-5eea5e3d25e2",
        "description": "REC Solar TwinPeak 2 Series",
        "quantity": 22,
        "type_url": "https://api.getpylon.com/v1/solar_modules/779db75d-436a-5631-ba68-5eea5e3d25e2"
      }
    ],
    "inverter_types": [
      {
        "sku": "cb532cd0-a5d4-5b77-a0e3-9a8dd27690f7",
        "description": "Sungrow Power Sun Access SH5K",
        "quantity": 1,
        "type_url": "https://api.getpylon.com/v1/solar_inverters/cb532cd0-a5d4-5b77-a0e3-9a8dd27690f7"
      }
    ],
    "storage_types": [
      {
        "sku": "56f5e7f0-4fb3-5ceb-8e8e-2f1be9dcdb0e",
        "description": "Sonnen Eco 8.10",
        "quantity": 1,
        "type_url": "https://api.getpylon.com/v1/solar_batteries/56f5e7f0-4fb3-5ceb-8e8e-2f1be9dcdb0e"
      }
    ],
    "pricing": {
      "total": 760000,
      "total_includes_tax": true,
      "currency": "aud"
    },
    "proposal_quote": {
      "currency": "aud",
      "total_tax_formatted": "$1,018.64",
      "total_price_formatted": "$7,600.00",
      "deposit_amount_formatted": "$760.00",
      "financed_amount_formatted": "$5,000.00",
      "amount_payable_formatted": "$1,840.00",
      "estimated_total_repayments_formatted": "$5,801.04",
      "locale_au": {
        "eligible_for_stcs": true,
        "stc_quantity": 103,
        "stc_value_formatted": "$3,605.00",
        "eligible_for_lgcs": false
      }
    },
    "created_at": "2020-02-18T13:14:00+00:00",
    "updated_at": "2020-02-18T16:09:40+00:00"
  },
  "relationships": {
    "project": {
      "data": {
        "type": "solar_projects",
        "id": "nqX0FBUa"
      },
      "links": {
        "related": "https://api.getpylon.com/v1/solar_projects/nqX0FBUa"
      }
    }
  },
  "links": {
    "self": "https://api.getpylon.com/v1/solar_designs/eIZC9Bxo?fields%5Bsolar_designs%5D=created_at"
  },
  "meta": {}
}

Solar designs › List solar designs `read`

Note that the filter query parameter fields[solar_designs] is mandatory when making requests to this resource. This is a slight divergence from the JSON:API spec and from other resources in our API. Read more about fields

Here's an example of a request URL that filters the response body to only include the summary and created_at fields:

https://api.getpylon.com/v1/solar_designs?fields[solar_designs]=summary,created_at

The fields you are allowed to include are the attributes and relationships of the solar design object. We require this in order to better track usage of different design properties without having to split the design into sub-resources.

Query parameters

filter: optional object
filter[project]: optional string; List designs belonging to the project with the given id
filter[created_at.gte]: optional string; Format: date-time; List designs created on or after the given timestamp.
filter[created_at.lt]: optional string; Format: date-time; List designs created before the given timestamp.
filter[updated_at.gte]: optional string; Format: date-time; List designs modified on or after the given timestamp.
filter[dc_output_kw.gte]: optional number; List designs with a size at least this value.
filter[dc_output_kw.lt]: optional number; List designs with size less than this value.
fields: object
fields[solar_designs]: string; Comma-separated list of fields to include. E.g. created_at,summary

Returns

A collection of solar design objects

curl https://api.getpylon.com/v1/solar_designs \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

Solar designs › Show solar design `read`

Here's an example of a request URL that filters the response body to only include the summary and created_at fields:

https://api.getpylon.com/v1/solar_designs?fields[solar_designs]=summary,created_at

Query parameters

fields: object
fields[solar_designs]: string; Comma-separated list of fields to include. E.g. created_at,summary

Returns

An instance of the solar design object

curl https://api.getpylon.com/v1/solar_designs/$SOLAR_DESIGN \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

{
  "data": {
    "type": "solar_designs",
    "id": "pURCkfp1",
    "attributes": {
      "summary": {
        "dc_output_kw": 6.49,
        "storage_kwh": 0,
        "web_proposal_url": "https://observer.getpylon.com/proposals/sxCJEXEx8T",
        "latest_snapshot_url": "https://static.getpylon.com/images/designs/1599550073.jpeg"
      },
      "locale": {
        "au": {
          "stc_quantity": 103,
          "stc_value": 360500
        }
      },
      "module_types": [
        {
          "sku": "779db75d-436a-5631-ba68-5eea5e3d25e2",
          "description": "REC Solar TwinPeak 2 Series",
          "quantity": 22,
          "type_url": "https://api.getpylon.com/v1/solar_modules/779db75d-436a-5631-ba68-5eea5e3d25e2"
        }
      ],
      "inverter_types": [
        {
          "sku": "cb532cd0-a5d4-5b77-a0e3-9a8dd27690f7",
          "description": "Sungrow Power Sun Access SH5K",
          "quantity": 1,
          "type_url": "https://api.getpylon.com/v1/solar_inverters/cb532cd0-a5d4-5b77-a0e3-9a8dd27690f7"
        }
      ],
      "storage_types": [
        {
          "sku": "56f5e7f0-4fb3-5ceb-8e8e-2f1be9dcdb0e",
          "description": "Sonnen Eco 8.10",
          "quantity": 1,
          "type_url": "https://api.getpylon.com/v1/solar_batteries/56f5e7f0-4fb3-5ceb-8e8e-2f1be9dcdb0e"
        }
      ],
      "pricing": {
        "total": 760000,
        "total_includes_tax": true,
        "currency": "aud"
      },
      "proposal_quote": {
        "currency": "aud",
        "total_tax_formatted": "$1,018.64",
        "total_price_formatted": "$7,600.00",
        "deposit_amount_formatted": "$760.00",
        "financed_amount_formatted": "$5,000.00",
        "amount_payable_formatted": "$1,840.00",
        "estimated_total_repayments_formatted": "$5,801.04",
        "locale_au": {
          "eligible_for_stcs": true,
          "stc_quantity": 103,
          "stc_value_formatted": "$3,605.00",
          "eligible_for_lgcs": false
        }
      },
      "created_at": "2020-02-18T13:14:00+00:00",
      "updated_at": "2020-02-18T16:09:40+00:00"
    },
    "relationships": {
      "project": {
        "data": {
          "type": "solar_projects",
          "id": "r56UD8Y"
        },
        "links": {
          "related": "https://api.getpylon.com/v1/solar_projects/r56UD8Y"
        }
      }
    },
    "links": {
      "self": "https://api.getpylon.com/v1/solar_designs/pURCkfp1?fields%5Bsolar_designs%5D=created_at"
    }
  }
}

Solar modules

This collection contains information about every solar module available in Observer. This data is sourced from the manufacuturer datasheets themselves, which we link to as part of the API response.

When building with Observer, feel free to use these datasheets to enhance your integration. We will expose more information as part of each datasheet in the future; subscribe to our developers mailing list to be kept up-to-date.

The solar module object

The id of a solar module datasheet is refered to as its SKU (stock keeping unit). These SKUs have been generated using a UUID v5 computed from the module's identity properties. You are encouraged to use these SKUs to uniquely identify solar modules in your own systems if you like.

Attributes

name: string
identity: object
identity.brand: string; Company/brand that produces this module.
identity.series: string; The line of module.
identity.model_number: string; The most specific product code this product has been assigned.
identity.sku_identifier: string; This helps create a unique SKU in cases where other properties are not unique enough.
files: object
files.datasheet_url: string; The URL of the manufacturer's datasheet for this component.

{
  "type": "solar_modules",
  "id": "c59f1f6f-67cb-5c39-ba91-ec66a9f3451e",
  "attributes": {
    "name": "Tindo Solar Karra 72 Cell Series 380W",
    "identity": {
      "brand": "Tindo Solar",
      "series": "Karra 72 Cell Series",
      "model_number": "Karra-380",
      "sku_identifier": ""
    },
    "files": {
      "datasheet_url": "https://static.getpylon.com/datasheets/panels/TindoSolar_Karra-Datasheets.pdf"
    }
  },
  "relationships": {},
  "links": {
    "self": "https://api.getpylon.com/v1/solar_modules/c59f1f6f-67cb-5c39-ba91-ec66a9f3451e"
  },
  "meta": {}
}

Solar modules › Show solar module `read`

Returns

An instance of the solar module object

curl https://api.getpylon.com/v1/solar_modules/$SOLAR_MODULE \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

{
  "data": {
    "type": "solar_modules",
    "id": "c59f1f6f-67cb-5c39-ba91-ec66a9f3451e",
    "attributes": {
      "name": "Tindo Solar Karra 72 Cell Series 380W",
      "identity": {
        "brand": "Tindo Solar",
        "series": "Karra 72 Cell Series",
        "model_number": "Karra-380",
        "sku_identifier": ""
      },
      "files": {
        "datasheet_url": "https://static.getpylon.com/datasheets/panels/TindoSolar_Karra-Datasheets.pdf"
      }
    },
    "relationships": {},
    "links": {
      "self": "https://api.getpylon.com/v1/solar_modules/c59f1f6f-67cb-5c39-ba91-ec66a9f3451e"
    }
  }
}

Solar inverters

This collection contains information about every solar inverter available in Observer. This data is sourced from the manufacuturer datasheets themselves, which we link to as part of the API response.

The solar inverter object

The id of a solar module datasheet is refered to as its SKU (stock keeping unit). These SKUs have been generated using a UUID v5 computed from the module's brand, series, and model_number. You are encouraged to use these SKUs to uniquely identify inverters in your own systems if you like.

Attributes

name: string
identity: object
identity.brand: string; Company/brand that produces this module.
identity.series: string; The line of inverter.
identity.model_number: string; The most specific product code this product has been assigned.
identity.sku_identifier: string; This helps create a unique SKU in cases where other properties are not unique enough.
files: object
files.datasheet_url: string; The URL of the manufacturer's datasheet for this component.

{
  "type": "solar_inverters",
  "id": "cb532cd0-a5d4-5b77-a0e3-9a8dd27690f7",
  "attributes": {
    "name": "Sungrow Power SH5K 4990W",
    "identity": {
      "brand": "Sungrow Power",
      "series": "Sun Access",
      "model_number": "SH5K",
      "sku_identifier": null
    },
    "files": {
      "datasheet_url": "https://static.getpylon.com/datasheets/inverters/SungrowPower_SH5K.pdf"
    }
  },
  "relationships": {},
  "links": {
    "self": "https://api.getpylon.com/v1/solar_inverters/cb532cd0-a5d4-5b77-a0e3-9a8dd27690f7"
  },
  "meta": {}
}

Solar inverters › Show solar inverter `read`

Returns

An instance of the solar inverter object

curl https://api.getpylon.com/v1/solar_inverters/$SOLAR_INVERTER \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

{
  "data": {
    "type": "solar_inverters",
    "id": "cb532cd0-a5d4-5b77-a0e3-9a8dd27690f7",
    "attributes": {
      "name": "Sungrow Power SH5K 4990W",
      "identity": {
        "brand": "Sungrow Power",
        "series": "Sun Access",
        "model_number": "SH5K",
        "sku_identifier": null
      },
      "files": {
        "datasheet_url": "https://static.getpylon.com/datasheets/inverters/SungrowPower_SH5K.pdf"
      }
    },
    "relationships": {},
    "links": {
      "self": "https://api.getpylon.com/v1/solar_inverters/cb532cd0-a5d4-5b77-a0e3-9a8dd27690f7"
    }
  }
}

Solar batteries

This collection contains information about every solar battery available in Observer. This data is sourced from the manufacuturer datasheets themselves, which we link to as part of the API response.

The solar battery object

The id of a solar battery is refered to as its SKU (stock keeping unit). These SKUs have been generated using a UUID v5 computed from the module's brand, manufacturer, and model_number. You are encouraged to use these SKUs to uniquely identify inverters in your own systems if you like.

{
  "type": "solar_batteries",
  "id": "56f5e7f0-4fb3-5ceb-8e8e-2f1be9dcdb0e",
  "attributes": {
    "name": "Sonnen Eco 8.10",
    "identity": {
      "brand": "Sonnen",
      "manufacturer": "Sonnen",
      "model_number": "Eco 8.10",
      "sku_identifier": ""
    }
  },
  "relationships": {},
  "links": {
    "self": "https://api.getpylon.com/v1/solar_batteries/56f5e7f0-4fb3-5ceb-8e8e-2f1be9dcdb0e"
  },
  "meta": {}
}

Solar batteries › Show solar battery `read`

Returns

An instance of the solar battery object

curl https://api.getpylon.com/v1/solar_batteries/$SOLAR_BATTERY \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

{
  "data": {
    "type": "solar_batteries",
    "id": "56f5e7f0-4fb3-5ceb-8e8e-2f1be9dcdb0e",
    "attributes": {
      "name": "Sonnen Eco 8.10",
      "identity": {
        "brand": "Sonnen",
        "manufacturer": "Sonnen",
        "model_number": "Eco 8.10",
        "sku_identifier": ""
      }
    },
    "relationships": {},
    "links": {
      "self": "https://api.getpylon.com/v1/solar_batteries/56f5e7f0-4fb3-5ceb-8e8e-2f1be9dcdb0e"
    }
  }
}

Files

This is an object describing a file hosted on Pylon's servers. This API allows you to upload files to Pylon for the purpose of using them with other APIs.

The file object

Attributes

name: string; The original filename of this file as provided by the uploader.
purpose: string; The purpose this file was uploaded for (may be left blank).
created_at: string; Format: date-time; When this file was uploaded (not when the original file itself was created).
expires_at: string; Format: date-time; When the file will expire, if not used by linking it to another entity.

{
  "type": "files",
  "id": "MZt5zlnt",
  "attributes": {
    "name": "load-data-2021-q1.csv",
    "purpose": "interval_analysis",
    "created_at": "2021-05-01T02:49:28+00:00",
    "expires_at": "2021-05-08T02:49:28+00:00"
  },
  "relationships": {},
  "links": {
    "self": "https://api.getpylon.com/v1/files/MZt5zlnt"
  },
  "meta": {}
}

Files › List files `read`

Returns

A collection of file objects

curl https://api.getpylon.com/v1/files \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

Files › Create file `read` `write`

Upload a new file to be used by another API operation. Note that you may also provide a purpose form parameter, which is omitted from the example to the right.

File creation is done using form-data to submit file content, instead of a JSON-API request body. However, as the server will return a JSON-API object representing the file, you must use the corresponding Accept header.

Returns

An instance of the file object

curl https://api.getpylon.com/v1/files \
  --request POST \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json" \
  --header "Content-Type: multipart/form-data" \
  --form "file=@/path/to/file"

{
  "data": {
    "type": "files",
    "id": "DhDfbFxF",
    "attributes": {
      "name": "load-data-2021-q1.csv",
      "purpose": "interval_analysis",
      "created_at": "2021-05-01T02:49:28+00:00",
      "expires_at": "2021-05-08T02:49:28+00:00"
    },
    "relationships": {},
    "links": {
      "self": "https://api.getpylon.com/v1/files/DhDfbFxF"
    }
  }
}

Files › Show file `read`

Returns

An instance of the file object

curl https://api.getpylon.com/v1/files/$FILE \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

{
  "data": {
    "type": "files",
    "id": "j1iuTp1M",
    "attributes": {
      "name": "load-data-2021-q1.csv",
      "purpose": "interval_analysis",
      "created_at": "2021-05-01T02:49:28+00:00",
      "expires_at": "2021-05-08T02:49:28+00:00"
    },
    "relationships": {},
    "links": {
      "self": "https://api.getpylon.com/v1/files/j1iuTp1M"
    }
  }
}

Australian STCs

The Clean Energy Regulator website contains more information about STCs. This API allows you to calculate the amount of STCs that a given solar system will generate.

Australian STCs › Calculate STC quantity `read`

Query parameters

sgu_kind: string; Allowed values: "solar_deemed"
output_kw: number; The rated DC output of the installed system, in kW.
site_postcode: string
installation_year: integer
deeming_period: optional integer; Defaults to the number of years remaining in the STC scheme.

Returns

data: object
data.stcs: integer; The number of STCs this system will create.
data.zone: integer; The rating zone the given postcode is associated with.
data.zone_rating: integer; The rating value for the given zone.
data.deeming_period: integer; The actual number of years used for deeming calculations.

curl https://api.getpylon.com/v1/localities/au/stc_amount \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/json"

{
  "data": {
    "stcs": 77,
    "zone": 3,
    "zone_rating": 1.382,
    "deeming_period": 10
  }
}

API Tokens

The Pylon API may be used to manage your API tokens. We recommend that only sophisticated clients make use of this feature, as a misbehaving script could cause unintended consequences for access to your account.

The API token object

Relationships

creator: A single user

{
  "type": "api_tokens",
  "id": "vywGP7BR",
  "attributes": {
    "name": "CRM integration token",
    "permissions": [
      "read",
      "write",
      "admin"
    ],
    "created_at": "2019-08-12T15:13:09+00:00",
    "last_used_at": null
  },
  "relationships": {
    "creator": {
      "data": null
    }
  },
  "links": {
    "self": "https://api.getpylon.com/v1/api_tokens/vywGP7BR",
    "pylon:api_tokens.key": "https://api.getpylon.com/v1/api_tokens/vywGP7BR/secret"
  },
  "meta": {}
}

API Tokens › List API tokens `read` `admin`

This shows all currently-usable API tokens associated with your current team.

Returns

A collection of API token objects

curl https://api.getpylon.com/v1/api_tokens \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

API Tokens › Show API token `read` `admin`

Returns

An instance of the API token object

curl https://api.getpylon.com/v1/api_tokens/$API_TOKEN \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"

{
  "data": {
    "type": "api_tokens",
    "id": "YGfSVba",
    "attributes": {
      "name": "CRM integration token",
      "permissions": [
        "read",
        "write",
        "admin"
      ],
      "created_at": "2019-08-12T15:13:09+00:00",
      "last_used_at": null
    },
    "relationships": {
      "creator": {
        "data": null
      }
    },
    "links": {
      "self": "https://api.getpylon.com/v1/api_tokens/YGfSVba",
      "pylon:api_tokens.key": "https://api.getpylon.com/v1/api_tokens/YGfSVba/secret"
    }
  }
}

API Tokens › Revoke API token `read` `write` `admin`

Destroying an API token in this way will render it unable to make any further requests to the API. An API token may not destroy itself; attempting to do so will result in an error.

Returns

No content returned

curl https://api.getpylon.com/v1/api_tokens/$API_TOKEN \
  --request DELETE \
  --header "Authorization: Bearer $TOKEN" \
  --header "Accept: application/vnd.api+json"