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
To support recurring task, we are also introducing 2 new data structures
  • event - This is the parent structure where holds the recurring rule.
tasks - When the event is generate from a calendar taskcampaign_actions - When the event is generate from a campaign taskrecurrent - If this event is a recurrent event - must have recurrenceRule field presentsingle - If the event is a single event
FieldLimitsRequired?Writeable?
scheduled_event_id
NoNo

The id of the scheduled event. Id auto generated in the sequence

crm_user_id
NoNo

The id of the user who created this task. Automatically set as the submitter's id

single_due_at
NoNo

This date is used as a due date for single events and as start date for recurring.

action
NoNo

All events will be generated for an specific action

Possible values:
type
NoNo

Event type

Possible values:
created_at
NoNo

The date and time at which the task was created

updated_at
NoNo

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.

1 - Update only this task. Other tasks in the series remain unchanged.2 - Update this and following tasks. Update this and upcoming tasks in the series.3 - Updates ONLY the status field - Use this type if you want to change only the status1 - Delete only this task2 - Delete this and the following tasks3 - Delete all tasks if recurrence1 - Delete only this task. Other tasks in the series remain unchanged.2 - Delete this and following tasks. Delete this and upcoming tasks in the series.3 - Delete all tasks. Delete all tasks in the series.0 - No reminder will be sent1 - Email2 - Call // Deprecated3 - SMS4 - Agent task email reminder // Deprecated5 - Agent task call reminder // Deprecated6 - Agent task text reminder // Deprecated7 - Agent task no reminder // Deprecatedcompleteincompletedeleted
FieldLimitsRequired?Writeable?
crm_user_id
NoNo

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.
NoYes

The id of the contact this task refers to

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

The id of the assigned user

due_at
This the time on this date will be used on the other days if recurring
YesYes

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
NoYes

Recurrence rule applied to the task

is_all_day
NoYes

Boolean flaging if this task is a all day task

notify_assignee
NoYes

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.
NoNo

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.
NoNo

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.
NoNo

An integer representing how tasks should be delete if this is a recurrent task

Possible values:
reminder_type
NoYes

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
NoYes

An integer representing the category for the task. This options can be retrieved on task-categories API

description
2000 characters
YesYes

The task description

status
YesYes

The status of this task

Possible values:
notes
2000 characters
NoYes
created_at
NoNo

The date and time at which the task was created

modified_at
NoNo

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]=16If 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.