Skip to main content

Your first call - create a project

/projects/create

A common requirement is to create a new Easy PV project from meta data that you already hold, such as a customer name, address and postcode.

You can create projects using the https://easy-pv.co.uk/api/v1/projects/create endpoint.

Projects must have an "owner", which must be specified in the request POST. The owner email must be a member of the pro team that owns the API key. The owner can then subsequently share the project with other members of the team if they wish.

Fields you can pass across in the 'meta' object are: projectName customerName customerEmail customerPhone address postcode crmReference

crmReference can be used for your internal reference - it's likely that you will have a unique database ID that you want to be associated with the project. All fields are optional.

You can run this from the command line to try it out. Change the owner email to a member of the Easy PV team (probably your own if you want to be able to check it has been successful), and put your key in the X-API-KEY header.

curl -X 'POST'   'https://sandbox.easy-pv.co.uk/api/v1/projects/create'  -H 'accept: application/json' -H 'X-API-KEY: **********KEY***********' -H 'Content-Type: application/json' -d '{
  "owner": "sales@midsummerenergy.co.uk",  
  "meta": {
      "customerName": "Joe Bloggs"
  }
}'

The endpoint will return a JSON object with a projectId property. You will almost certainly want to save this projectId within your own database.

https://easy-pv.co.uk/?project=872019

Congratulations! You've used our API to create a project within Easy PV. Read on to see how you can retrieve files and form data from an Easy PV project.

FORMS AND FILES Within Easy PV and Heatpünk, users complete forms and generate PDF reports. In your application you may want to view the completed files and forms associated with a project, and fetch completed form data and PDF documents.

To list forms for a project:

To get a list completed forms for a project, use /api/v1/projects/forms/list. Provide the projectId and ownerEmail in the GET parameters.

curl -X 'GET'
'https://sandbox.easy-pv.co.uk/api/v1/projects/forms/list?projectId=872034&ownerEmail=andy%40midsummerenergy.co.uk'
-H 'accept: application/json'
-H 'X-API-KEY: ---KEY---'

This should return an object with completed forms and surveys.

To retrieve form fields:

Use /api/v1/projects/forms/form.

You will need to provide the ID of the project, ID of the form (from the response above), and the ownerEmail.

curl -X 'GET' \

'https://sandbox.easy-pv.co.uk/api/v1/projects/forms/form?projectId=872034&form=letterOfConsent&ownerEmail=andy%40midsummerenergy.co.uk&formCategory=forms'
-H 'accept: application/json'
-H 'X-API-KEY: ---KEY---'

To list files saved to a project: Use /api/v1/projects/files/list. Set the type property to projects Provide the ID of the project and the ownerEmail Files saved within Easy-PV are listed within the fileRegistry.uploads array of the response.

curl -X 'GET'
'https://sandbox.easy-pv.co.uk/api/v1/files/list?type=projects&id=872034&ownerEmail=andy%40midsummerenergy.co.uk'
-H 'accept: application/json'
-H 'X-API-KEY: ---KEY---'

To download a file:

use /api/v1/files/file.

Provide the same details as the previous request, plus the file category (uploads) and the file name.

curl -X 'GET'
'https://sandbox.easy-pv.co.uk/api/v1/files/file?type=projects&id=872034&ownerEmail=andy%2Bjumptech%40midsummerenergy.co.uk&fileCategory=uploads&file=test%20project%20%20letter%20of%20consent~Letter%20of%20Consent.pdf&responseFormat=b64'
-H 'accept: application/json'
-H 'X-API-KEY: ---KEY---'

Setting responseFormat to either b64 or meta will include a meta object in the response. This includes a datetime string for when the file was created and last updated. b64 will also return the document as a base64-encoded string in the response. raw will just return the file as stored.

PROJECT DATA, CART AND ORDER LINKS

Easy PV and Heatpünk generate a full bill of materials for a project, and for our UK and Ireland sites you can very quickly place an order for the components from Midsummer. You may like to import the shopping cart into your application and display an ordering link. Users love the ease of ordering all the kit for an installation.

Please note - the cart is refreshed every time you visit the overview page of a project.

To fetch project data, including the cart and order link, use the api/v1/projects/data endpoint. You need to pass in the project ID, and the user you are acting as. The user must have view rights to the project. You will get back an object which includes a 'cart' array and a 'midsummerOrderLink' string. Both should be self explanatory.

In its simplest form, an order can be just an object with an 'items' property. For each item, specify the property.

const order = { "items": { "2586": { "qty": 99 }, "4258": { "qty": 99 } } }

Here is a more complex order, with a shipping address, despatch date and reference:

const order = { "items": { "2586": { "qty": 99 } }, "deliveryOption": "standard", "shippingAddress": { "postcode": "CB24 6AZ", "add1": "Midsummer Energy", "add2": "Cambridge Road Industrial Estate", "add3": "Milton", "add4": "", "email": " andy@midsummerenergy.co.uk ", "phone": "01223 858414", "firstname": "Andy", "lastname": "Rankin" }, "despatchDate": "2023-02-08", "reference": "trial order" }

Once you have created your order, simply create an order string by stringifying the object then Base64 encoding the result then URL encoding the result Then goto https://midsummerwholesale.co.uk/upload?order=[string]

In javascript: function createOrderLink(order) { return "https://midsummerwholesale.co.uk/upload?order="+encodeURIComponent(btoa(JSON.stringify(order))) }

Back to top