Skip to content

Create one-off task

Endpoint

POST /organizations/{org_id}/tasks

This endpoint creates a new standalone (“one-off”) task that is not part of a process run initiated from a template.

Request

Replace {org_id} with your Organization ID.

Headers

  • Authorization: Bearer {your_access_token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient
  • Content-Type: application/json

Body (JSON)

The request body requires a JSON object defining the new task.

Refer to the #definitions/createStandaloneTaskInput schema in Swagger for all available properties. Key fields include:

  • name (string, required): The title of the task.
  • description (string): A description or instructions for the task.
  • owners (object): Assignees for the task (structure: { "users": [...], "guests": [...], "groups": [...] }).
  • deadline (string): Due date/time in ISO 8601 format.
  • started_at (string): Start date/time in ISO 8601 format.
  • task_type (string): Usually member or guest.
  • separate_task_for_each_assignee (boolean): If true, creates individual tasks for each person in owners.
  • max_assignable (integer): Maximum number of assignees.
  • prevent_guest_comment (boolean).
  • tags (array of strings): Tag IDs to apply.

Minimal Example Body:

{
"name": "Follow up with ACME Corp"
}

More Comprehensive Example Body:

{
"name": "Prepare Q3 Report",
"description": "Gather data and prepare the quarterly report slides.",
"owners": {
"users": [1001, 1002],
"groups": [],
"guests": []
},
"deadline": "2024-07-15T17:00:00Z",
"tags": ["reporting", "finance"]
}

Code Samples

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/tasks`;
const taskData = {
name: "JS One-Off Task: Review Budget",
description: "Review the draft budget spreadsheet.",
owners: {
users: [12345]
},
deadline: "2024-06-10T12:00:00Z"
};
const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');
headers.append('Content-Type', 'application/json');
fetch(apiUrl, {
method: 'POST',
headers: headers,
body: JSON.stringify(taskData)
})
.then(response => {
return response.json().then(data => {
if (!response.ok) {
console.error("Failed to create one-off task:", data);
throw new Error(`HTTP error! status: ${response.status}`);
}
return data;
});
})
.then(data => {
console.log('Successfully created one-off task:');
console.log(JSON.stringify(data, null, 2));
})
.catch(error => {
console.error('Error creating one-off task:', error.message);
});

Response

A successful request returns a 200 OK or 201 Created status code and a JSON object containing the details of the newly created one-off task, including its assigned id.

{
"data": {
"id": "new_one_off_task_id_789",
"increment_id": 1250,
"title": "Python One-Off Task: Plan Meeting",
"description": "Schedule and plan the project kickoff meeting.",
"run_id": null,
"step_id": null,
"status": "active",
"owners": {
"users": [
{ "id": 1001, "full_name": "Bob", "profile_pic": "..." }
],
"guests": [],
"groups": []
},
"deadline": null,
"created_at": "2024-05-20T18:00:00.000Z",
"last_updated": "2024-05-20T18:00:00.000Z"
}
}

Make note of the returned id to manage this task later (get, update, complete, delete).


Tasks > Create a one-off task

One-off tasks in Tallyfy are standalone action items that can be quickly created outside of templates by clicking the Create button, filling in task details like name, assignee, and deadline, then clicking Create Task to generate flexible workflow items for urgent or non-standardized work.

Tasks > Delete task

A DELETE endpoint permanently removes standalone tasks while preserving process-related tasks that can only be deleted through their parent process run deletion.

Tasks > Complete task

An API endpoint marks tasks as complete through POST requests requiring task ID with optional approval status and form field values while supporting both process-based and standalone tasks through different URL structures.

Tasks > Update task

The API endpoint enables updating task properties like title summary deadline assignees and form field values through a PUT request while handling both process-run tasks and standalone one-off tasks with appropriate response validation.