Events
Events were previously referred to as activities in the LionDesk V1 API and the web application. The name was changed to more accurately represent the data being captured.
The following fields relate to the Events endpoint.
Field | Limits | Required? | Writeable? |
---|---|---|---|
user_id | No | No | |
The ID of the user who created this event. Automatically set as the submitter's id | |||
contact_id | User must have correct permissions to access the contact provided. | Yes | Yes |
The ID of the contact this event refers to | |||
source | No | No | |
The source of the event type. Possible values: | |||
type | 45 characters. Any custom type can be read from the API. The LionDesk UI can currently only display a predefined set of types. Support for displaying all custom types will be implemented soon. Click here to see a table containing all predefined LionDesk UI types. | Yes | Yes |
The event type. | |||
description | 2000 characters | No | Yes |
The description in relation with the event. | |||
site_domain | 100 characters | No | Yes |
The domain the from which request is received. | |||
dialer_session_id | No | No | |
The ID of the dialer session associated with the event. | |||
property | No | No | |
The property data attached to an api event. | |||
created_at | ISO8601 format | No | Yes |
The date and time at which the event was created. | |||
modified_at | ISO8601 format | No | Yes |
The date and time at which the event was last modified. |
Events Permissions
To Submit, Get, or Find events, the user must have access to the event's contact. The user can have access to a contact in one of the following ways:
- owner of the contact
- assigned to the contact
- teammate of the contact owner if team sharing is on
- shared by the user's broker
To Update or Remove events the user must be the owner of the event's contact.
Submit one Event
To submit one event:
POST https://api-v2.liondesk.com//events
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
The request object should have this form:{
"contact_id": "2",
"type": "property_viewed",
"description": "Under $250,000, type: Single Family Residential, Condo",
"site_domain": "www.mysite.com",
"created_at": "2016-07-01T12:12:11.000Z",
"modified_at": "2018-01-09T12:24:09.000Z"
}
Update one Event
Only the description field of an event can currently be updated.
PATCH https://api-v2.liondesk.com//events/10
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}{
"description": "Under $250,000, type: Single Family Residential, Condo"
}
Get One Event
To get one event:
GET https://api-v2.liondesk.com//events/1
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
The response object will have this form:{
"user_id": "1",
"contact_id": "2",
"source": "api",
"type": "property_viewed",
"description": "Under $250,000, type: Single Family Residential, Condo",
"site_domain": "www.mysite.com",
"dialer_session_id": null,
"property": {
"mls": "8940680",
"url": "hershel.com",
"address": "725 Johnson Summit",
"city": "East Florine",
"state": "CT",
"zip": "32419",
"beds": 1,
"full_baths": 10,
"half_baths": 7,
"type": "Single Family Residential",
"sqft": "3511",
"listing_price": "621434",
"listing_status": "ACTIVE",
"listing_days_on_market": 199,
"estimated_value": "1769315",
"last_sold_at": "2018-02-18 08:29:06.368",
"last_sold_price": "75513",
"latitude": "-29.0757",
"longitude": "-89.3485",
"images": "http://lorempixel.com/640/480",
"year_built": 1837,
"listed_at": "2018-05-08 22:54:04.490"
},
"created_at": "2016-07-01T12:12:11.000Z",
"modified_at": "2018-01-09T12:24:09.000Z"
}
Find All Events
You find/search events by issuing a GET
request to the base endpoint:
GET https://api-v2.liondesk.com//events
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
The response will contain an array of event objects, like so:
{
"total": 2,
"limit": 10,
"skip": 0,
"data": [
{
"user_id": "1",
"contact_id": "2",
"source": "api",
"type": "property_viewed",
"description": "Under $250,000, type: Single Family Residential, Condo",
"site_domain": "www.mysite.com",
"dialer_session_id": null,
"property": {
"mls": "8940680",
"url": "hershel.com",
"address": "725 Johnson Summit",
"city": "East Florine",
"state": "CT",
"zip": "32419",
"beds": 1,
"full_baths": 10,
"half_baths": 7,
"type": "Single Family Residential",
"sqft": "3511",
"listing_price": "621434",
"listing_status": "ACTIVE",
"listing_days_on_market": 199,
"estimated_value": "1769315",
"last_sold_at": "2018-02-18 08:29:06.368",
"last_sold_price": "75513",
"latitude": "-29.0757",
"longitude": "-89.3485",
"images": "http://lorempixel.com/640/480",
"year_built": 1837,
"listed_at": "2018-05-08 22:54:04.490"
},
"created_at": "2016-07-01T12:12:11.000Z",
"modified_at": "2018-01-09T12:24:09.000Z"
},
{
"user_id": "5",
"contact_id": "10",
"source": "web",
"type": "Text Sent",
"description": "Hi John Smith, I got your property request and will be with you ASAP. was sent to the number (555) 555-5555.",
"site_domain": "null",
"dialer_session_id": null,
"property": null,
"created_at": "2017-11-21T07:08:10.000Z",
"modified_at": "2018-02-01T07:08:10.000Z"
}
]
}
Filtering Events
The following filtering operators may be mixed and matched as desired.
Equality
You may query event fields directly by specifying equality parameters in the request URI:GET /events?contact_id=1&source=web
You may wish to exclude results having some value with $ne:GET /events?contact_id[$ne]=1
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 /events?$limit=2
$skip will skip the specified number of results, useful for paginating:GET /events?contact_id=1&$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 /events?$limit=10&$sort[created_at]=-1
Inclusion / Exclusion
Find all records where the property values are ($in) some set:GET /events?contact_id[$in]=2&contact_id[$in]=3
If the column matches any of the given values, the resource shall be returned.
Similarly, you may exclude certain values with ($nin):GET /events?contact_id[$nin]=2&contact_id[$nin]=3
Comparisons
You may use the less-than $lt and less-than-or-equal $lte operators to filter your queries: GET /events?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 /events?created_at[$gte]=2018-05-07T10:00:00-07:00
You may also combine these operators to query for a range of values: GET /events?created_at[$gte]=2017-01-01&created_at[$lte]=2017-01-31T00:00:00Z
Viewing events of teammates' contacts
Setting $teams to true will return events for all of your contacts and your teammates' contacts:
GET /events?teams=true
You can get events of specific teammates' contacts as well:
GET /events/:id?teams=true
Remove
Events can be removed with a delete request.
DELETE https://api-v2.liondesk.com//events/561
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}