# Leads

## Get Leads

<mark style="color:blue;">`GET`</mark> `https://api.clients.icaal.co.uk/leads`

This endpoint will list all leads ordered by the most recent.

#### Query Parameters

| Name | Type    | Description              |
| ---- | ------- | ------------------------ |
| page | integer | Offset the results page. |

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "reference": "92ccb3f8-358f-4ffc-be49-683f5a0b3a65",
      "name": "Casement Window Lead",
      "value": 0,
      "description": null,
      "postcode": "SO14 2AL",
      "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_15_0) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/89.0.4389.82 Safari\/537.36",
      "ip": "192.168.10.1",
      "referrer": "Direct",
      "referrer_url": null,
      "device_type": "desktop",
      "device_name": "Apple Macintosh",
      "browser": "Chrome",
      "browser_version": "89.0.4389.82",
      "os": "OS X",
      "os_version": "10.15.0",
      "status": "open",
      "type": "quote",
      "test": 1,
      "created_at": "2021-01-01T12:00:00.000000Z",
      "updated_at": "2021-01-01T12:00:00.000000Z",
    }
  ],
  "first_page_url": "https://api.clients.icaal.co.uk/leads?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://api.clients.icaal.co.uk/leads?page=1",
  "next_page_url": null,
  "path": "https://api.clients.icaal.co.uk/leads",
  "per_page": 20,
  "prev_page_url": null,
  "to": 20,
  "total": 1
}
```

{% endtab %}
{% endtabs %}

## Create Lead

<mark style="color:green;">`POST`</mark> `https://api.clients.icaal.co.uk/leads`

Create a new lead with associated customer data.

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th width="108.48046875" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>true</td><td>The name of the lead (e.g. Casement Window Lead).</td></tr><tr><td>first_name</td><td>string</td><td>true</td><td>The customer's first name.</td></tr><tr><td>last_name</td><td>string</td><td>true</td><td>The customer's last name.</td></tr><tr><td>company_name</td><td>string</td><td>false</td><td>The company associated with the customer.</td></tr><tr><td>email</td><td>string</td><td>true</td><td>The customer's email address.</td></tr><tr><td>phone</td><td>string</td><td>true</td><td>The customer's telephone number.</td></tr><tr><td>mobile</td><td>string</td><td>false</td><td>The customer's mobile number.</td></tr><tr><td>postcode</td><td>string</td><td>true</td><td>The UK postcode of the lead.</td></tr><tr><td>referrer</td><td>string</td><td>true</td><td>One of the following values: Canvasser, Email, Existing Customer, Facebook, Live Chat, Phone, Purchased Lead, Showroom, Website</td></tr><tr><td>status</td><td>string</td><td>true</td><td>The status of the lead. Check the lead statuses endpoint for a list of valid values.</td></tr><tr><td>user_id</td><td>integer</td><td>false</td><td>The ID of the user to assign to the lead.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Retrieve Lead

<mark style="color:blue;">`GET`</mark> `https://api.clients.icaal.co.uk/leads/:reference`

Retrieve a specific lead and it's associated data.

#### Path Parameters

| Name      | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| reference | string | The UUID that identifies the lead. |

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "data": {
    "id": 1,
    "reference": "92ccb3f8-358f-4ffc-be49-683f5a0b3a65",
    "name": "Casement Window Lead",
    "value": 0,
    "description": null,
    "postcode": "SO14 2AL",
    "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_15_0) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/89.0.4389.82 Safari\/537.36",
    "ip": "192.168.10.1",
    "referrer": "Direct",
    "referrer_url": null,
    "device_type": "desktop",
    "device_name": "Apple Macintosh",
    "browser": "Chrome",
    "browser_version": "89.0.4389.82",
    "os": "OS X",
    "os_version": "10.15.0",
    "status": "open",
    "type": "quote",
    "test": 1,
    "created_at": "2021-01-01T12:00:00.000000Z",
    "updated_at": "2021-01-01T12:00:00.000000Z",
    "customer": {
      "id": 1,
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "company_name": null,
      "email": "admin@icaal.co.uk",
      "phone": "023 8033 2675",
      "phone_link": "tel:+44-23-8033-2675",
      "mobile": null,
      "mobile_link": null,
      "address_1": null,
      "address_2": null,
      "city": null,
      "county": null,
      "postcode": "SO14 2AL",
      "avatar_url": null,
      "created_at": "2021-01-01T12:00:00.000000Z"
    },
    "quotes": [
      {
        "id": 1,
        "lead_id": 1,
        "status": "complete",
        "created_at": "2021-01-01T12:00:00.000000Z",
        "updated_at": "2021-01-01T12:00:00.000000Z",
        "items": [
          {
            "id": 1,
            "quote_id": 1,
            "product_style_id": 1,
            "name": "Casement Window",
            "price": 52500,
            "cost": null,
            "margin": null,
            "tax": null,
            "minimum": null,
            "maximum": null,
            "format": "range",
            "hidden": 1,
            "status": "active",
            "created_at": "2021-01-01T12:00:00.000000Z",
            "updated_at": "2021-01-01T12:00:00.000000Z",
            "image": {
              "id": 1,
              "name": null,
              "file_name": "S1.svg",
              "file_size": 54445,
              "content_type": "image/svg+xml",
              "alt": null,
              "public": 1,
              "processed": 0,
              "created_at": "2021-01-01T12:00:00.000000Z",
              "updated_at": "2021-01-01T12:00:00.000000Z",
              "url": "https://assets.clients.icaal.co.uk/storage/images/1/original/S1.svg"
            },
            "product_style": {
              "sku": "CW-1",
              "name": "Style 1",
              "product": {
                "name": "Casement Windows",
              }
            },
            "options": {
              "width": 800,
              "height": 800,
              "external_frame_colour": "white",
              "internal_frame_colour": "white",
              "glass": "clear",
              "frame_material": "upvc"
            }
          }
        ]
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

## Update Lead

<mark style="color:purple;">`PATCH`</mark> `https://api.clients.icaal.co.uk/leads/:reference`

Update an existing lead.

#### Path Parameters

| Name      | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| reference | string | The UUID that identifies the lead. |

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th width="107.9296875" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>value</td><td>integer</td><td>false</td><td>The numeric value of the lead in GBP.</td></tr><tr><td>status</td><td>string</td><td>false</td><td>Status of the lead.</td></tr><tr><td>user_email</td><td>string</td><td>false</td><td>Email address of the user to assign</td></tr><tr><td>notify</td><td>boolean</td><td>false</td><td>Notify assigned user</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Schedule Appointment

<mark style="color:green;">`POST`</mark> `https://api.clients.icaal.co.uk/leads/:reference/appointments`

Schedule an appointment for a lead.

#### Path Parameters

| Name      | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| reference | string | The UUID that identifies the lead. |

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th width="107.703125" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>notify</td><td>boolean</td><td>true</td><td>Notify user of appointment.</td></tr><tr><td>user_id</td><td>integer</td><td>true</td><td>The user to assign the appointment to.</td></tr><tr><td>date</td><td>string</td><td>true</td><td>The requested appointment datetime formatted as <code>dd/mm/yyyy hh:mm</code></td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Schedule Callback

<mark style="color:green;">`POST`</mark> `https://api.clients.icaal.co.uk/leads/:reference/callbacks`

Schedule a callback for a lead.

#### Path Parameters

| Name      | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| reference | string | The UUID that identifies the lead. |

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th width="108.48828125" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>notify</td><td>boolean</td><td>true</td><td>Notify user of callback.</td></tr><tr><td>user_id</td><td>integer</td><td>true</td><td>The user to assign the appointment to.</td></tr><tr><td>date</td><td>string</td><td>true</td><td>The requested callback datetime formatted as <code>dd/mm/yyyy hh:mm</code></td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Attach a file

<mark style="color:green;">`POST`</mark> `https://api.clients.icaal.co.uk/leads/:reference/attachments`

Attach a file to a lead (max 10mb). This should be sent a multipart form data.

#### Path Parameters

| Name      | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| reference | string | The UUID that identifies the lead. |

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |
| Content-Type  | string | `multipart/form-data`                |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th width="107.96484375" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>true</td><td>The name of the file.</td></tr><tr><td>file</td><td>string</td><td>true</td><td>The file in one of the following formats <code>jpeg,png,gif,svg,pdf,txt,xlsx,docx</code></td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## List Lead Statuses

<mark style="color:blue;">`GET`</mark> `https://api.clients.icaal.co.uk/leads/statuses`

List available lead statuses.

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "data": [
    "appointment_scheduled",
    "awaiting_email",
    "callback_later",
    "duplicate",
    "lost",
    "not_interested",
    "number_not_recognised",
    "open",
    "out_of_area",
    "sold",
    "spam",
    "test",
    "unable_to_contact"
  ]
}
```

{% endtab %}
{% endtabs %}