About the Tasks API

With Tasks, site admins can efficiently create and manage tasks on a site. This enables site admins to organize and prioritize their daily activities, enhancing their customer relationship management. Tasks include activities such as follow up calls or emails, scheduling meetings with clients, tracking steps for customer onboarding, and more.

The Tasks API allows you to:

  • Create and update tasks with the option to set a due date or to link the task to a contact.
  • Count the total amount of tasks you have, or count the amount of tasks based on provided filters. For example, you can count the number of tasks that are linked to a specific contact.
  • Retrieve tasks.
  • Prioritize your tasks by adjusting the display order.
  • Delete tasks you no longer need.

Terminology

  • Task: A specific activity, action, or assignment that needs to be completed by a site admin.
  • Reminder notification: A notification that is sent if the task has a due date. The reminder is sent the day before the due date and on the due date.
Was this helpful?
Yes
No

Setup

To use the Tasks API, install the @wix/crm package using npm or Yarn:

Copy
1
npm install @wix/crm

or

Copy
1
yarn add @wix/crm

Then import { tasks } from @wix/crm:

Copy
1
import { tasks } from '@wix/crm'
Was this helpful?
Yes
No
countTasks( )

Counts the number of tasks.

This endpoint returns the count of all tasks regardless of the task status.

Optionally, you can pass a filter to count only tasks based on specified criteria.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Tasks
Manage Tasks
Learn more about permission scopes.
Copy
function countTasks(options: CountTasksOptions): Promise<CountTasksResponse>
Method Parameters
optionsCountTasksOptions
Filtering options.
Returns
Return Type:Promise<CountTasksResponse>
Was this helpful?
Yes
No
createTask( )

Creates a new task.

All fields in the task object are optional. If you don't pass any fields in the task object, the function returns a task with the following core properties:

  • _id
  • _createdDate
  • _updatedDate
  • status
  • source
  • revision

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Tasks
Learn more about permission scopes.
Copy
function createTask(task: Task): Promise<Task>
Method Parameters
taskTaskRequired
Task to create.
Returns
Return Type:Promise<Task>
Was this helpful?
Yes
No
deleteTask( )

Deletes a task by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Tasks
Learn more about permission scopes.
Copy
function deleteTask(taskId: string): Promise<void>
Method Parameters
taskIdstringRequired
ID of the task to delete.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No
getTask( )

Retrieves a task by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Tasks
Manage Tasks
Learn more about permission scopes.
Copy
function getTask(taskId: string): Promise<Task>
Method Parameters
taskIdstringRequired
ID of the task to retrieve.
Returns
Return Type:Promise<Task>
Was this helpful?
Yes
No
moveTaskAfter( )

Moves a task specified by ID to be placed after another task in the display.

You can reposition a task to be first in the display by ommitting beforeTaskId.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Tasks
Learn more about permission scopes.
Copy
function moveTaskAfter(taskId: string, options: MoveTaskAfterOptions): Promise<void>
Method Parameters
taskIdstringRequired
The task ID to move.
optionsMoveTaskAfterOptions
Options for moving the task.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No
queryTasks( )

Creates a query to retrieve a list of tasks.

The queryTasks() function builds a query to retrieve a list of tasks and returns a TasksQueryBuilder object.

The returned object contains the query definition which is typically used to run the query using the find() function. You can refine the query by chaining TasksQueryBuilder functions onto the query. TasksQueryBuilder functions enable you to sort, filter, and control the results that queryTasks() returns.

queryTasks() runs with these TasksQueryBuilder defaults, which you can override:

  • limit(50)
  • descending('_createdDate')

The functions that are chained to queryTasks() are applied in the order they are called. For example, if you apply ascending('_createdDate') and then descending('_updatedDate'), the results are sorted first by the created date and then, if there are multiple results with the same date, the items are sorted by the updated date.

The following TasksQueryBuilder functions are supported for queryTasks(). For a full description of the task object, see the object returned for the items property in TasksQueryResult.

PROPERTYSUPPORTED FILTERS & SORTING
_ideq(),ne(),in(),ascending(),descending()
_createdDateeq(),ne(),gt(),lt(),ge(),le(),ascending(),descending()
_updatedDateeq(),ne(),gt(),lt(),ge(),le(),ascending(),descending()
dueDateeq(),ne(),gt(),lt(),ge(),le(),ascending(),descending()
statuseq(),ne(),in()
contact.ideq(),ne(),in(),exists()

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Tasks
Manage Tasks
Learn more about permission scopes.
Copy
function queryTasks(): TasksQueryBuilder
Request
This method does not take any parameters
Returns
Return Type:TasksQueryBuilder
Was this helpful?
Yes
No
updateTask( )

Updates a task.

Each time the task is updated, revision increments by 1. The existing revision must be included when updating the task. This ensures you're working with the latest task and prevents unintended overwrites.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Tasks
Learn more about permission scopes.
Copy
function updateTask(_id: string, task: UpdateTask): Promise<Task>
Method Parameters
_idstringRequired
Task ID.
taskUpdateTaskRequired
Task to update.
Returns
Return Type:Promise<Task>
Was this helpful?
Yes
No