Contacts

Contacts represent the individuals associated with a user's account. They are typically real-estate customers who may be interesting in buying or selling property.

The following fields relate to the Contacts endpoint.

FieldLimitsRequired?Writeable?
owner_user_id
Automatically set as the submitter's id
NoNo

The id of the user who owns this contact

assigned_user_id
Assigned user must belong to one of your teams/groups
NoYes

The id of the assigned user

first_name
255 characters
NoYes
last_name
255 characters
NoYes
email
255 characters
NoYes
mobile_phone
255 characters
NoYes
home_phone
45 characters
NoYes
office_phone
45 characters
NoYes
fax
45 characters
NoYes
company
45 characters
NoYes
birthday
45 characters
NoYes
anniversary
45 characters
NoYes

Either purchase or sale anniversary

spouse_name
45 characters
NoYes
spouse_email
45 characters
NoYes
spouse_phone
NoYes
spouse_birthday
NoYes
tags
508 characters
NoYes

The tag

created_at
NoYes

The date and time at which the contact was created

modified_at
NoYes

The date and time at which the contact was last edited

hotness_id
NoYes

The hotness id

source_id
NoYes

The source id

While no contact fields are strictly required, care should be taken to fill as much information as possible to provide the greatest value.

Related Resources

Contacts have the following related resources, manipulated through the contacts endpoint:

Submit one Contact

To submit one contact:

POST https://api-v2.liondesk.com//contacts headers: { Authorization: "Bearer [access token]", Content-Type: "application/json" }

The request object should have this form:{ "assigned_user_id": 2, "first_name": "Bill", "last_name": "Gates", "email": "bill@microsoft.com", "mobile_phone": "1 (604) 555-4572", "home_phone": "1 (604) 555-1124", "office_phone": "1 (208) 555-4432", "fax": "1 (306) 555-0449", "company": "Microsoft", "birthday": "1955-10-28", "anniversary": "2017-10-31", "spouse_name": "Melinda Gates", "spouse_email": "melinda@gatesfoundation.com", "spouse_phone": "1 (604) 555-1124", "spouse_birthday": "1964-08-15", "tags": "Pending", "created_at": "2016-07-01T12:12:11.000Z", "modified_at": "2018-01-09T12:24:09.000Z", "hotness_id": 12, "source_id": 12 }

Update one Contact

To update some attributes on one contact:

PATCH https://api-v2.liondesk.com//contacts/10 headers: { Authorization: "Bearer [access token]", Content-Type: "application/json" }

data: {
assigned_user_id: "2",
first_name: "Bill"
}

Get One Contact

To get one contact:

GET https://api-v2.liondesk.com//contacts/1 headers: { Authorization: "Bearer [access token]", Content-Type: "application/json" }

The response object will have this form:{ "owner_user_id": 1, "assigned_user_id": 2, "first_name": "Bill", "last_name": "Gates", "email": "bill@microsoft.com", "mobile_phone": "1 (604) 555-4572", "home_phone": "1 (604) 555-1124", "office_phone": "1 (208) 555-4432", "fax": "1 (306) 555-0449", "company": "Microsoft", "birthday": "1955-10-28", "anniversary": "2017-10-31", "spouse_name": "Melinda Gates", "spouse_email": "melinda@gatesfoundation.com", "spouse_phone": "1 (604) 555-1124", "spouse_birthday": "1964-08-15", "tags": "Pending", "created_at": "2016-07-01T12:12:11.000Z", "modified_at": "2018-01-09T12:24:09.000Z", "addresses": [ { "id": 279, "type": "Main Office", "street_address_1": "1428 S. Broadway", "street_address_2": "", "zip": "75482", "city": "Sulphur Springs", "state": "", "created_at": null, "modified_at": null } ], "hotness": { "name": "Pending", "rank": 14, "color": "#3b274c" }, "custom_fields": [ { "id": 21, "user_id": 8, "name": "infrastructures", "rank": 2, "data_type": "Number", "value": null } ], "source": { "id": 12, "name": "Zillow Lead", "user_id": 12, "created_at": "2015-01-09T03:34:15.000Z" } }

Contacts can only be retrieved if the querying user meets one of the following requirements:

  • Is the owner
  • Is assigned that contact
  • Has been shared that contact by a teammate or the owning user

This applies to GET, FIND, and PATCH methods

Find All Contacts

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

GET https://api-v2.liondesk.com//contacts headers: { Authorization: "Bearer [access token]", Content-Type: "application/json" }

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

{ "total": 2, "limit": 10, "skip": 0, "data": [ { "owner_user_id": 1, "assigned_user_id": 2, "first_name": "Bill", "last_name": "Gates", "email": "bill@microsoft.com", "mobile_phone": "1 (604) 555-4572", "home_phone": "1 (604) 555-1124", "office_phone": "1 (208) 555-4432", "fax": "1 (306) 555-0449", "company": "Microsoft", "birthday": "1955-10-28", "anniversary": "2017-10-31", "spouse_name": "Melinda Gates", "spouse_email": "melinda@gatesfoundation.com", "spouse_phone": "1 (604) 555-1124", "spouse_birthday": "1964-08-15", "tags": "Pending", "created_at": "2016-07-01T12:12:11.000Z", "modified_at": "2018-01-09T12:24:09.000Z", "addresses": [ { "id": 279, "type": "Main Office", "street_address_1": "1428 S. Broadway", "street_address_2": "", "zip": "75482", "city": "Sulphur Springs", "state": "", "created_at": null, "modified_at": null } ], "hotness": { "name": "Pending", "rank": 14, "color": "#3b274c" }, "custom_fields": [ { "id": 21, "user_id": 8, "name": "infrastructures", "rank": 2, "data_type": "Number", "value": null } ], "source": { "id": 12, "name": "Zillow Lead", "user_id": 12, "created_at": "2015-01-09T03:34:15.000Z" } }, { "owner_user_id": 5, "assigned_user_id": 10, "first_name": "Steve", "last_name": "Jobs", "email": "steve.jobs@apple.com", "mobile_phone": "1 (250) 555-8899", "home_phone": "1 (250) 555-8574", "office_phone": "1 (208) 555-2378", "fax": "1 (306) 555-8711", "company": "Apple", "birthday": "1955-02-24", "anniversary": "2016-04-12", "spouse_name": "Laurene Powell", "spouse_email": "lapow@icloud.com", "spouse_phone": "1 (250) 555-8574", "spouse_birthday": "1963-11-06", "tags": "Seller", "created_at": "2017-11-21T07:08:10.000Z", "modified_at": "2018-02-01T07:08:10.000Z", "addresses": [ { "id": 279, "type": "Main Office", "street_address_1": "1428 S. Broadway", "street_address_2": "", "zip": "75482", "city": "Sulphur Springs", "state": "", "created_at": null, "modified_at": null } ], "hotness": { "name": "Hot", "rank": 12, "color": "#3b274c" }, "custom_fields": [], "source": { "id": 12, "name": "Referral", "user_id": 12, "created_at": "2015-01-09T03:34:15.000Z" } } ] }

Filtering Contacts

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

Equality

You may query contact fields directly by specifying equality parameters in the request URI:GET /contacts?first_name=bill&last_name=gates

You may wish to exclude results having some value with $ne:GET /contacts?last_name[$ne]=gates

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 /contacts?$limit=2

$skip will skip the specified number of results, useful for paginating:GET /contacts?last_name=gates&$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 /contacts?$limit=10&$sort[created_at]=-1

Inclusion / Exclusion

Find all records where the property values are ($in) some set:GET /contacts?last_name[$in]=gates&last_name[$in]=jobsIf the column matches any of the given values, the resource shall be returned.

Similarly, you may exclude certain values with ($nin):GET /contacts?last_name[$nin]=gates&last_name[$nin]=jobs

Comparisons

You may use the less-than $lt and less-than-or-equal $lte operators to filter your queries: GET /contacts?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 /contacts?created_at[$gte]=2018-05-07T10:00:00-07:00

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

Caveats to Filtering Contacts

  • Only created_at and modified_at dates are guaranteed to be well-formed dates
  • Since created_at and modified_at are date-time fields, use ranges to search for full days.
  • Use ranges of days to search for time periods.

Remove

Contacts can be removed with a delete request.

DELETE https://api-v2.liondesk.com//contacts/971 headers: { Authorization: "Bearer [access token]", Content-Type: "application/json" }

Only the owner of the contact may remove a contact. Assigned users, and users with whom this contact has been shared may not delete contacts.