CREATE Master Tasks

Create a new master task for your company. Master tasks can be assigned to specific positions and help standardize recurring work across your organization.

API Endpoint

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

Permissions

API Access

Access Level: Public API endpoint
Minimum Role: Employee

Authorization Requirements

Users must have one of the following permissions for all requested positions:

System roles - can create task on positions they manage

Custom roles - can create tasks on positions for which they have shift edit permissions

Users have to have the above permissions for all requested positions

Parameters

Request Body

Parameter	Type	Required	Description
`name`	string	✅ Required	Name of the master task
`positionIds`	array of integers	✅ Required	Array of position IDs where this task can be assigned
`description`	string	❌ Optional	Detailed description of the task
`color`	string	❌ Optional	Hex color code for the task (e.g., "#B0BFC5")

Request Example

{
    "name": "Write API documentation",
    "positionIds": [62580]
}

Response

Success Response

Status Code: 200 OK

{
    "status": 1,
    "data": {
        "id": "01k6d0xksd04t0ztrhbzqettb0",
        "companyId": 11,
        "name": "Write API documentation",
        "description": "",
        "favorite": false,
        "color": "#B0BFC5",
        "positionIds": [
            62580
        ],
        "createdBy": 39737,
        "createdAt": "2025-09-30T09:58:05+00:00",
        "updatedBy": null,
        "updatedAt": null,
        "deletedBy": null,
        "deletedAt": null
    },
    "metadata": [],
    "token": "token",
    "error": null
}

Response Fields

Field	Type	Description
`id`	string	Unique identifier for the master task
`companyId`	integer	ID of the company this task belongs to
`name`	string	Name of the master task
`description`	string	Task description (empty string if not provided)
`favorite`	boolean	Whether this task is marked as favorite
`color`	string	Hex color code for the task
`positionIds`	array	Array of position IDs associated with this task
`createdBy`	integer	User ID of the task creator
`createdAt`	string	ISO 8601 timestamp of creation
`updatedBy`	integer	User ID of last updater (null if never updated)
`updatedAt`	string	ISO 8601 timestamp of last update (null if never updated)
`deletedBy`	integer	User ID who deleted the task (null if not deleted)
`deletedAt`	string	ISO 8601 timestamp of deletion (null if not deleted)

Error Responses

Common error responses include:

401 Unauthorized: Invalid or missing access token
403 Forbidden: User doesn't have permission for all requested positions
400 Bad Request: Invalid parameters or missing required fields

Common Error Scenarios

Missing Position Permissions: If you don't have the required permissions for all positions in positionIds, you'll receive a 403 Forbidden response.

Invalid Position IDs: If any position ID in the array doesn't exist or is inaccessible, the request will fail.

Missing Required Fields: Both name and positionIds must be provided in the request body.

Usage Notes

Master tasks created through this API can be used to standardize work across your organization
Tasks will inherit the default color #B0BFC5 if no color is specified
The favorite field is automatically set to false for newly created tasks
Position IDs must be valid and accessible to your user account