Overview

The GET Master Tasks endpoint retrieves a list of master tasks from your organization. This endpoint supports advanced search capabilities, filtering options, and cursor-based pagination.

Minimum required role: Employee

Endpoint

GET {baseUrl}/api/v2/master-tasks?access_token={token}

Query Parameters

Parameter	Type	Required	Description
`searchTerm`	string	optional	Search term for filtering tasks (minimum length: 3 characters)
`descriptionSearchEnabled`	boolean	optional	Enable searching within task descriptions (default: false)
`positionIds`	array of int	optional	Filter tasks by specific position IDs
`includeDeleted`	boolean	optional	Include deleted tasks in results (default: false)
`limit`	int	optional	Number of records per page (default: 30)
`cursor`	string	optional	Pagination cursor from previous API response

Search Functionality

Search by Name or Description

Default behavior: The result set is searched by task name by default
Description search: Searching by task description is enabled only when descriptionSearchEnabled is set to true
Search term: Limited to a maximum of 3 characters for optimal performance

Filtering Options

Position Filtering

Use the positionIds parameter to filter tasks assigned to specific positions
Pass an array of position IDs to filter results

Deleted Records

By default, the result set excludes deleted tasks
Set includeDeleted to true to include deleted tasks in the results

Pagination

This endpoint uses cursor-based pagination:

The cursor parameter should contain the cursor value returned in the metadata object from previous API calls
Use the limit parameter to control the number of records returned per page (default: 30)

Permissions

User access to master tasks depends on their role and permissions:

System Role Users

Can view tasks assigned to positions they manage

Custom Role Users

Can view tasks assigned to positions for which they have "Can Update Shift" permissions

Response Example

{
    "status": 1,
    "data": [
        {
            "id": "01j8hctkhb1j37dbm9qhd4shat",
            "companyId": 11,
            "name": "Write Unit Tests",
            "description": "Add test coverage for recently introduced methods to ensure reliability.",
            "favorite": false,
            "color": "",
            "positionIds": [
                367, 890
            ],
            "createdBy": 2,
            "createdAt": "2024-09-24T06:52:13+00:00",
            "updatedBy": 2,
            "updatedAt": "2024-09-26T13:36:49+00:00",
            "deletedBy": null,
            "deletedAt": null
        },
        {
            "id": "01j8hg8s0kww5dx48jzx54qwbe",
            "companyId": 11,
            "name": "Update API Documentation",
            "description": "Sync the docs with the latest API changes and add missing examples.",
            "favorite": false,
            "color": "",
            "positionIds": [
                86098
            ],
            "createdBy": 2,
            "createdAt": "2024-09-24T07:52:23+00:00",
            "updatedBy": null,
            "updatedAt": null,
            "deletedBy": null,
            "deletedAt": null
        }
    ],
    "metadata": {
        "current": null,
        "next": null,
        "count": 2
    },
    "token": "9f5d20ae6c40e58c72bab7776ca23f18f60d0017",
    "error": null
}

Response Fields

Data Object Fields

Field	Type	Description
`id`	string	Unique identifier for the master task
`companyId`	int	ID of the company this task belongs to
`name`	string	Name of the master task
`description`	string	Detailed description of the task
`favorite`	boolean	Whether the task is marked as favorite
`color`	string	Color associated with the task
`positionIds`	array	Array of position IDs this task is assigned to
`createdBy`	int	ID of the user who created the task
`createdAt`	string	Timestamp when the task was created (ISO 8601)
`updatedBy`	int	ID of the user who last updated the task
`updatedAt`	string	Timestamp when the task was last updated (ISO 8601)
`deletedBy`	int	ID of the user who deleted the task (null if not deleted)
`deletedAt`	string	Timestamp when the task was deleted (null if not deleted)

Metadata Object

Field	Type	Description
`current`	string	Current cursor position (null for first page)
`next`	string	Cursor for the next page (null if no more pages)
`count`	int	Total number of tasks returned in this response