Tasks v2.1
Tasks are reminders that are sent to agents. These reminders may or may not be related to a campaign
In this new version for Tasks API, we are supporting Recurring Task. It is hosted in a new url base:
- https://communications.liondesk.com/api/v1
- event - This is the parent structure where holds the recurring rule.
Field | Limits | Required? | Writeable? |
---|---|---|---|
scheduled_event_id | No | No | |
The id of the scheduled event. Id auto generated in the sequence | |||
crm_user_id | No | No | |
The id of the user who created this task. Automatically set as the submitter's id | |||
single_due_at | No | No | |
This date is used as a due date for single events and as start date for recurring. | |||
action | No | No | |
All events will be generated for an specific action Possible values: | |||
type | No | No | |
Event type Possible values: | |||
created_at | No | No | |
The date and time at which the task was created | |||
updated_at | No | No | |
The date and time at which the task was last edited |
- manual_event - This structure is translated to the Task structure
The following fields relate to the Tasks v2.1 endpoint.
Field | Limits | Required? | Writeable? |
---|---|---|---|
crm_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 | |||
assigned_user_id | Assigned user must belong to one of your teams/groups | Yes | Yes |
The id of the assigned user | |||
due_at | This the time on this date will be used on the other days if recurring | Yes | Yes |
The time at which this task is due | |||
recurrence_rule | This Recurrence rule must respect the definitions on rfc5545. In the absense of this field, the API wil consider it a single task - non recurrent | No | Yes |
Recurrence rule applied to the task | |||
is_all_day | No | Yes | |
Boolean flaging if this task is a all day task | |||
notify_assignee | No | Yes | |
Boolean flaging if this task should generate assignment notification and reminders | |||
update_type | This field is applicable only when updating a recurring task. The default value is 1. | No | No |
An integer representing how tasks should be updated if this is a recurrent task Possible values: | |||
delete_type | This field is applicable only when deleting a recurring task. The default value is 1. | No | No |
An integer representing how tasks should be delete if this is a recurrent task Possible values: | |||
delete_type | This field is applicable only when deleting/removing a recurring task. The default value is 1. | No | No |
An integer representing how tasks should be delete if this is a recurrent task Possible values: | |||
reminder_type | No | Yes | |
An integer representing the reminder type for the task. This field is also filtrable on the listing api as string with comma-delimited, ex: {“reminder_types”:”0,4,5,6,7”} Possible values: | |||
category_id | No | Yes | |
An integer representing the category for the task. This options can be retrieved on task-categories API | |||
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 v2.1
To submit one task v2.1:
POST https://communications.liondesk.com/api/v1/scheduled/tasks
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
You can create a single task or a recurring task.
The request object to create a single task should have this form:{
"contact_id": "2",
"assigned_user_id": "2",
"due_at": "2018-12-16T12:00:00",
"reminder_type": "1",
"category_id": "1",
"description": "New Lead Alert",
"status": "incomplete",
"notes": "Received alert"
}
When creating a recurring task, you need to send the recurrence_rule field based on rfc5545. The request object to create a recurring task should have this form:
{
"contact_id": "2",
"assigned_user_id": "2",
"due_at": "2018-12-16T12:00:00",
"recurrence_rule": "FREQ=DAILY;INTERVAL=1;COUNT=5",
"reminder_type": "1",
"category_id": "1",
"description": "New Lead Alert",
"status": "incomplete",
"notes": "Received alert"
}
Update one Task v2.1
To update some attributes on one task v2.1:
PATCH https://communications.liondesk.com/api/v1/scheduled/tasks/10
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
data: { contact_id: "2", assigned_user_id: "2"}
The update is an upsert, so you need to send all values, even the ones that you are not changing. Any omited value will result in setting the field to the default value.
In case you only want to update the status, the update_type must be equal to 3.
For all other cases, all values must be provided.
When updating a recurring task, you should send the update_type. If not present, will be used the default value:
PATCH https://communications.liondesk.com/api/v1/scheduled/tasks/10
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
data: { ...
update_type: 1,}
Get One Task v2.1
To get one task v2.1:
GET https://communications.liondesk.com/api/v1/scheduled/tasks/1
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
The response object will have this form:{
"crm_user_id": "1",
"contact_id": "2",
"assigned_user_id": "2",
"due_at": "2018-12-16T12:00:00",
"recurrence_rule": "FREQ=DAILY;INTERVAL=1;COUNT=5",
"reminder_type": "1",
"category_id": "1",
"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 v2.1 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 v2.1
You find/search tasks v2.1 by issuing a GET
request to the base endpoint:
GET https://communications.liondesk.com/api/v1/scheduled/tasks
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
The response will contain an array of task v2.1 objects, like so:
{
"total": 2,
"limit": 10,
"skip": 0,
"data": [
{
"crm_user_id": "1",
"contact_id": "2",
"assigned_user_id": "2",
"due_at": "2018-12-16T12:00:00",
"recurrence_rule": "FREQ=DAILY;INTERVAL=1;COUNT=5",
"reminder_type": "1",
"category_id": "1",
"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"
},
{
"crm_user_id": "5",
"contact_id": "10",
"assigned_user_id": "10",
"due_at": "2019-06-02T13:15:00",
"recurrence_rule": "FREQ=YEARLY;INTERVAL=1;COUNT=5",
"reminder_type": "2",
"category_id": "2",
"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 v2.1
The following filtering operators may be mixed and matched as desired.
Equality
You may query task v2.1 fields directly by specifying equality parameters in the request URI:GET /scheduled/tasks?status=incomplete&owner_user_id=8
You may wish to exclude results having some value with $ne:GET /scheduled/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 /scheduled/tasks?$limit=2
$skip will skip the specified number of results, useful for paginating:GET /scheduled/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 /scheduled/tasks?$limit=10&$sort[created_at]=-1
Inclusion / Exclusion
Find all records where the property values are ($in) some set:GET /scheduled/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 /scheduled/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 /scheduled/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 /scheduled/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 /scheduled/tasks?created_at[$gte]=2017-01-01&created_at[$lte]=2017-01-31T00:00:00Z
Remove
Tasks v2.1 can be removed with a delete request.
DELETE https://communications.liondesk.com/api/v1/scheduled/tasks/841
headers: {
Authorization: "Bearer [access token]",
Content-Type: "application/json"
}
The default delete_type is 1. If you want to change, you can add to the query string.
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.