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.

To

Jump to section:

  • GET /forms/list
    • forms
  • GET for/forms/form
    • a
  • GET project:
/files/list
  • GET /files/file

    • GET /forms/list

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

    use
    theAuthentication

    Endpoint:  

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

    Headers:

    Provide
    • X-API-KEY: YOUR_API_KEY     (Replace projectIdYOUR_API_KEY with your actual API key.)
    Request structure

    Every request must contain the project ID and userEmailuser 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' \GET 'https://sandbox.heatpunk.co.uk/api/v1/projects/forms/list?projectId=87203412345&userEmail=sales%40midsummerenergy.2540midsummerenergy.co.uk' \
      -H 'accept: application/json' \
      -H 'X-API-KEY: ---KEY---'
    Response

    ThisA shouldsuccessful returncall anreturns a JSON object withcontaining a forms and surveys object, which contains the completed forms and surveys.

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

    GET /forms/form

    Use
    Tothis endpoint to retrieve form fields:
    fields.

    Authentication

    UseEndpoint:  

    GET https://[DOMAIN]/api/v1/projects/forms/form.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 provideinclude the ID of the project,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 theresponse userEmail.
    Example Here'sAPI Request

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

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

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

    {
  "form": {
    "details": {
      "coverLetterHeading": "...",
      "coverLetter": "..."
    },
    "quote": {
      "quoteReference": "32836",
      "validFor": "30 days"
    },
    "scope": {
      "show": "No",
      "scopeOfWorks": ""
    },
    "terms": {
      "show": "No",
      "terms": ""
    }
  }
}

    GET /files/list

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

    Authentication

    UseEndpoint:  

    GET https://[DOMAIN]/api/v1/projects/files/list.
    Set

    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 property to projects, and provideof the IDreturn object.

    ID: The id of the project andas a number.

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

    before.

    Type: Files saved within Easy-PV are listed withinSet the fileRegistry.uploadstype arrayproperty ofto "projects"

    Example API request and response
    Example API Request

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

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

    ThisA successful call returns a JSON object containing a fileRegistry object. Files saved within the project will returnbe acontained listin the uploads array of files associated with the project:response.

    {
  "fileRegistry": {
    "uploads": {
      "dno"heatPumpCommissioningChecklist": [
        {
          "name": "CloneFri ofDec Tue Jul 3027 2024 DNO-hp-commissioning~Heat commissioningPump form~DNO.Commissioning Checklist.pdf",
          "size": 66967,83175,
          "created": "2024-11-06T09:08:52.258Z"1970-01-01T00:00:00.000Z",
          "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"2026-01-13T17:01:29.107Z",
          "format": ".pdf"
        }
      ]
    }
  }
}

    GET /files/file

    Use
    Tothis endpoint to download a file:
    file.

    Authentication

    UseEndpoint:  

    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

    ProvideRequest must contain the sameproject detailsID, and user email as GET parameters. You must also set the previoustype request, plusof the return object, file category (uploads) 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 name.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' \GET 'https://sandbox.heatpunk.co.uk/api/v1/files/file?type=projects&id=872034&userEmail=andy%2Bjumptech%40midsummerenergy.co.uk&fileCategory=uploads&file=Heat%20pump%20-%20design%20report%20-%20Clone%test%20project%20%20letter%20of%20Tue%20Jul%2030%202024~Heat%20Pump%20Project%20Design.20consent~Letter%20of%20Consent.pdf&responseFormat=b64' \
    -H 'accept: application/json' \
     -H 'X-API-KEY: ---KEY---'
    Response

    SettingIf responseFormatthe torequest eitheris b64successful or metayou will includereceive a meta200 objectsuccess inresponse and returns the response.specified 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.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