Tiledesk Developer Hub
WebsiteCommunityTutorialsGet started
  • Introduction
  • Community
  • Ask for Support
  • Public Roadmap and Changelog
  • Tutorials
  • Widget
    • Widget SDK
    • Javascript API: Methods
    • Javascript API: Attributes
    • Javascript API: Listeners/Events
    • Widget Authentication
    • Widget Angular integration
    • Widget React integration
    • Widget for Android with WebView
    • Widget for iOS with WKWebView
    • Widget for Flutter with WebView
    • Widget for React with WebView
    • Widget for Wix Website platform
    • Tutorials
      • Hide widget
      • Show/Hide widget programmatically
      • Force widget loading without user interaction
      • Mobile positioning
      • Custom size (width/height)
      • Installing widget on selected pages
    • Conversation Embedded Apps
      • Payment App Tutorial
      • Prechat form App Tutorial
    • Advanced
      • Preset the Widget on a specific Department
      • Authentication Flow
      • Widget protocol specs
      • Prechat Form JSON specs
      • Prevent multiple conversations
      • Old versions
        • Web SDK v4
  • External Chatbot
    • Introduction
    • Hello World tutorial
    • Chatbot to Human handoff
    • Send Text Buttons
    • Advanced Tutorials
      • Introduction
      • Tutorial 1 - Dialogflow as external chatbot
      • Tutorial 2 - Buttons and images
      • Tutorial 3 - Automatic human handoff with fallback intent
      • Tutorial 4 - Explicit Human handoff with user intent
      • Tutorial 5 - Gracefully handling operating hours during handoff
      • Generate Dialogflow Google Credentials file
    • Rasa tutorials
      • Rasa Tutorial 1 - Rasa as external chatbot
  • Resolution bot
    • Introduction
    • Quickstart
    • Webhook service
    • Rich messages
    • Tutorials
      • Chatbot chooser (multilanguage)
      • Department chooser
      • Order info (webhook)
  • APIs
    • REST APIs
      • Introduction
      • Authentication
      • Requests
      • Leads
      • Messages
      • Activities
      • Projects
      • Team
      • User
      • Analytics
      • Canned responses
      • Tags
      • Events
      • Jwt
      • Labels
      • Images
      • Files
      • Segments
      • Chatbots
      • Knowledge Bases
        • Knowledge Base
        • Contents
        • Question & Answer
      • Management Api
        • Departments
        • Groups
    • NodeJS SDK
    • Webhooks
      • Subscriptions
    • Conversation Messages APIs tips
    • Realtime API
    • JWT Authentication
      • JWT Custom authentication Tutorial
    • Tutorials
      • REST API
        • Sending and receiving messages with Tiledesk APIs
        • PHP Tiledesk REST API example
        • Import multiple messages into Tiledesk using REST APIs from third party app
      • Webhooks
        • Custom Request assignment
        • Request transcript on close
  • Apps
    • Build Custom App - Quick start
    • External Channels integration flow diagram
    • Telegram integration tutorial
  • Dashboard & AgentChat SDK
    • Dashboard SDK
    • Agent Chat SDK
  • Architecture
    • Architecture overview
    • Components list
    • Bot Design diagram
    • Multi Channel Message Flow
  • Installation
    • Installation
    • Running Tiledesk using Docker Compose
    • Running Tiledesk with Kubernetes using Helm
    • Choosing Hardware
  • Configuration
    • Chat21 channel configuration
    • Email parameters and templates configuration
    • Configure the logging system
Powered by GitBook
On this page
  • The Lead Model
  • Get all leads
  • Get a lead by id
  • Create a new lead
  • Update a lead by id
  • Delete a lead by id

Was this helpful?

  1. APIs
  2. REST APIs

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

{
   "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

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

{  
         "_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

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

{  
         "_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

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

{  
         "_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

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

{  
         "_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
PreviousRequestsNextMessages

Last updated 1 year ago

Was this helpful?