# Leads

You can use the API to get or set lead information.

## The Lead Model

Our Lead API is a central place to gather all information and take actions on your contacts (leads), such as fetching, searching, creating, updating, and deleting.

| Key         | Type   | Description                                                                     |
| ----------- | ------ | ------------------------------------------------------------------------------- |
| id          | String | The unique identifier for the lead which is given by Tiledesk.                  |
| lead\_id    | String | A unique identifier for the lead which is given to Tiledesk.It's an external id |
| fullname    | String | The lead name and surname.                                                      |
| attributes  | Object | The custom attributes which are set for the lead.                               |
| createdAt   | String | The time (ISO-8601 date string) when the lead was created.                      |
| updatedAt   | String | The time (ISO-8601 date string) when the lead was updated.                      |
| createdBy   | String | The unique identifier of the row creator                                        |
| id\_project | String | The unique identifier of the project                                            |

## Get all leads

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/leads`

Allows an account to list all the leads.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | the Project Id is a unique code assigned to your project when you create it in Tiledesk. |

#### Query Parameters

| Name      | Type   | Description                                                                                                          |
| --------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| sortField | string | what field to sort the results by.                                                                                   |
| direction | string | <p>sort direction: 1 or -1. Return the results in ascending or descending order.</p><p><em>defaults to desc</em></p> |
| email     | string | search a lead by the email address                                                                                   |
| page      | number | what page of results to fetch. defaults to first page.                                                               |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |

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

```
{
   "perPage":40,
   "count":179,
   "leads":[
      {
         "_id":"5c81593adf767b0017d1aa66",
         "updatedAt":"2019-03-07T17:47:38.393Z",
         "createdAt":"2019-03-07T17:47:38.393Z",
         "lead_id":"SRbb2PfbSFcgICv9VQBcURZeloh1",
         "fullname":"Guest",
         "attributes":{
         ...
         },
         "id_project":"5b55e806c93dde00143163dd",
         "createdBy":"system",
         "__v":0
      },
      {
         "_id":"5c81565edf767b0017d1aa35",
         "updatedAt":"2019-03-07T17:35:26.132Z",
         "createdAt":"2019-03-07T17:35:26.132Z",
         "lead_id":"WTteQpKpGZN1aElfFYCP9YPaaLN2",
         "fullname":"Guest",
         "attributes":{
          ...
         },
         "id_project":"5b55e806c93dde00143163dd",
         "createdBy":"system",
         "__v":0
      },
      ...
   ]
}
```

{% endtab %}
{% endtabs %}

Example

```
curl -v -X GET -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads
```

## Get a lead by id

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/leads/:id`

Fetches a lead by his or her Lead ID

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| id          | string | the lead identifier                                                                      |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |
| Content-Type  | string | use "application/json" value                                |

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

```
{  
         "_id":"5c81593adf767b0017d1aa66",
         "updatedAt":"2019-03-07T17:47:38.393Z",
         "createdAt":"2019-03-07T17:47:38.393Z",
         "lead_id":"SRbb2PfbSFcgICv9VQBcURZeloh1",
         "fullname":"Guest",
         "attributes":{ ... },
         "id_project":"5b55e806c93dde00143163dd",
         "createdBy":"system",
         "__v":0
}
```

{% endtab %}
{% endtabs %}

Example

```
curl -v -X GET -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads/5c81593adf767b0017d1aa66
```

## Create a new lead

<mark style="color:green;">`POST`</mark> `https://api.tiledesk.com/v3/:project_id/leads`

Allows to add more leads.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |
| Content-Type  | string | use "application/json" value                                |

#### Request Body

| Name       | Type   | Description                 |
| ---------- | ------ | --------------------------- |
| email      | string | the lead email address      |
| lead\_id   | string | the external id of the lead |
| fullname   | string | The lead fullname           |
| attributes | object | The lead custom attributes  |

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

```
{  
         "_id":"5c81593adf767b0017d1aa66",
         "updatedAt":"2019-03-07T17:47:38.393Z",
         "createdAt":"2019-03-07T17:47:38.393Z",
         "lead_id":"SRbb2PfbSFcgICv9VQBcURZeloh1",
         "fullname":"Guest",
         "attributes":{ ... },
         "id_project":"5b55e806c93dde00143163dd",
         "createdBy":"system",
         "__v":0
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X POST -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  -d '{"fullname":"andrea", "lead_id":"123456"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads
```

## Update a lead by id

<mark style="color:orange;">`PUT`</mark> `https://api.tiledesk.com/v3/:project_id/leads/:id`

Allows to update a lead.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The id is the lead indentifier.                                                          |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |
| Content-Type  | string | use "application/json" value                                |

#### Request Body

| Name          | Type   | Description                |
| ------------- | ------ | -------------------------- |
| email         | string | the lead email address     |
| fullname      | string | The lead fullname          |
| attributes    | object | The lead custom attributes |
| phone         | string | The lead phone             |
| company       | string | The lead company           |
| note          | string | Notes                      |
| streetAddress | string | The lead address           |
| city          | string | The lead city              |
| region        | string | The lead region            |
| zipcode       | string | The lead zipcode           |
| country       | string | The lead country           |
| tags          | array  | The lead tags              |

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

```
{  
         "_id":"5c81593adf767b0017d1aa66",
         "updatedAt":"2019-03-07T17:47:38.393Z",
         "createdAt":"2019-03-07T17:47:38.393Z",
         "lead_id":"SRbb2PfbSFcgICv9VQBcURZeloh1",
         "fullname":"Guest",
         "attributes":{ ... },
         "id_project":"5b55e806c93dde00143163dd",
         "createdBy":"system",
         "__v":0
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X PUT -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  -d '{"fullanem":"andrea", "lead_id":"123456"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads/5c81593adf767b0017d1aa66
```

## Delete a lead by id

<mark style="color:red;">`DELETE`</mark> `https://api.tiledesk.com/v3/:project_id/leads/:id`

Allows to delete a lead.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The id is the lead indentifier.                                                          |

#### Headers

| Name          | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT. Minumun role: agent |

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

```
{  
         "_id":"5c81593adf767b0017d1aa66",
         "updatedAt":"2019-03-07T17:47:38.393Z",
         "createdAt":"2019-03-07T17:47:38.393Z",
         "lead_id":"SRbb2PfbSFcgICv9VQBcURZeloh1",
         "fullname":"Guest",
         "attributes":{ ... },
         "id_project":"5b55e806c93dde00143163dd",
         "createdBy":"system",
         "__v":0
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X DELETE -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads/5c81593adf767b0017d1aa66
```