# SitePack API: Leads

Base URL: `https://api.sitepack.eu`. Authentication, scopes and rate limits: https://sitepack.dev/api-reference/getting-started.md
Full OpenAPI document: https://sitepack.dev/openapi.json. Interactive reference: https://sitepack.dev/docs/api-reference#tag/Leads

Leads: the form submissions visitors send through the site's forms, with their notes. A new one fires the `lead.created` webhook.

In the help centre: [Leads](https://help.sitepack.eu/docs/admin/leads).

## List leads

```http
GET https://api.sitepack.eu/api/public/v1/leads
```

Operation id: `siteLeads`

**Required scope:** `leads:read` — Read form submissions and their notes

Help centre: [Form submissions](https://help.sitepack.eu/docs/admin/leads)

### Parameters

| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| `status` | query | integer | no | Only submissions in this status: 1 new, 2 in contact, 3 waiting on the lead, 4 won, 5 lost. (one of `1`, `2`, `3`, `4`, `5`) |
| `type` | query | integer | no | Only submissions of this kind: 1 contact form, 2 newsletter, 3 product enquiry, 4 other. (one of `1`, `2`, `3`, `4`) |
| `page` | query | integer | no | Which page to read, starting at 1. Out-of-range pages come back empty rather than as an error. |
| `limit` | query | integer | no | How many records per page. Defaults to 25, clamped to 100. |

### Responses

**200**: A paginated list of form submissions

```json
{
  "status": "success",
  "items": [
    {
      "uuid": "0192c560-3e91-7c25-86ab-1d47f0b93e58",
      "type": 1,
      "status": 1,
      "source": "contact_form",
      "subject": "Test ride",
      "message": "Hi, I would like to test ride the Aero 2026 in size L this Saturday. Is that possible?",
      "email": "emma@example.com",
      "first_name": "Emma",
      "last_name": "Clarke",
      "company_name": null,
      "job_title": null,
      "phone": "+44 20 7946 0958",
      "address": "12 Baker Street",
      "zip": "NW1 6XE",
      "city": "London",
      "country": "GB",
      "language": "en",
      "rating": 2,
      "value_cents": null,
      "created": "2026-06-12T10:58:03+00:00",
      "updated": "2026-06-12T10:58:03+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "totalRecords": 87,
    "totalPages": 4
  }
}
```

**401**: No access token, or the token is invalid or expired.

```json
{
  "status": "error",
  "error": {
    "code": "invalid_token",
    "message": "The access token is invalid or expired."
  }
}
```

**403**: The app lacks the required scope, or its installation is no longer active.

```json
{
  "status": "error",
  "error": {
    "code": "scope_required",
    "message": "This endpoint needs the \"leads:read\" scope, which this app was not granted.",
    "scope": "leads:read"
  }
}
```

**429**: Too many requests. Retry after the number of seconds in the Retry-After header.

```json
{
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the number of seconds in the Retry-After header."
  }
}
```

## List lead notes

```http
GET https://api.sitepack.eu/api/public/v1/leads/{uuid}/notes
```

Operation id: `siteLeadNotes`

The notes on a form submission.

**Required scope:** `leads:read` — Read form submissions and their notes

Help centre: [Form submissions](https://help.sitepack.eu/docs/admin/leads)

### Parameters

| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| `uuid` | path | string | yes | The uuid of the form submission. Uuids are unique per site: one from another site reads as not found. |

### Responses

**200**: The notes on a form submission

```json
{
  "status": "success",
  "notes": [
    {
      "note": "Called back, wants to book a test ride.",
      "is_system": true,
      "created": "2026-06-12T11:04:21+00:00"
    }
  ]
}
```

**401**: No access token, or the token is invalid or expired.

```json
{
  "status": "error",
  "error": {
    "code": "invalid_token",
    "message": "The access token is invalid or expired."
  }
}
```

**403**: The app lacks the required scope, or its installation is no longer active.

```json
{
  "status": "error",
  "error": {
    "code": "scope_required",
    "message": "This endpoint needs the \"leads:read\" scope, which this app was not granted.",
    "scope": "leads:read"
  }
}
```

**404**: That form submission does not exist on this site.

```json
{
  "status": "error",
  "error": {
    "code": "not_found",
    "message": "That form submission does not exist on this site.",
    "resource": "form submission"
  }
}
```

**429**: Too many requests. Retry after the number of seconds in the Retry-After header.

```json
{
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the number of seconds in the Retry-After header."
  }
}
```

## Add a lead note

```http
POST https://api.sitepack.eu/api/public/v1/leads/{uuid}/notes
```

Operation id: `siteAddLeadNote`

Add a note to a form submission.

**Required scope:** `leads:write` — Create, change and delete form submissions

Help centre: [Form submissions](https://help.sitepack.eu/docs/admin/leads)

### Parameters

| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| `uuid` | path | string | yes | The uuid of the form submission. Uuids are unique per site: one from another site reads as not found. |

### Request body (`application/json`), required

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `note` | string | yes | The note text. Notes written through the API are marked as system notes, because they did not come from someone typing in the admin. |

Example:

```json
{
  "note": "Called back, wants to book a test ride."
}
```

### Responses

**201**: The added note

```json
{
  "status": "success",
  "note": {
    "note": "Called back, wants to book a test ride.",
    "is_system": true,
    "created": "2026-06-12T11:04:21+00:00"
  }
}
```

**401**: No access token, or the token is invalid or expired.

```json
{
  "status": "error",
  "error": {
    "code": "invalid_token",
    "message": "The access token is invalid or expired."
  }
}
```

**403**: The app lacks the required scope, or its installation is no longer active.

```json
{
  "status": "error",
  "error": {
    "code": "scope_required",
    "message": "This endpoint needs the \"leads:write\" scope, which this app was not granted.",
    "scope": "leads:write"
  }
}
```

**404**: That form submission does not exist on this site.

```json
{
  "status": "error",
  "error": {
    "code": "not_found",
    "message": "That form submission does not exist on this site.",
    "resource": "form submission"
  }
}
```

**422**: Field "note" is required.

```json
{
  "status": "error",
  "error": {
    "code": "validation_failed",
    "message": "Field \"note\" is required.",
    "field": "note"
  }
}
```

**429**: Too many requests. Retry after the number of seconds in the Retry-After header.

```json
{
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the number of seconds in the Retry-After header."
  }
}
```

## Get a lead

```http
GET https://api.sitepack.eu/api/public/v1/leads/{uuid}
```

Operation id: `siteLead`

One lead, including the subject and message the visitor sent. A repeat submission
from the same email while the lead is still open does not create a new lead: it is
added to this one as a note (see the notes endpoint) and fires lead.updated.

**Required scope:** `leads:read` — Read form submissions and their notes

Help centre: [Form submissions](https://help.sitepack.eu/docs/admin/leads)

### Parameters

| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| `uuid` | path | string | yes | The uuid of the form submission. Uuids are unique per site: one from another site reads as not found. |

### Responses

**200**: One form submission

```json
{
  "status": "success",
  "lead": {
    "uuid": "0192c560-3e91-7c25-86ab-1d47f0b93e58",
    "type": 1,
    "status": 1,
    "source": "contact_form",
    "subject": "Test ride",
    "message": "Hi, I would like to test ride the Aero 2026 in size L this Saturday. Is that possible?",
    "email": "emma@example.com",
    "first_name": "Emma",
    "last_name": "Clarke",
    "company_name": null,
    "job_title": null,
    "phone": "+44 20 7946 0958",
    "address": "12 Baker Street",
    "zip": "NW1 6XE",
    "city": "London",
    "country": "GB",
    "language": "en",
    "rating": 2,
    "value_cents": null,
    "created": "2026-06-12T10:58:03+00:00",
    "updated": "2026-06-12T10:58:03+00:00"
  }
}
```

**401**: No access token, or the token is invalid or expired.

```json
{
  "status": "error",
  "error": {
    "code": "invalid_token",
    "message": "The access token is invalid or expired."
  }
}
```

**403**: The app lacks the required scope, or its installation is no longer active.

```json
{
  "status": "error",
  "error": {
    "code": "scope_required",
    "message": "This endpoint needs the \"leads:read\" scope, which this app was not granted.",
    "scope": "leads:read"
  }
}
```

**404**: That form submission does not exist on this site.

```json
{
  "status": "error",
  "error": {
    "code": "not_found",
    "message": "That form submission does not exist on this site.",
    "resource": "form submission"
  }
}
```

**429**: Too many requests. Retry after the number of seconds in the Retry-After header.

```json
{
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the number of seconds in the Retry-After header."
  }
}
```

## Update a lead

```http
PATCH https://api.sitepack.eu/api/public/v1/leads/{uuid}
```

Operation id: `siteUpdateLead`

**Required scope:** `leads:write` — Create, change and delete form submissions

Help centre: [Form submissions](https://help.sitepack.eu/docs/admin/leads)

### Parameters

| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| `uuid` | path | string | yes | The uuid of the form submission. Uuids are unique per site: one from another site reads as not found. |

### Request body (`application/json`), required

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `status` | integer | yes | The new status: 1 new, 2 in contact, 3 waiting on the lead, 4 won, 5 lost. (one of `1`, `2`, `3`, `4`, `5`) |
| `value_cents` | integer | no | The deal value in cents, stored only with status 4 (won). Status 5 (lost) clears it. |

Example:

```json
{
  "status": 4,
  "value_cents": 249900
}
```

### Responses

**200**: The updated form submission

```json
{
  "status": "success",
  "lead": {
    "status": 4,
    "value_cents": 249900,
    "updated": "2026-06-14T09:30:00+00:00",
    "uuid": "0192c560-3e91-7c25-86ab-1d47f0b93e58",
    "type": 1,
    "source": "contact_form",
    "subject": "Test ride",
    "message": "Hi, I would like to test ride the Aero 2026 in size L this Saturday. Is that possible?",
    "email": "emma@example.com",
    "first_name": "Emma",
    "last_name": "Clarke",
    "company_name": null,
    "job_title": null,
    "phone": "+44 20 7946 0958",
    "address": "12 Baker Street",
    "zip": "NW1 6XE",
    "city": "London",
    "country": "GB",
    "language": "en",
    "rating": 2,
    "created": "2026-06-12T10:58:03+00:00"
  }
}
```

**401**: No access token, or the token is invalid or expired.

```json
{
  "status": "error",
  "error": {
    "code": "invalid_token",
    "message": "The access token is invalid or expired."
  }
}
```

**403**: The app lacks the required scope, or its installation is no longer active.

```json
{
  "status": "error",
  "error": {
    "code": "scope_required",
    "message": "This endpoint needs the \"leads:write\" scope, which this app was not granted.",
    "scope": "leads:write"
  }
}
```

**404**: That form submission does not exist on this site.

```json
{
  "status": "error",
  "error": {
    "code": "not_found",
    "message": "That form submission does not exist on this site.",
    "resource": "form submission"
  }
}
```

**422**: Field "status" is required.

```json
{
  "status": "error",
  "error": {
    "code": "validation_failed",
    "message": "Field \"status\" is required.",
    "field": "status"
  }
}
```

**429**: Too many requests. Retry after the number of seconds in the Retry-After header.

```json
{
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the number of seconds in the Retry-After header."
  }
}
```

## Delete a lead

```http
DELETE https://api.sitepack.eu/api/public/v1/leads/{uuid}
```

Operation id: `siteDeleteLead`

**Required scope:** `leads:write` — Create, change and delete form submissions

Help centre: [Form submissions](https://help.sitepack.eu/docs/admin/leads)

### Parameters

| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| `uuid` | path | string | yes | The uuid of the form submission. Uuids are unique per site: one from another site reads as not found. |

### Responses

**200**: The form submission was deleted

```json
{
  "status": "success"
}
```

**401**: No access token, or the token is invalid or expired.

```json
{
  "status": "error",
  "error": {
    "code": "invalid_token",
    "message": "The access token is invalid or expired."
  }
}
```

**403**: The app lacks the required scope, or its installation is no longer active.

```json
{
  "status": "error",
  "error": {
    "code": "scope_required",
    "message": "This endpoint needs the \"leads:write\" scope, which this app was not granted.",
    "scope": "leads:write"
  }
}
```

**404**: That form submission does not exist on this site.

```json
{
  "status": "error",
  "error": {
    "code": "not_found",
    "message": "That form submission does not exist on this site.",
    "resource": "form submission"
  }
}
```

**429**: Too many requests. Retry after the number of seconds in the Retry-After header.

```json
{
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the number of seconds in the Retry-After header."
  }
}
```