Tasks
Transition to Tasks 2.1
If you are currently using Tasks V2.0, please update your application to use Tasks V2.1 that supports recurrence and other new features.
Tasks are reminders that are sent to agents. These reminders may or may not be related to a campaign
Filtering Owned and Assigned tasks
You can filter between tasks that you own and tasks that are assigned to you with owner_user_id and assigned_user_id.
Examples:
- Tasks you own or are assigned to you:
/tasks
- Only tasks assigned to you:
/tasks?owner_user_id[$ne]={id}&assigned_user_id={id}
- Only tasks you've assigned to others:
/tasks?owner_user_id={id}&assigned_user_id[$ne]={id}
- Only tasks you own and are assigned to you:
/tasks?owner_user_id={id}&assigned_user_id={id}
The following fields relate to the Tasks endpoint.
Field | Limits | Required? | Writeable? |
---|---|---|---|
owner_user_id | No | No | |
The id of the user who created this task. Automatically set as the submitter's id | |||
contact_id | The contact must be owned by, assigned to or shared with the user submitting this task. | No | Yes |
The id of the contact this task refers to | |||
action_type | Yes | Yes | |
The task communication type Possible values: | |||
reminder_type | No | Yes | |
Same as action_type. Exists solely for backwards compatibility | |||
assigned_user_id | Assigned user must belong to one of your teams/groups | No | Yes |
The id of the assigned user | |||
due_at | No | Yes | |
The time at which this task is due | |||
description | 2000 characters | Yes | Yes |
The task description | |||
status | Yes | Yes | |
The status of this task Possible values: | |||
notes | 2000 characters | No | Yes |
created_at | No | No | |
The date and time at which the task was created | |||
modified_at | No | No | |
The date and time at which the task was last edited |
Submit one Task
To submit one task:
POST https://api-v2.liondesk.com//tasks
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
The request object should have this form:{
"contact_id": "2",
"action_type": "Email Contact",
"assigned_user_id": "12",
"due_at": "2018-12-16 12:00:00",
"description": "New Lead Alert",
"status": "incomplete",
"notes": "Received alert"
}
Update one Task
To update some attributes on one task:
PATCH https://api-v2.liondesk.com//tasks/10
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
data: { contact_id: "2", action_type: "Email Contact"}
Get One Task
To get one task:
GET https://api-v2.liondesk.com//tasks/1
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
The response object will have this form:{
"owner_user_id": "1",
"contact_id": "2",
"action_type": "Email Contact",
"assigned_user_id": "12",
"due_at": "2018-12-16 12:00:00",
"description": "New Lead Alert",
"status": "incomplete",
"notes": "Received alert",
"created_at": "2016-07-01T12:12:11.000Z",
"modified_at": "2018-01-09T12:24:09.000Z"
}
Tasks can only be retrieved if the querying user is the owner/creator of that task. This applies to both the GET and FIND methods
Find All Tasks
You find/search tasks by issuing a GET
request to the base endpoint:
GET https://api-v2.liondesk.com//tasks
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
The response will contain an array of task objects, like so:
{
"total": 2,
"limit": 10,
"skip": 0,
"data": [
{
"owner_user_id": "1",
"contact_id": "2",
"action_type": "Email Contact",
"assigned_user_id": "12",
"due_at": "2018-12-16 12:00:00",
"description": "New Lead Alert",
"status": "incomplete",
"notes": "Received alert",
"created_at": "2016-07-01T12:12:11.000Z",
"modified_at": "2018-01-09T12:24:09.000Z"
},
{
"owner_user_id": "5",
"contact_id": "10",
"action_type": "Text Contact",
"assigned_user_id": "21",
"due_at": "2019-06-02 13:15:00",
"description": "Email Stacy buyer on buy anniversary",
"status": "complete",
"notes": "",
"created_at": "2017-11-21T07:08:10.000Z",
"modified_at": "2018-02-01T07:08:10.000Z"
}
]
}
Filtering Tasks
The following filtering operators may be mixed and matched as desired.
Equality
You may query task fields directly by specifying equality parameters in the request URI:GET /tasks?status=incomplete&owner_user_id=8
You may wish to exclude results having some value with $ne:GET /tasks?status[$ne]=deleted
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 /tasks?$limit=2
$skip will skip the specified number of results, useful for paginating:GET /tasks?status=deleted&$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 /tasks?$limit=10&$sort[created_at]=-1
Inclusion / Exclusion
Find all records where the property values are ($in) some set:GET /tasks?status[$in]=complete&owner_user_id[$in]=16
If the column matches any of the given values, the resource shall be returned.
Similarly, you may exclude certain values with ($nin):GET /tasks?status[$nin]=complete&owner_user_id[$nin]=16
Comparisons
You may use the less-than $lt and less-than-or-equal $lte operators to filter your queries: GET /tasks?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 /tasks?created_at[$gte]=2018-05-07T10:00:00-07:00
You may also combine these operators to query for a range of values: GET /tasks?created_at[$gte]=2017-01-01&created_at[$lte]=2017-01-31T00:00:00Z
Remove
Tasks can be removed with a delete request.
DELETE https://api-v2.liondesk.com//tasks/116
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
Only the owner of the task may remove a task. Assigned users, and users with whom this task has been shared may not delete tasks.