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.

KeyTypeDescription

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

NameTypeDescription

project_id

string

the Project Id is a unique code assigned to your project when you create it in Tiledesk.

Query Parameters

NameTypeDescription

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

NameTypeDescription

Authorization

string

Authorization token. Basic Auth or JWT. Minumun role: agent

{
   "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 andrea.leo@f21.it: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

NameTypeDescription

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

NameTypeDescription

Authorization

string

Authorization token. Basic Auth or JWT. Minumun role: agent

Content-Type

string

use "application/json" value

{  
         "_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 andrea.leo@f21.it: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

NameTypeDescription

project_id

string

The project_id is a unique code assigned to your project when you create it in Tiledesk

Headers

NameTypeDescription

Authorization

string

Authorization token. Basic Auth or JWT. Minumun role: agent

Content-Type

string

use "application/json" value

Request Body

NameTypeDescription

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

{  
         "_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 andrea.leo@f21.it: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

NameTypeDescription

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

NameTypeDescription

Authorization

string

Authorization token. Basic Auth or JWT. Minumun role: agent

Content-Type

string

use "application/json" value

Request Body

NameTypeDescription

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

{  
         "_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 andrea.leo@f21.it: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

NameTypeDescription

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

NameTypeDescription

Authorization

string

Authorization token. Basic Auth or JWT. Minumun role: agent

{  
         "_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 andrea.leo@f21.it:123456  https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/leads/5c81593adf767b0017d1aa66

Last updated