# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tiledesk.com/apis/rest-api/leads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.