Skip to main content

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

Jump to section:

GET /forms/list

Use this endpoint to get a list of completed forms for a project.

Authentication

Endpoint:  

GET https://[DOMAIN]/api/v1/projects/forms/list

Headers:

  • X-API-KEY: YOUR_API_KEY     (Replace YOUR_API_KEY with your actual API key.)

Request structure

Every request must contain the project ID and user email as GET parameters. 

Project ID: The projectId as a number.

User email: The userEmail should be a valid email address of an Easy PV Pro team member who has access to the project. 

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.

Example API request and response
Example API Request

Below is an example using curl that demonstrates how to create a project with the required fields:

curl  -X GET 'https://easy-pv.co.uk/api/v1/projects/forms/list?projectId=12345&userEmail=sales%2540midsummerenergy.co.uk' \
      -H 'accept: application/json' \ 
      -H 'X-API-KEY: ---KEY---'
Response

A successful call returns a JSON object containing a forms and surveys object, which contains the completed forms and surveys.

{
    "forms": [
        {
            "id": "customerProposal"
        },
        {
            "id": "enaConnect"
        },
        {
            "id": "f08_v2"
        },
        {
            "id": "g99_50kw"
        },
        {
            "id": "scaffoldingRequest"
        },
        {
            "id": "g98"
        },
        {
            "id": "g99_A1_1"
        },
        {
            "id": "g99_A1_2"
        },
        {
            "id": "letterOfConsent"
        },
        {
            "id": "install_record"
        },
        {
            "id": "g99_A3_1"
        },
        {
            "id": "g99_A3_2"
        }
    ],
    "surveys": [
        {
            "id": "survey"
        }
    ]
}

GET /forms/form

Use this endpoint to retrieve form fields.

Authentication

Endpoint:  

GET https://[DOMAIN]/api/v1/projects/forms/form

Headers:

  • X-API-KEY: YOUR_API_KEY     (Replace YOUR_API_KEY with your actual API key.)

Request structure

Request must contain the project ID and user email as GET parameters. You will also need to include the ID of the form.

Form category also must be set if you are requesting survey forms.

Project ID: The projectId as a number.

User email: The userEmail should be a valid email address of an Easy PV Pro team member who has access to the project. 

Form: The ID of the form (from the response above).

Form Category: The formCategory currently only needs to be set if requesting survey forms.

Allowed Values:

    • "forms"
    • "surveys"
Example API request and response
Example API Request

Below is an example using curl that demonstrates how to create a project with the required fields:

curl -X GET 'https://easy-pv.co.uk/api/v1/projects/forms/form?projectId=12345&userEmail=sales%2540midsummerenergy.co.uk&form=letterOfConsent' \
     -H 'accept: application/json' \
     -H 'X-API-KEY: ---KEY---'
Response

A successful call returns a JSON object containing a form object, which contains the fields in the form.

{
    "form": {
        "details": {
            "fullName": "Testing Testington",
            "address": "90 Example Rd\nCambridge \nUK\nCB4 2QD",
            "installCompany": "Midsummer Installations",
            "installType": "PV system with battery storage",
            "customerIsCompany": "as an individual"
        }
    }
}

GET /files/list

Use this endpoint to get a list of files saved to a project.

Authentication

Endpoint:  

GET https://[DOMAIN]/api/v1/files/list

Headers:

  • X-API-KEY: YOUR_API_KEY     (Replace YOUR_API_KEY with your actual API key.)

Request structure

Request must contain the project ID, and user email as GET parameters. You must also set the type of the return object.

ID: The id of the project as a number.

User email: The userEmail should be a valid email address of an Easy PV Pro team member who has access to the project. 

Type: Set the type property to "projects"

Example API request and response
Example API Request

Below is an example using curl that demonstrates how to create a project with the required fields:

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

A successful call returns a JSON object containing a fileRegistry object. Files saved within the project will be contained in the uploads array of the response.

{
    "fileRegistry": {
        "uploads": {
            "quotation": [
                {
                    "name": "Customer proposal~Quotation.pdf",
                    "size": 4114053,
                    "created": "1970-01-01T00:00:00.000Z",
                    "modified": "2024-10-15T12:41:35.000Z",
                    "format": ".pdf"
                }
            ],
            "installationRecord": [
                {
                    "name": "Installation record~Installation record.pdf",
                    "size": 59254,
                    "created": "1970-01-01T00:00:00.000Z",
                    "modified": "2024-10-15T12:58:29.000Z",
                    "format": ".pdf"
                }
            ],
            "letterOfConsent": [
                {
                    "name": "Multiple AC inverters  letter of consent~Letter of Consent.pdf",
                    "size": 2685,
                    "created": "1970-01-01T00:00:00.000Z",
                    "modified": "2024-10-15T12:58:00.000Z",
                    "format": ".pdf"
                }
            ],
        }
    }
}

GET /files/file

Use this endpoint to download a file.

Authentication

Endpoint:  

GET https://[DOMAIN]/api/v1/files/file

Headers:

  • X-API-KEY: YOUR_API_KEY     (Replace YOUR_API_KEY with your actual API key.)

Request structure

Request must contain the project ID, and user email as GET parameters. You must also set the type of the return object, file category and the name of the file.

ID: The id of the project as a number.

User email: The userEmail should be a valid email address of an Easy PV Pro team member who has access to the project. 

Type: Set the type property to "projects"

File category: Set fileCategory to "uploads"

File: The name of the file (from the response above).

(Optional) Response format: You can specify the responseFormat from the allowed values:

  • "raw" file as stored (Default).
  • "b64" JSON object with image in base64 format and metadata.
  • "meta" Just metadata.
Example API request and response
Example API Request

Below is an example using curl that demonstrates how to create a project with the required fields:

curl -X 'GET' \
    'https://sandbox.easy-pv.co.uk/api/v1/files/file?type=projects&id=872034&userEmail=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---'
Response

A successful call returns the specified file.

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