Skip to main content

Projects: Create, list, update & delete

Updated (WIP):

This guide walks you through creating, updating and archiving projects using our Open API.

Jump to section:

  • POST /projects/create
  • POST/projects/list
  • PATCH / projects/update
  • DELETE /projects/softDelete
  • DELETE /projects/hardDelete

POST /projects/create

Use this endpoint to create new projects.

Authentication

Endpoint:  

POST https://[DOMAIN]/api/v1/projects/create

Headers:

  • accept: application/json
  • X-API-KEY: YOUR_API_KEY     (Replace YOUR_API_KEY with your actual API key.)
  • Content-Type: application/json
Request structure

Every request to create a new project must include a JSON object with the following:

Owner field: The owner should be a valid email address of an Easy PV Pro team member. This email will become the primary project owner.

Meta object: Use the meta object to pass in parameters for the project. All fields are optional.

  • buildDate Sets the design mode for the project. Allowed values: 
    • "pre2000"
    • "post2000"
    • "post2006"
  • projectName
  • customerName
  • customerEmail
  • customerPhone
  • address
  • postcode
  • lat and lng - provide the latitude and longitude in the decimal degrees format
  • status - set the status of the project. Allowed values:
    • "Lead"
    • "Quote"
    • "Sale"
    • "Install"
    • "Completed"
    • "Rejected"
  • crmReference - include an ID or reference to the customer record or project in your CRM
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 POST 'https://heatpunk.co.uk/api/v1/projects/create' \
     -H 'accept: application/json' \
     -H 'X-API-KEY: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
           "owner": "sales@example.com",
           "meta": {
               "customerName": "Joe Bloggs",
               "address": "123 Sample Street",
               "postcode": "AB12 3CD"
           }
         }'
Response

A successful call returns a JSON object containing a projectId which you should store in your own database for future reference.

You can use the ID to construct a link directly to the project using the following link structure:

https://heatpunk.co.uk/?project=[PROJECT ID]

POST /projects/list

Use this endpoint to get a list of projects.

Authentication

Endpoint:  

POST https://[DOMAIN]/api/v1/projects/list

Headers:

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

Every request to update a project must contain a JSON object with the following.

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

Start date: start should be in the format (YYYY-MM-DD)

End date: end should be in the format (YYYY-MM-DD)

Example API request and response
Example API Request

Below is an example using curl that demonstrates how to retrieve a list of projects:

curl -X POST 'https://heatpunk.co.uk/api/v1/projects/list' \
     -H 'X-API-KEY: YOUR_API_KEY' \
     -d '{
          "ownerEmail": "matt.agnes+proBasic@midsummerenergy.co.uk",
          "start": "2025-05-22",
          "end": "2025-11-22"
      }'
Response

A successful request returns a projects object containing a list of projects within the specified date range. For example:

{
    "status": "success",
    "projects": [
        {
            "ID": 1353680,
            "owner": 27091,
            "dateCreated": "2025-09-01T09:14:30.000Z",
            "dateModified": "2025-12-04T11:52:18.000Z",
            "projectName": "Mon Sep 01 2025",
            "customerName": "",
            "address": "105 Sample Road Cambridge Cambridgeshire",
            "postcode": "CB1 3QD",
            "lat": 52.193912506103516,
            "lng": 0.15014299750328064,
            "status": "Lead"
        },
    ...
    ],
    "ownerEmail": "matt.agnes+proBasic@midsummerenergy.co.uk",
    "ownerID": 00123
}

PATCH /projects/update

Use this endpoint to update core project data for an existing project.

Authentication

Endpoint:  

PATCH https://[DOMAIN]/api/v1/projects/update

Headers:

  • accept: application/json
  • X-API-KEY: [YOUR_API_KEY] (Replace [YOUR_API_KEY] with your actual API key.)
  • Content-Type: application/json
Request structure

Every request to update a project must contain the project id, user email, and new data to be updated. The data must be an object with keys for each field to be updated.

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.

Data object: Include a data object that will contain the information to be updated. We currently support a meta object with keys for each field to be updated. See the projects/create and projects/data endpoint documentation for the list of project meta fields that can be updated.

Example API request and response
Example API Request

Below is an example using curl that demonstrates how to update a project:

curl -X PATCH 'https://heatpunk.co.uk/api/v1/projects/update' \
     -H 'accept: application/json' \
     -H 'X-API-KEY: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
        "projectId": 986206,
        "userEmail": "matt.agnes+pro@midsummerenergy.co.uk",
        "data": {
            "meta": { "status": "Completed"}
                }
        }'
Response

If the request is successful you will receive a 204 success response. 

DELETE /projects/softDelete

Use this endpoint to reversibly soft-delete a project.

Authentication

Endpoint:  

DELETE https://[DOMAIN]/api/v1/projects/softDelete

Headers:

  • accept: application/json
  • X-API-KEY: [YOUR_API_KEY] (Replace [YOUR_API_KEY] with your actual API key.)
  • Content-Type: application/json
Request structure

Every request to archive a project must contain the project id and user email.

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.

Example API request and response
Example API Request

Below is an example using curl that demonstrates how to soft delete a project:

curl -X DELETE 'https://heatpunk.co.uk/api/v1/projects/softDelete' \
     -H 'accept: application/json' \
     -H 'X-API-KEY: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
        "projectId": 986206,
        "userEmail": "matt.agnes+pro@midsummerenergy.co.uk",
        }'
Response

If the request is successful you will receive a 204 success response. 

DELETE /projects/hardDelete

Use this endpoint to permanently delete a project, together with its associated data.

Authentication

Endpoint:  

DELETE https://[DOMAIN]/api/v1/projects/hardDelete

Headers:

  • accept: application/json
  • X-API-KEY: [YOUR_API_KEY] (Replace [YOUR_API_KEY] with your actual API key.)
  • Content-Type: application/json
Request structure

Every request to archive a project must contain the project id and user email.

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.

Example API request and response
Example API Request

Below is an example using curl that demonstrates how to hard delete a project:

curl -X DELETE 'https://heatpunk.co.uk/api/v1/projects/hardDelete' \
     -H 'accept: application/json' \
     -H 'X-API-KEY: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
        "projectId": 986206,
        "userEmail": "matt.agnes+pro@midsummerenergy.co.uk",
        }'
Response

If the request is successful you will receive a 204 success response. 

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