Skip to main content

Projects: Create, list, update, archive & delete

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

Jump to section:

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.

  • projectType Sets the design mode for the project. Allowed values: 
    • "three-d-model"
    • "quick-roof"
    • "roof-outline"
  • "magicMode" : true   Enable automatic roof scanning - only available for three-d-model projects
  • customerName
  • customerEmail
  • customerPhone
  • address
  • postcode
  • lat and lng - provide the latitude and longitude in the decimal degrees format
  • zoom - set the zoom level of the satellite map imagery
  • 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://easy-pv.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": {
               "projectType": "three-d-model",
               "magicMode": "true",
               "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://easy-pv.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://easy-pv.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-10-21T12:35:57.000Z",
            "dateModified": "2025-10-21T12:35:57.000Z",
            "projectName": "New project 10/21/2025, 1:35:57 PM",
            "customerName": "Test Project 1",
            "address": "",
            "postcode": "",
            "lat": null,
            "lng": null,
            "status": ""
        },
    ...
    ],
    "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://easy-pv.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. 

POST /projects/archive

Use this endpoint to archive a project.

Authentication

Endpoint:  

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

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 archive a project:

curl -X POST 'https://easy-pv.co.uk/api/v1/projects/archive' \
     -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. 

POST /projects/unarchive

Use this endpoint to unarchive a project.

Authentication

Endpoint:  

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

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 unarchive a project:

curl -X POST 'https://easy-pv.co.uk/api/v1/projects/unarchive' \
     -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/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://easy-pv.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://easy-pv.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. 

Back to top