Leads Overview

This guide describes the steps for creating a new lead and setting up lead offer distributions.

When a lead (an inquiry) reaches the system, it can be routed to a user so that they may follow up.

The family of leads endpoints describe how to set the routing up, and distribute offers to your user or their colleagues.

Definitions

Lead vs Contact

A lead is a contact’s request for more information on a property and can be followed up on
A user's contact can have multiple leads enquiring about different properties

Leads Submission Walkthrough

Decide whether to distribute lead offers to the current user or to a team

• Current User: The current user will automatically be assigned.
• Members of a Team: The incoming lead may be distributed to members of some team.

• Current User

  keyboard_arrow_down

  Setting Up Lead Offer Distributions

  This setup procedure only needs to be done once for each relevant lead source and/or contact source. Once complete, it should handle the routing and distribution of any leads that come in from the specified sources.

  The process for setting up lead distributions to the current user is simple:

  1. Decide on the relevant sources
  2. Set up a campaign and list of campaign actions
  3. Verify the lead route is configured
  4. Find or create a contact
  5. Create a lead for the contact
  6. Start the campaign specified in the lead route for the new contact

  
  

  Decide whether to distribute lead offers based on the lead source, contact source, or both.

  Note that lead offers are typically distributed based on the lead source.

  See the definitions above for more information on these terms.

  • Finding a lead source

    keyboard_arrow_down
    GET https://api-v2.liondesk.com//lead-sources?name=ZillowExample lead source response object:{ "id": 1, "name": "Zillow" }

    Note that the id above represents the lead source id

  
  
  • Finding a contact source

    keyboard_arrow_down
    GET https://api-v2.liondesk.com//contact-sources?name=EmailExample contact source response object:{ "id": 3, "name": "Email", "user_id": 2 },

    Note that the id above represents the contact source id

  Set up a campaign and list of campaign actions
  If you would like to start a campaign for a contact when a new lead comes in, seach for or create a campaign, and make note of the campaign's id
  • Searching for a campaign by name

    keyboard_arrow_down
    GET /campaigns?name[$like]=%Campaign Name%

    It may be necessary to escape the percent sign (%) to ensure proper encoding:

    GET /campaigns?name[$like]=%25Campaign Name%25

    Example campaign response object:

    {

    "id": 6,

    "name": "LionDesk: General Buyer Drip", "created_at": "2017-07-08T11:11:11.000Z", "modified_at": "2018-01-16T12:12:12.000Z", "is_broker_sharing_on": true, "is_default": true, "is_shared_by_broker": true }
  • Creating a new campaign

    keyboard_arrow_down

    If no existing campaigns suit your needs, create a new one:

    POST /campaignsExample request object:{ "name": "LionDesk: General Buyer Drip", "is_broker_sharing_on": true }
  Set up instructions for creating action items for a campaign by searching for or creating campaign actions
  • Finding campaign actions

    keyboard_arrow_down
    GET /campaigns/6/actions?$load=template

    Example campaign response object:

    { "total": 8, "limit": 10, "skip": 0, "data": [ { "id": 4, "template_metadata_id": 28, "template": { "template_metadata_id": 28, "id": 7, "description": "Modi ad quasi.", "subject": "Unde commodi nisi delectus dolorum." }, "delay_by_seconds": null, "timing_type": "Delay by Day and Time", "dispatch_time": "02:02:00", "dispatch_datetime": null, "delay_by_days": 199, "notes": "", "assigned_user_id": 6, "recurrence": null, "is_stopped_on_text_reply": false, "type": "Email Contact" }, { "id": 46, "template_metadata_id": 0, "template": null, "delay_by_seconds": 600, "timing_type": "Delay by Minutes", "dispatch_time": null, "dispatch_datetime": null, "delay_by_days": null, "notes": "Follow up with the client at 18:30.", "assigned_user_id": 5, "recurrence": null, "is_stopped_on_text_reply": true, "type": "Agent Task - Text Reminder" }, ] }
  • Creating a new campaign action

    keyboard_arrow_down
    POST /campaigns/6/actions

    Example request object:

    { "type": "Email Contact", "assigned_user_id": 10, "template_metadata_id": 2, "timing_type": "Delay by Day and Time", "delay_by_seconds": null, "delay_by_days": 1, "dispatch_time": "20:30:00", "dispatch_datetime": null, "notes": "", "is_stopped_on_text_reply": false }

  1. Ensure a lead route is set up for the desired source.

  • Finding a lead route

    keyboard_arrow_down

    Make sure that the campaign id associated with the lead route is correct

    GET https://api-v2.liondesk.com//lead-routes?lead_source_id=1&contact_source_id=3

    Example lead route response object:

    { "id": 12,

    "team": null,

    "distribution_target": "Myself", "filter": "Buyer", "campaign": {

    "id": 6,

    "name": "LionDesk: General Buyer Drip" }, "lead_source": { "id": 1, "name": "Zillow" }, "contact_source": { "id": 3, "name": "Email" }, }

    The team will be null when distributing to the current user.

    If such a lead route exists, no further set up is required. Future leads will be automatically assigned to the current user.

  • Creating a lead route

    keyboard_arrow_down

    If no lead route is found, create one for each of your desired source(s):

    POST /lead-routes

    Example request object:

    { "campaign_id": 6, "lead_source_id": 1, "contact_source_id": 3, "distribution_target": "Myself", "filter": "Buyer" }

  Submitting Leads

  Find or create a contact

  To prevent creating duplicate contacts, first attempt to find the contact by parameters such as their email and/or phone number (mobile_phone, home_phone, or office_phone):

  • Check if a contact already exists

    keyboard_arrow_down
    GET https://api-v2.liondesk.com//contacts?email=paul@microsoft.com&mobile_phone=1(604)555-4572

    If the contact is found, take note of the id and continue to the next step (creating a lead).

  • Creating a new contact

    keyboard_arrow_down

    If the contact is not found, create a new contact and fill in as much detail as possible:

    POST https://api-v2.liondesk.com//contactsExample request object:{ "source_id": 3 "first_name": "Paul", "last_name": "Allen", "email": "paul@microsoft.com", "mobile_phone": "1(604)555-4572", "company": "Microsoft", "tags": "Pending", "hotness_id": 12, "assigned_user_id": 2, }

    Note that you can also add tags and hotnesses when creating a new contact

  Refer to the contacts page for full information.

  Create a new lead
  POST /leadsExample request object:{ "contact_id": 123, "source_id": 1, "text_body": "Lead from Zillow", "mls_id": 2000, "listing_status": "For Sale", "listing_price": "10000000", "street_address": "16215 Alton Pkwy", "city": "Irvine", "state": "CA",
"type": "Buyer" }
  Note the following about the lead submitted above:
  • Some lead route target will be found from the sources.
    • the contact's source_id (found on the contact record)
    • the lead's source_id
  • If you would like to start a campaign for the contact, make note of the contact_id for the next step
  • The lead will be distributed to the current user if the matching lead route specifies a target of "Myself"
  
  
  Initiate a campaign for a contact by creating a campaign contact
  This will also create and schedule a list of automated contact communications and/or agent tasks for the contact based on the specifications in campaign actions.
  Make sure that:
  • The campaign ID passed in to the query below is the same as the one specified in your lead route
  • The contact_id passed in to the request object is the same as the lead created in the previous step
  POST /campaigns/6/contacts
  Example request object:
  { contact_id: 123 }
  After a campaign contact is created, the list of contact communications and agent tasks can be retrieved:
  • View contact communications

    keyboard_arrow_down

    Replace the percent sign character (%) in the query below with %25 if needed for proper encoding

    GET /contacts/123/campaign-communications?campaign_name[$like]=%Buyer Drip%

    Example response object:

    { "total": 2, "limit": 10, "skip": 0, "data": [ {

    "campaign_name": "LionDesk: General Buyer Drip",

    "type": "Text Contact", "is_stopped_on_text_reply": true, "template_subject": "Text Template", "template_name": "Important Deadline", "template_folder_name": "New Contacts Template Folder", "is_active": true, "send_at": "2028-09-12T18:31:35.000Z", "completed_at": null, "send_from_user_id": 3, "completing_user_id": 76 }, {

    "campaign_name": "LionDesk: General Buyer Drip",

    "type": "Email Contact", "is_stopped_on_text_reply": false, "template_subject": "Email Template", "template_name": "Saying Hello", "template_folder_name": "New Contacts Template Folder", "is_active": false, "send_at": "2017-12-06T22:11:02.000Z", "completed_at": "2017-12-06T22:11:02.000Z", "send_from_user_id": 4, "completing_user_id": null } ] }
  • View agent tasks

    keyboard_arrow_down
    GET /tasks?campaign_contact_id=1

    Example response object

    { "total": 1, "limit": 10, "skip": 0, "data": [ { "id": 181, "owner_user_id": 7, "contact_id": 7,

    "campaign_contact_id": 1,

    "reminder_type": "Email Contact", "action_type": "Email Contact", "status": "incomplete", "created_at": "2018-03-16T15:43:47.000Z", "modified_at": "2018-12-12T22:47:13.000Z", "due_at": "2019-05-05T23:54:48.000Z", "completed_at": null, "description": "Non non id quam quaerat atque unde enim.", "is_all_day": false, "is_important": false, "due_end_at": null, "notes": "Rem accusantium eligendi tempore quia non.", "is_public": false, "assigned_user_id": 0, "completing_user_id": 0, "category": null, "folder": null } ] }
• Members of a Team

  keyboard_arrow_down

  Setting Up Lead Offer Distributions

  This setup procedure only needs to be done once for each relevant lead source and/or contact source. Once complete, it should handle the routing and distribution of any leads that come in from the specified sources.

  Setting up distributions to teams involves more setup than distributing to individuals

  Prerequisite steps for submitting a lead

  1. Decide on the relevant sources
  2. Set up a campaign and list of campaign actions
  3. Verify the lead route is configured
  4. Verify that each potential target team has lead rules in place
  5. Ensure that team member distribution options are set up for your teams

  Submitting a lead

  5. Find or create a contact
  6. Create a new lead
  7. Start the campaign specified in the lead route for the new contact
  8. Create lead offers for each team member

  
  

  Decide whether to distribute lead offers based on the lead source, contact source, or both.

  Note that lead offers are typically distributed based on the lead source.

  See the definitions above for more information on these terms.

  • Finding a lead source

    keyboard_arrow_down
    GET https://api-v2.liondesk.com//lead-sources?name=ZillowExample lead source response object:{ "id": 1, "name": "Zillow" }

    Note that the id above represents the lead source id

  
  
  • Finding a contact source

    keyboard_arrow_down
    GET https://api-v2.liondesk.com//contact-sources?name=EmailExample contact source response object:{ "id": 3, "name": "Email", "user_id": 2 },

    Note that the id above represents the contact source id

  Set up a campaign and list of campaign actions
  If you would like to start a campaign for a contact when a new lead comes in, seach for or create a campaign, and make note of the campaign's id
  • Searching for a campaign by name

    keyboard_arrow_down
    GET /campaigns?name[$like]=%Campaign Name%

    It may be necessary to escape the percent sign (%) to ensure proper encoding:

    GET /campaigns?name[$like]=%25Campaign Name%25

    Example campaign response object:

    {

    "id": 6,

    "name": "LionDesk: General Buyer Drip", "created_at": "2017-07-08T11:11:11.000Z", "modified_at": "2018-01-16T12:12:12.000Z", "is_broker_sharing_on": true, "is_default": true, "is_shared_by_broker": true }
  • Creating a new campaign

    keyboard_arrow_down

    If no existing campaigns suit your needs, create a new one:

    POST /campaignsExample request object:{ "name": "LionDesk: General Buyer Drip", "is_broker_sharing_on": true }
  Set up instructions for creating action items for a campaign by searching for or creating campaign actions
  • Finding campaign actions

    keyboard_arrow_down
    GET /campaigns/6/actions?$load=template

    Example campaign response object:

    { "total": 8, "limit": 10, "skip": 0, "data": [ { "id": 4, "template_metadata_id": 28, "template": { "template_metadata_id": 28, "id": 7, "description": "Modi ad quasi.", "subject": "Unde commodi nisi delectus dolorum." }, "delay_by_seconds": null, "timing_type": "Delay by Day and Time", "dispatch_time": "02:02:00", "dispatch_datetime": null, "delay_by_days": 199, "notes": "", "assigned_user_id": 6, "recurrence": null, "is_stopped_on_text_reply": false, "type": "Email Contact" }, { "id": 46, "template_metadata_id": 0, "template": null, "delay_by_seconds": 600, "timing_type": "Delay by Minutes", "dispatch_time": null, "dispatch_datetime": null, "delay_by_days": null, "notes": "Follow up with the client at 18:30.", "assigned_user_id": 5, "recurrence": null, "is_stopped_on_text_reply": true, "type": "Agent Task - Text Reminder" }, ] }
  • Creating a new campaign action

    keyboard_arrow_down
    POST /campaigns/6/actions

    Example request object:

    { "type": "Email Contact", "assigned_user_id": 10, "template_metadata_id": 2, "timing_type": "Delay by Day and Time", "delay_by_seconds": null, "delay_by_days": 1, "dispatch_time": "20:30:00", "dispatch_datetime": null, "notes": "", "is_stopped_on_text_reply": false }
  1. Ensure a lead route is set up for the desired source(s)
  • Finding a lead route

    keyboard_arrow_down

    Make sure that the campaign id associated with the lead route is correct

    GET https://api-v2.liondesk.com//lead-routes?lead_source_id=1&contact_source_id=3Example lead route response object:{ "id": 12, "distribution_target": "Team Rollout", "filter": "Buyer", "team_selection_method": "Specific Team", "team": { "id": 6, "name": "Schulist, Klein and Fay", "is_sharing_contacts": 1, "order_method": 1, "mins_until_next_alert": 0, "distribution_zipcodes": null }, "campaign": {

    "id": 6,

    "name": "LionDesk: General Buyer Drip" }, "lead_source": { "id": 1, "name": "Zillow" }, "contact_source": { "id": 3, "name": "Email" }, }

    If a lead route exists, proceed to the next step.

  • Creating a lead route

    keyboard_arrow_down

    If no lead route is found, create one for each of your desired source(s):

    POST /lead-routes

    Example request object:

    { "team_id": 3, "campaign_id": 6, "lead_source_id": 1, "contact_source_id": 3, "distribution_target": "Team Rollout", "team_selection_method": "Specific Team", "filter": "Buyer" }
  2. Verify that each potential target team has lead rules in place.

  Team properties related to leads are highlighted below:

  GET https://api-v2.liondesk.com//teams

  Example team response object:

  { "total": 2, "limit": 10, "skip": 0, "data": [{ "id": 3, "name": "Blizzard", "order_method": "Rank", "mins_until_next_alert": 5, "distribution_zipcodes": "91109,92618,32899" }, { "id": 5, "name": "Rockstar", "order_method": "Time", "mins_until_next_alert": null, "distribution_zipcodes": "" }] }

  The Blizzard team members...

  • Will be sent leads in the rank order specified in the distribution options (next step) until...
    • the lead is claimed, or
    • each member has been alerted.
  • Will be alerted one at a time, every 5 minutes.
  • May receive leads based on their zipcode, given that they have distribution zipcodes specified.
  
  

  The Rockstar team members...

  • Will be sent leads based on the time intervals specified in the distribution options until...
    • the lead is claimed, or
    • each member has been alerted.
  • May not receive leads by Zipcode, as no distribution zipcodes have been specified.

  See the teams docs for complete information;

  3. Ensure that team member distribution options are set up for your teams.

  Each record specifies:

  • How each member will be notified of a lead offer
  • If any action needs to be taken to claim a lead
  • Check if team member distribution options have been set up for your team

    keyboard_arrow_down
    GET https://api-v2.liondesk.com//team-member-distribution-options?team_id=6If there are existing team member distribution options for your team, no further action is required.
  • Create team member distribution options for your team

    keyboard_arrow_down

    Create a new record for every team member that should receive a lead offer alert.

    POST https://api-v2.liondesk.com//team-member-distribution-options

    Example request object:

    { "team_id": 6, "user_id": 2, "rank": 1, "mins_until_lead_offer": 5, "assign_automatically": true, "has_call_alert": false, "has_text_alert": true, "has_email_alert": false }

    At least one of has_call_alert, has_text_alert or has_email_alert must be set to true in order for a team member to be notified of a lead offer. Alternatively, set all of these fields to false to temporarily disable sending lead offer alerts to a specific user.

  Submitting Leads

  Find or create a contact

  To prevent creating duplicate contacts, first attempt to find the contact by parameters such as their email and/or phone number (mobile_phone, home_phone, or office_phone):

  • Check if a contact already exists

    keyboard_arrow_down
    GET https://api-v2.liondesk.com//contacts?email=paul@microsoft.com&mobile_phone=1(604)555-4572

    If the contact is found, take note of the id and continue to the next step (creating a lead).

  • Creating a new contact

    keyboard_arrow_down

    If the contact is not found, create a new contact and fill in as much detail as possible:

    POST https://api-v2.liondesk.com//contactsExample request object:{ "source_id": 3 "first_name": "Paul", "last_name": "Allen", "email": "paul@microsoft.com", "mobile_phone": "1(604)555-4572", "company": "Microsoft", "tags": "Pending", "hotness_id": 12, "assigned_user_id": 2, }

    Note that you can also add tags and hotnesses when creating a new contact

  Refer to the contacts page for full information.

  Create a new lead
  POST /leadsExample request object:{ "contact_id": 123, "source_id": 1, "text_body": "Lead from Zillow", "mls_id": 2000, "listing_status": "For Sale", "listing_price": "10000000", "street_address": "16215 Alton Pkwy", "city": "Irvine", "state": "CA",
"zipcode": 92618,
"type": "Buyer" }
  Note the following about the lead submitted above:
  • Some lead route target will be found from the sources.
    • the contact's source_id (found on the contact record)
    • the lead's source_id
  • If you would like to start a campaign for the contact, make note of the contact_id for the next step
  • The lead will be distributed to a team if the matching lead route specifies a target of "Team Rollout"
  • The distribution then depends on the lead route's team_selection_method:
    • Zipcode: Some team with zipcode 92618 will be sought.
    • Specific Team: Then select the team specified in the lead routing.
  
  
  Initiate a campaign for a contact by creating a campaign contact
  This will also create and schedule a list of automated contact communications and/or agent tasks for the contact based on the specifications in campaign actions.
  Make sure that:
  • The campaign ID passed in to the query below is the same as the one specified in your lead route
  • The contact_id passed in to the request object is the same as the lead created in the previous step
  POST /campaigns/6/contacts
  Example request object:
  { contact_id: 123 }
  After a campaign contact is created, the list of contact communications and agent tasks can be retrieved:
  • View contact communications

    keyboard_arrow_down

    Replace the percent sign character (%) in the query below with %25 if needed for proper encoding

    GET /contacts/123/campaign-communications?campaign_name[$like]=%Buyer Drip%

    Example response object:

    { "total": 2, "limit": 10, "skip": 0, "data": [ {

    "campaign_name": "LionDesk: General Buyer Drip",

    "type": "Text Contact", "is_stopped_on_text_reply": true, "template_subject": "Text Template", "template_name": "Important Deadline", "template_folder_name": "New Contacts Template Folder", "is_active": true, "send_at": "2028-09-12T18:31:35.000Z", "completed_at": null, "send_from_user_id": 3, "completing_user_id": 76 }, {

    "campaign_name": "LionDesk: General Buyer Drip",

    "type": "Email Contact", "is_stopped_on_text_reply": false, "template_subject": "Email Template", "template_name": "Saying Hello", "template_folder_name": "New Contacts Template Folder", "is_active": false, "send_at": "2017-12-06T22:11:02.000Z", "completed_at": "2017-12-06T22:11:02.000Z", "send_from_user_id": 4, "completing_user_id": null } ] }
  • View agent tasks

    keyboard_arrow_down
    GET /tasks?campaign_contact_id=1

    Example response object

    { "total": 1, "limit": 10, "skip": 0, "data": [ { "id": 181, "owner_user_id": 7, "contact_id": 7,

    "campaign_contact_id": 1,

    "reminder_type": "Email Contact", "action_type": "Email Contact", "status": "incomplete", "created_at": "2018-03-16T15:43:47.000Z", "modified_at": "2018-12-12T22:47:13.000Z", "due_at": "2019-05-05T23:54:48.000Z", "completed_at": null, "description": "Non non id quam quaerat atque unde enim.", "is_all_day": false, "is_important": false, "due_end_at": null, "notes": "Rem accusantium eligendi tempore quia non.", "is_public": false, "assigned_user_id": 0, "completing_user_id": 0, "category": null, "folder": null } ] }
  5. Create lead offers for each member of the team.

  Lead offers can only be created when:

  • There is a lead route created for a specific lead source and/or contact source
  • The lead has not been claimed by a user

  Please ensure that all team members that should receive lead offer alerts have Team Member Distribution Options created for them

  POST https://api-v2.liondesk.com//leads/4/offers

  No request object is needed here. The target distribution team will be found based on the team_selection_method - either Specific Team or Zipcode. If the distribution_method es equal to Zipcode, then the team with matching distribution_zipcodes will be targetted.

  • Example response (Click to expand)

    keyboard_arrow_down

    Note that there are multiple lead offer records in the response:

    [ { "id": 1, "rank": "2", "notify_at": "2018-01-16T09:09:09.000Z", "status": "Pending", "assign_automatically": "true", "has_call_alert": "true", "has_text_alert": "false", "has_email_alert": "true" "team": { "id": 6, "name": "IBM" }, "lead": { "id": 2, "distribution_target": "Team Rollout", "contact": { "id": 123, "first_name": "Mary", "last_name": "Jackson" } }, "user": { "id": 3, "first_name": "Dorothy", "last_name": "Vaughan", "email": "dot@example.com" }, }, { "id": 2, "rank": "3", "notify_at": "2018-01-16T09:09:09.000Z", "status": "Pending", "assign_automatically": "false", "has_call_alert": "false", "has_text_alert": "true", "has_email_alert": "true" "team": { "id": 6, "name": "IBM" }, "lead": { "id": 2, "distribution_target": "Team Rollout", "contact": { "id": 123, "first_name": "Mary", "last_name": "Jackson" } }, "user": { "id": 5, "first_name": "Jeff", "last_name": "Kaplan", "email": "jeff@example.com" }, } ]