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.

NoneEmail ContactCall ContactText ContactAgent Task - Email ReminderAgent Task - Call ReminderAgent Task - Text ReminderAgent Task - No ReminderBombBomb Video EmailDirect Mail: LetterDirect Mail: PostcardAgent Task - Direct Mail: Letter (Manual)Agent Task - Direct Mail: Postcard (Manual)completeincompletedeleted
FieldLimitsRequired?Writeable?
owner_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

action_type
YesYes

The task communication type

Possible values:
reminder_type
NoYes

Same as action_type. Exists solely for backwards compatibility

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

The id of the assigned user

due_at
NoYes

The time at which this task is due

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

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