Cubicl Docs


Definitions of the types and formats of the data used in the endpoints can be found at the bottom of the page.


Get Tasks
Get Task By Id
Create Task
Update Task
Delete Task



Details of a task.
_id: string;
name: string;
desc: string;
state: string;
start: number | null; // Start date
deadline: number | null;
assignees: string[]; // Assignee ids
assignedBy: string; // Owner id
followers: string[];
// Ids of the portal users who follow this task if task is shared in
// the client portal
portalFollowers?: string[];
// From 1 to 5. 5 is the highest.
priority: number;
// A score to sort same-priority tasks among themselves.
// Lowest score is shown at the top.
priorityScore: number;
// Project id
group: string;
completedAt: number;
archivedAt?: number | null;
/* none: Task has no steps
* steps: Task has a checklist
* progress: Task has a progress bar
stepType: 'none' | 'steps' | 'progress';
// Check below for definitions of these types
steps?: CheckList | ProgressBar;
customer: {
_id: string,
name: string,
} | null,
createdAt: number;
files: { _id: string }[];
tags: string[];
subtasks: string[];
parent: string | null;
// This property exists if task is created for an incoming mail
// An id is created for the email sender
email?: {
emailUserId: string,
// This property exists if task is created for a support request
// through the Client Portal feature
support?: {
portalUser: string, // Id of the client portal user
private: boolean;
sharedWithCustomer?: boolean;
// Exists if task belongs to a workflow
workflow?: {
id: string,
templateId: string,
isCompleted: boolean,
taskflowId: string
estimatedTime?: number; // Duration in seconds
// If task has custom fields, holds the name and value for each field
customFields?: {[fieldName: string]: string};
// If task is recurrent, shows if this is the newest copy
lastCopy?: boolean;

Task Steps

Tasks can have a checklist or a progress bar to indicate the steps / overall progress.
type ProgressBar = {
completed: number;
total: number;
type CheckList = TaskStep[];
type TaskStep = {
id: string;
name: string;
desc?: string;
assignees: string[]; // Ids of the step assignees
/* Task steps are recursive. They can have sub-steps too.
* If not set, the step has no sub-steps.
* If 'steps', a property named 'steps' holds sub-steps.
* If 'progress', this step object has a property named 'total'.
stepType?: 'steps' | 'progress';
steps?: CheckList;
// If 'stepType' is 'progress', this is a number and indicates the total number
// of steps in the bar. Otherwise, a boolean to indicate completion.
completed: boolean | number;
// Set when 'stepType' is 'progress'
total?: number;


type Recurrence = {
type: 'daily' | 'weekly' | 'monthly';
// Example: Set 3 for task to be copied every 3 days/weeks/months.
period: number;
// New copy is created after task deadline or when task is completed
createWhen: 'after-deadline' | 'completed';
// If true, recurrence continues. Otherwise, it will pause.
active: boolean;
/* 'none': Continues indefinitely
* 'date': Continues until given date in the 'end' parameter.
* 'count': Continues until amount of copies set in 'maxCount' parameter
* are created. The task itself is the first copy. So if, maxCount is 1,
* no copies will be created.
stopCondition: 'none' | 'date' | 'count';
end?: number;
maxCount?: number;
// If 'type' is 'weekly' you can set in which days of the week a copy should
// be created. The list is the days of the week indicating whether that day
// a copy should be created. Starts with Monday.
days?: boolean[];

Default Task States

If task states are not customized for the project, default states are used. These values are translated into the user's language when shown in the UI. These values are:
State Value
Translation in UI
You can check the project object to see whether task states are customized or defaults are being used.

Task Activity

Update and progress actions and messages on tasks create task activities.
type TaskActivity = {
_id: string;
// Id of the user who did the activity
user: string;
// Id of the portal user who created the activity. Exists only when
// activity is created in the Client Portal by a portal user.
portalUser?: string;
// Id of the email sender. Exists when the activity is created due to
// an incoming mail.
emailUser?: string;
| 'post' // A post (comment) on the task
| 'update' // Task is updated
| 'progress' // Task step completed/uncompleted, progress changed
| 'archive' // Task is archived
| 'restore' // Task is restored from the archive
| 'state-change' // Task state is changed
| 'delete'; // Task is deleted
// Holds the info about the update. The shape depends on the 'type'
data?: object;
// If 'type' is 'post', holds the comment content
content?: string;
// If 'type' is 'post', holds the file details
files?: File[] = [];
createdAt: number;
// If activity is a reply to a previous post, keeps the referenced activity id
replyToId?: string;
// Whether the activity (post) is shared with a Client Portal user.
customerCanSee: boolean;
// List of users mentioned in the post
mentions: Mention[];
customFields?: {
fieldName: string;
value: string;
// If a task is created from an incoming email
emailDetails?: EmailDetails;
// If task is created for an incoming email, posts on the task can be sent
// as email. This holds the state of the mail.
mailStatus?: 'not-sent' | 'sending' | 'sent' | 'mail-box-error' | 'error';
type Mention = {
id: string; // User id
name: string; // Text used to mention user in the post
type EmailDetails = {
to: EmailPerson[];
cc: EmailPerson[];
from: EmailPerson;
type EmailPerson = {
name: string;
emailAddress: string;