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.
Field | Limits | Required? | Writeable? |
---|---|---|---|
owner_user_id | Automatically set as the submitter's id | No | No |
The id of the user who owns this contact | |||
assigned_user_id | Assigned user must belong to one of your teams/groups | No | Yes |
The id of the assigned user | |||
first_name | 255 characters | No | Yes |
last_name | 255 characters | No | Yes |
255 characters | No | Yes | |
mobile_phone | 255 characters | No | Yes |
home_phone | 45 characters | No | Yes |
office_phone | 45 characters | No | Yes |
fax | 45 characters | No | Yes |
company | 45 characters | No | Yes |
birthday | 45 characters | No | Yes |
anniversary | 45 characters | No | Yes |
Either purchase or sale anniversary | |||
spouse_name | 45 characters | No | Yes |
spouse_email | 45 characters | No | Yes |
spouse_phone | No | Yes | |
spouse_birthday | No | Yes | |
tags | 508 characters | No | Yes |
The tag | |||
created_at | No | Yes | |
The date and time at which the contact was created | |||
modified_at | No | Yes | |
The date and time at which the contact was last edited | |||
hotness_id | No | Yes | |
The hotness id | |||
source_id | No | Yes | |
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
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]=jobs
If 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.