Projects: Forms & files Within 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 GET /forms/form GET /files/list GET /files/file 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 a Heatpunk 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://heatpunk.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  forms and surveys object, which contains the completed forms and surveys. { "forms": [ { "id": "proposal" }, { "id": "enaConnect" } ], "surveys": [] } 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 a Heatpunk 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://heatpunk.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  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. 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 a Heatpunk 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://heatpunk.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  fileRegistry object. Files saved within the project will be contained in the uploads array of the response. { "fileRegistry": { "uploads": { "heatPumpCommissioningChecklist": [ { "name": "Fri Dec 27 2024 -hp-commissioning~Heat Pump Commissioning Checklist.pdf", "size": 83175, "created": "1970-01-01T00:00:00.000Z", "modified": "2026-01-13T17:01:29.107Z", "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 a Heatpunk 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)  R esponse 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://heatpunk.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.