# 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](https://help.easy-pv.co.uk/link/64#bkmrk-post-%2Fprojects%2Fcreat-1) - [GET /forms/form](https://help.easy-pv.co.uk/link/64#bkmrk-get-%2Fforms%2Fform) - [GET /files/list](https://help.easy-pv.co.uk/link/64#bkmrk-get-%2Ffiles%2Flist) - [GET /files/file](https://help.easy-pv.co.uk/link/64#bkmrk-get-%2Ffiles%2Ffile) --- ### `GET` /forms/list Use this endpoint to get a list of completed forms for a project.
Authentication **Endpoint:** ```javascript 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: ```javascript 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 `forms` and `surveys` object, which contains the completed forms and surveys. ```json { "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:** ```javascript 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: ```javascript 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 `form` object, which contains the fields in the form. ```json { "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:** ```javascript 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: ```javascript 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 `fileRegistry` object. Files saved within the project will be contained in the `uploads` array of the response. ```json { "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:** ```javascript 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: ```javascript 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.