Skip to main content

Interacting with forms and files

Within Easy PV and Heatpunk, 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 the /api/v1/projects/forms/list endpoint. Provide projectId and userEmail as GET parameters. userEmail is necessary as the API key is shared amongst all members of your team, but projects aren't necessarily shared with all members of the team. When we receive the request we will check if the given email has the right to access the project.

curl -X 'GET' \
      'https://sandbox.heatpunk.co.uk/api/v1/projects/forms/list?projectId=872034&userEmail=sales%40midsummerenergy.co.uk' \
      -H 'accept: application/json' \ 
      -H 'X-API-KEY: ---KEY---'

This should return an object with completed forms and surveys.

{
    "forms": [
        {
            "id": "enaConnect"
        },
        {
            "id": "proposal"
        },
        {
            "id": "hpCommissioning"
        },
        {
            "id": "dno"
        }
    ],
    "surveys": [
        {
            "id": "survey"
        }
    ]
}

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 userEmail. Here's an example:

curl -X 'GET' \
    'https://sandbox.heatpunk.co.uk/api/v1/projects/forms/form?projectId=872034&form=letterOfConsent&userEmail=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, and provide the ID of the project and the userEmail as before. Files saved within Easy-PV are listed within the fileRegistry.uploads array of the response.

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

This will return a list of files associated with the project:

{
    "fileRegistry": {
        "uploads": {
            "dno": [
                {
                    "name": "Clone of Tue Jul 30 2024 DNO commissioning form~DNO.pdf",
                    "size": 66967,
                    "created": "2024-11-06T09:08:52.258Z",
                    "modified": "2024-11-06T09:08:52.258Z",
                    "format": ".pdf"
                }
            ],
            "mcsComplianceCertificate": [
                {
                    "name": "Clone of Tue Jul 30 2024 MCS Compliance Certificate~MCS Compliance Certificate.pdf",
                    "size": 14452,
                    "created": "2024-11-06T09:08:48.566Z",
                    "modified": "2024-11-06T09:08:48.566Z",
                    "format": ".pdf"
                }
            ],
            "heatPumpProjectDesign": [
                {
                    "name": "Heat pump - design report - Clone of Tue Jul 30 2024~Heat Pump Project Design.pdf",
                    "size": 104281,
                    "created": "2024-11-06T09:08:56.370Z",
                    "modified": "2024-11-06T09:08:56.370Z",
                    "format": ".pdf"
                }
            ]
        }
    }
}

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.heatpunk.co.uk/api/v1/files/file?type=projects&id=872034&userEmail=andy%40midsummerenergy.co.uk&fileCategory=uploads&file=Heat%20pump%20-%20design%20report%20-%20Clone%20of%20Tue%20Jul%2030%202024~Heat%20Pump%20Project%20Design.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.

We have updated the attribute used by the API when specifying the email address of the user that owns the record so it is consistent across all our endpoints. We now always refer to this attribute as userEmail. If you previously used ownerEmail this will still work as it has been set up as an alias of userEmail.

Back to top