Skip to main content

Projects: Forms & 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 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 The projectId  as a number.

User email:  The 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 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 'X-API-KEY: ---KEY---'
Response

A successful call returns a JSON object containing a 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 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 The projectId as a number.

User email:  The 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 the form (from the response above).

Form Category: The 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 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 'X-API-KEY: ---KEY---'
Response

A successful call returns a JSON object containing a 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 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 The id of the project as a number.

User email:  The 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 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 'X-API-KEY: ---KEY---'
Response

A successful call returns a JSON object containing a 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 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 The id of the project as a number.

User email:  The 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 using curl that demonstrates how to create a project with the required fields:

curl -X GET 'https://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 'X-API-KEY: ---KEY---'
Response

If the request is successful you will receive a 200 success response and 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 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