Leads

Leads are a contact’s request for more information on a certain property. A contact can have multiple leads.

Submit one lead
Get one lead
Find all leads
Filtering leads

The following fields relate to the Leads endpoint.

NoneEmailTextPhoneAssignedAuto

Field	Required?	Writeable?
contact_id	Yes	Yes
The ID of the contact associated with the lead
source_id	No	Yes
The lead source ID, used for filtering. To obtain a list of source IDs, check out /lead-sources
claimed_by_user_id	No	No
The id of the user who claimed the lead
claimed_at	No	No
The date and time at which the lead was claimed
claimed_via	No	Yes
How the lead was claimed Possible values:
text_body	No	Yes
html_body	No	Yes
time_to_claim	No	No
The time it took for the lead to be claimed by a user
mls_id	No	Yes
The MLS number of the property if coming from an MLS
listing_status	No	Yes
The status of the listing associated with the lead
listing_price	No	Yes
The price of the listing associated with the lead
street_address	No	Yes
The address associated with the lead
address_1	No	No
Same as 'street_address'. Exists solely for backwards compatibility
city	No	Yes
The city associated with the lead
state	No	Yes
The state associated with the lead
zipcode	No	Yes
type	No	Yes
The lead type

Submit one Lead

To submit one lead:

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

headers: {
  Authorization: "Bearer [access token]",
  Content-Type: "application/json"
}

The request object should have this form:{ "contact_id": 123, "source_id": 1, "claimed_via": "Email", "text_body": "Lead from Zillow", "html_body": "<html>Lead from Zillow</html>", "mls_id": 2000, "listing_status": "For Sale", "listing_price": "10000000", "street_address": "171 Lake Washington Blvd E", "city": "Seattle", "state": "WA", "zipcode": 98112, "type": "Buyer" }

Get One Lead

To get one lead:

GET https://api-v2.liondesk.com//leads/788

headers: {
  Authorization: "Bearer [access token]",
  Content-Type: "application/json"
}

The response object will have this form:{ "id": 788, "claimed_at": "2018-01-16T09:09:09.000Z", "claimed_via": "Email", "text_body": "Lead from Zillow", "html_body": "<html>Lead from Zillow</html>", "time_to_claim": "00:12:34", "mls_id": 2000, "listing_status": "For Sale", "listing_price": "10000000", "street_address": "171 Lake Washington Blvd E", "address_1": "171 Lake Washington Blvd E", "city": "Seattle", "state": "WA", "zipcode": 98112, "type": "Buyer", "assigned_to_user": { "id": 8, "first_name": "Sergey", "last_name": "Brin", "email": "sergey@google.com" }, "created_by_user": { "id": 2, "first_name": "Bill", "last_name": "Gates" }, "contact": { "id": 86, "first_name": "Elon", "last_name": "Musk", "email": "elon@spacex.com" }, "source": { "id": 1, "name": "Zillow" }, "status": "Pending", "created_at": "2017-01-16T07:07:07.000Z" }

Get Contact Leads

There should always be one contact associated with a lead. If an invalid contact ID is entered, the API will return null for contact.

GET https://api-v2.liondesk.com//leads?contact_id=10

headers: {
  Authorization: "Bearer [access token]",
  Content-Type: "application/json"
}

The response object will have this form:

{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "claimed_at": "2018-12-01T08:08:08.000Z",
      "claimed_via": "Text",
      "text_body": "Lead from Trulia",
      "html_body": "<html>Lead from Trulia</html>",
      "time_to_claim": "00:01:20",
      "mls_id": "",
      "listing_status": "",
      "listing_price": "",
      "street_address": "",
      "address_1": "",
      "city": "Los Angeles",
      "state": "CA",
      "zipcode": 90028,
      "type": "Seller"
    }
  ]
}

Find All Leads

You find/search leads by issuing a GET request to the base endpoint:

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

headers: {
  Authorization: "Bearer [access token]",
  Content-Type: "application/json"
}

The response will contain an array of lead objects, like so:

{
  "total": 2,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 788,
      "claimed_at": "2018-01-16T09:09:09.000Z",
      "claimed_via": "Email",
      "text_body": "Lead from Zillow",
      "html_body": "<html>Lead from Zillow</html>",
      "time_to_claim": "00:12:34",
      "mls_id": 2000,
      "listing_status": "For Sale",
      "listing_price": "10000000",
      "street_address": "171 Lake Washington Blvd E",
      "address_1": "171 Lake Washington Blvd E",
      "city": "Seattle",
      "state": "WA",
      "zipcode": 98112,
      "type": "Buyer",
      "assigned_to_user": {
        "id": 8,
        "first_name": "Sergey",
        "last_name": "Brin",
        "email": "sergey@google.com"
      },
      "created_by_user": {
        "id": 2,
        "first_name": "Bill",
        "last_name": "Gates"
      },
      "contact": {
        "id": 86,
        "first_name": "Elon",
        "last_name": "Musk",
        "email": "elon@spacex.com"
      },
      "source": {
        "id": 1,
        "name": "Zillow"
      },
      "status": "Pending",
      "created_at": "2017-01-16T07:07:07.000Z"
    },
    {
      "id": 39,
      "claimed_at": "2018-12-01T08:08:08.000Z",
      "claimed_via": "Text",
      "text_body": "Lead from Trulia",
      "html_body": "<html>Lead from Trulia</html>",
      "time_to_claim": "00:01:20",
      "mls_id": "",
      "listing_status": "",
      "listing_price": "",
      "street_address": "",
      "address_1": "",
      "city": "Los Angeles",
      "state": "CA",
      "zipcode": 90028,
      "type": "Seller",
      "assigned_to_user": {
        "id": 7,
        "first_name": "Jack",
        "last_name": "Dorsey",
        "email": "jack@twitter.com"
      },
      "created_by_user": {
        "id": 3,
        "first_name": "Steve",
        "last_name": "Jobs"
      },
      "contact": {
        "id": 4,
        "first_name": "Jeff",
        "last_name": "Kaplan",
        "example": "jeff@blizzard.com"
      },
      "source": {
        "id": 3,
        "name": "Trulia"
      },
      "status": "Offered",
      "created_at": "2017-12-01T06:06:06.000Z"
    }
  ]
}

Filtering Leads

The following filtering operators may be mixed and matched as desired.

Equality

You may query lead fields directly by specifying equality parameters in the request URI:GET /leads?source_id=3&claimed_via=Email

You may wish to exclude results having some value with $ne:GET /leads?claimed_via[$ne]=Assigned

Dates & Times

Unless otherwise stated all dates and times should be in ISO8601 format. Examples: 2012-09-27, 2012-09-27T09:15:00Z (UTC), 2012-09-27T09:15:00-07:00 (PDT)

Limiting and Pagination

$limit will return only the number of results you specify: GET /leads?$limit=2

$skip will skip the specified number of results, useful for paginating:GET /leads?claimed_via=Assigned&$limit=2&$skip=2

Sorting

$sort will order results based on the field given.

Use 1 for ascending order, and -1 for descending order:GET /leads?$limit=10&$sort[created_at]=-1

Inclusion / Exclusion

Find all records where the property values are ($in) some set:GET /leads?contact_id[$in]=1&source_id[$in]=3If the column matches any of the given values, the resource shall be returned.

Similarly, you may exclude certain values with ($nin):GET /leads?contact_id[$nin]=1&source_id[$nin]=3

Comparisons

You may use the less-than $lt and less-than-or-equal $lte operators to filter your queries: GET /leads?created_at[$lt]=2020-01-01T00:00:00Z

Similarly, you may use greater-than $gt and greater-than-or-equal $gte operators to filter your queries: GET /leads?created_at[$gte]=2018-05-07T10:00:00-07:00

You may also combine these operators to query for a range of values: GET /leads?created_at[$gte]=2017-01-01&created_at[$lte]=2017-01-31T00:00:00Z