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

GET 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	sort direction: 1 or -1. Return the results in ascending or descending order. defaults to desc
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

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
      },
      ...
   ]
}

Example

curl -v -X GET -H 'Content-Type: application/json' -u [email protected]:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads

Get a lead by id

GET 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

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
}

Example

curl -v -X GET -H 'Content-Type: application/json' -u [email protected]:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads/5c81593adf767b0017d1aa66

Create a new lead

POST 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

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
}

Example:

curl -v -X POST -H 'Content-Type: application/json' -u [email protected]:123456  -d '{"fullname":"andrea", "lead_id":"123456"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads

Update a lead by id

PUT 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

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
}

Example:

curl -v -X PUT -H 'Content-Type: application/json' -u [email protected]:123456  -d '{"fullanem":"andrea", "lead_id":"123456"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads/5c81593adf767b0017d1aa66

Delete a lead by id

DELETE 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

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
}

Example:

curl -v -X DELETE -H 'Content-Type: application/json' -u [email protected]:123456  https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads/5c81593adf767b0017d1aa66