# Leads: Fetch, create, update & delete

This guide covers the API endpoints that handle leads.

Jump to section:

- [POST /leads/fetch](https://help.heatpunk.co.uk/link/252#bkmrk-patch-%2Fprojects%2Fupda)
- [POST /leads/create](https://help.heatpunk.co.uk/link/252#bkmrk-patch-%2Fprojects%2Fupda-1)
- [POST /leads/update](https://help.heatpunk.co.uk/link/252#bkmrk-post-%2Fleads%2Fupdate)
- [DELETE /leads/delete](https://help.heatpunk.co.uk/link/252#bkmrk-delete-%2Fleads%2Fdelete)

---

##  `POST` /leads/fetch

Use this endpoint to get all the leads from your leads dashboard so you can see them in your CRM.

<details id="bkmrk-authentication-endpo-1"><summary>Authentication</summary>

**Endpoint:**

```javascript
POST https://[DOMAIN]/api/v1/leads/fetch
```

**Headers:**

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

</details><details id="bkmrk-request-structure-yo"><summary>Request structure</summary>

Every request must include `userEmail` and `furthestDate` in the body.

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

**Furthest date:** `furthestDate` should be in the format (YYYY-MM-DD).

</details><details id="bkmrk-example-api-request-"><summary>Example API request and response</summary>

##### Example API Request

Below is an example using `curl` that demonstrates how to fetch leads:

```javascript
curl  -X POST 'https://heatpunk.co.uk/api/v1/leads/fetch' \
      -H 'x-api-key: YOUR_API_KEY_HERE'
      -d '{
            "userEmail": "saira.noor@midsummerenergy.co.uk",
            "furthestDate": "2025-09-10"
          }'
```

##### Response

A successful call will return a JSON array of lead objects, that looks like this:

```javascript
{
    "rows": {
        "32123": {
        "dateCreated": "2025-03-11T11:03:29.000Z",
        "status": "new",
        "customerName": "John Doe",
        "address": "8 The Rowans, Milton, Cambridge, Cambridgeshire, CB24 6YU",
        "customerEmail": "test@test.com",
        "customerPhone": "07111111111",
        ...
        },
    ...
    }
}
```


</details>
---


## `POST` /leads/create

Use this endpoint to insert a lead that comes from sources that aren't Speedy PV.

<details id="bkmrk-authentication-endpo"><summary>Authentication</summary>

**Endpoint:**

```javascript
POST https://[DOMAIN]/api/v1/leads/create
```

**Headers:**

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

</details><details id="bkmrk-request-structure-ev-1"><summary>Request structure</summary>

The request body can take the following parameters:

- `address` can include the postcode.
- `postcode`
- `customerEmail`
- `customerName`
- `customerPhone`
- `lat` and `lng` in [decimal degrees ](https://en.wikipedia.org/wiki/Decimal_degrees)format.

</details><details id="bkmrk-example-api-request--1"><summary>Example API request and response</summary>

##### Example API Request

Below is an example using `curl` that demonstrates how to save a lead with the require fields:

```javascript
curl  -X POST 'https://heatpunk.co.uk/api/v1/leads/create' \
      -H 'x-api-key: YOUR_API_KEY_HERE' \
      -d '{
            "address": "7 Erdiston Ct, Bude, EX23 8HE",
            "customerName": "John Doe",
            "customerEmail": "john.doe@example.com",
            "customerPhone": "1234567890"
          }'
```

##### Response

A successful call will return a JSON object containing a `leadId`.


</details>
---


## `POST` /leads/update

Use this endpoint to update the details of a lead.

<details id="bkmrk-authentication-endpo-2"><summary>Authentication</summary>

**Endpoint:**

```javascript
POST https://[DOMAIN]/api/v1/leads/update
```

**Headers:**

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

</details><details id="bkmrk-request-structure-ev"><summary>Request structure</summary>

Every request must include the following in the request body:

- **Lead ID:** The `leadID` of the lead you want to update.
- **User email:** `userEmail` should be a valid email address of an Easy PV Pro team member who has access to the project.
- **Fields object:** A `fields` object containing the information to be updated. See the projects/create endpoint documentation for the list of meta fields that can be updated.

</details><details id="bkmrk-example-api-request--2"><summary>Example API request and response</summary>

##### Example API Request

Below is an example using `curl` that demonstrates how to save a lead with the required fields:

```javascript
curl  -X POST 'https://heatpunk.co.uk/api/v1/leads/update' \
      -H 'x-api-key: YOUR_API_KEY_HERE' \
      -d '{
            "leadID": "1001",
            "userEmail": "saira.noor@midsummerenergy.co.uk",
            "fields": {
              "address": "123 main st"
            }
          }'
```

##### Response

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


</details>
---


## `DELETE` /leads/delete

Use this endpoint to delete leads from your leads dashboard.

<details id="bkmrk-authentication-endpo-3"><summary>Authentication</summary>

**Endpoint:**

```javascript
DELETE https://[DOMAIN]/api/v1/leads/delete
```

**Headers:**

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

</details><details id="bkmrk-request-structure-ev-2"><summary>Request structure</summary>

Every request must include the following in the request body:

- **Lead ID:** The `leadID` of the lead you want to update.
- **User email:** `userEmail` should be a valid email address of an Easy PV Pro team member who has access to the project.

</details><details id="bkmrk-example-api-request--3"><summary>Example API request and response</summary>

##### Example API Request

Below is an example using `curl` that demonstrates how to save a lead with the require fields:

```javascript
curl  -X DELETE 'https://heatpunk.co.uk/api/v1/leads/delete' \
      -H 'x-api-key: YOUR_API_KEY_HERE' \
      -d '{
            "leadID": "1001"
            "userEmail": "saira.noor@midsummerenergy.co.uk"
          }'
```

##### Response

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


</details>