API Documentation
The TASKUMS API allows you to create tools for use outside of the Taskums website. For example, you could create a widget for a CMS to display the progress of your projects, develop a mobile app for managing projects on the go, or anything else that uses the web and fits your needs.
The API is simple and straightforward. Below is the complete documentation and all you need for reference while creating your applications. Please read the documentation from the beginning the first time to get a handle on the process. After that, you will probably only need use specific sections of this page as a reference.
Table of Contents
Introduction
The API can be used to perform many functions on your account. The ability to manage your projects from off the website will enhance your experience tremendously if done right. To ensure the task is done right, the API has a strict format that you can read about in the next section.
In addition, the API can also respond in multiple formats like xml, html, text and json. While this is not the final response list, it ensures that you can find at least one way to use the system.
Formatting
All calls to the API must follow this format:
Notice the sections in bold: object, function and parameters. With these three parts, you can do most tasks that can be done on taskums.com. The "object" is the item type to act on, the "function" is what you want to do on the "object" and "parameters" are the support data needed to carry out the function. Each of these has its own section in the documentation to further explain them in detail, so don't worry if that sounded like tech speak.
Here is an example on how to mark a task as complete. Note: the authentication parameters have been removed for simplicity of the example.
Objects
- project
A project holds all the tasks to be completed. Allows most non-task specific functions. - task
The tasks within a project. Allows most functions. - email
The emails sent to individuals with instructions to complete tasks. Allows a few basic functions.
Functions
Not all objects support all functions, but if it seems logical, than you can probably do it.
Projects
- add
Creates a project. Requires a "name" parameter and "template_id" if you are using one. - list
Returns a list of all the projects in your account. - start
Starts a project. The "project_id" parameter of the project is required. This will send emails for the first level of tasks. - delete
Deletes a project. The "project_id" parameter of the project is required. - view
View a project's information. The "project_id" parameter of the project is required. - view_all
View all active project's information. - count
Count the number of active projects. - count_tasks
Count the number of tasks in a specific project. The "project_id" parameter of the project is required. - progress
Retrieve the progress percentage for a specific project. The "project_id" parameter of the project is required. - list_tasks
List the tasks in a specific project. The "project_id" parameter of the project is required. - save_template
Save a template based on a project. The "project_id" and "name" parameters are required. - view_template
View an existing template's information. The "template_id" parameter is required. - delete_template
Delete an existing template. The "template_id" parameter is required. - time
View the budgeted and actual time calculations for a specific project. The "project_id" parameter of the project is required.
Tasks
- add
Creates a task. Requires "email", "days", "instructions" and "project_id" parameters. Optional, provide "parent" parameter to make new task child of existing task where parent is the task_id of the parent task. - delete
Deletes a task. The "task_id" parameter of the project is required. - edit
Edit a task. The "task_id" parameter is the only required parameter. You may edit any field provided in the add task function. - complete
Complete a task. The "task_id" parameter of the task is required. - view
View a task's information. The "task_id" parameter of the task is required. - view_children
Retrieve the directly subordinate tasks to a parent task. The "task_id" parameter of the parent task is required. - view_all_children
Retrieve all of the subordinate tasks to a parent task. The "task_id" parameter of the parent task is required. - list
Returns a list of all the tasks for a specific project. The "project_id" parameter of the project is required. - list_children
Retrieve a list of all the subordinate tasks to the parent task. The "task_id" parameter of the parent task is required. Similar to view_children, except a specific list format is provided. - latest_completed
Retrieve the most recent completed tasks. The "project_id" parameter is optional if you wish to restrict the results to one project, otherwise, all projects will be used. You can also supply an optional "limit" parameter to limit the results. Limit has a default/max value of 10. - count
Count the number of tasks for a specific project. The "project_id" parameter of the project is required. - count_children
Count the number of tasks that are directly subordinate to a specific task. Only counts tasks one level deep below a parent task. The "task_id" parameter of the parent task is required. - count_all_children
Count the total number of tasks that are subordinate to a specific task. Count all tasks, multiple levels deep below a parent task. The "task_id" parameter of the parent task is required. - view_parent
Retrieve the parent task for a given subordinate task. The "task_id" parameter of the child task is required. - view_all_parents
Retrieve all parent tasks for a given subordinate task. The "task_id" parameter of the child task is required. The data set returned will include the subordinate task as the final item in the list.
Emails
- count
Count the number of emails sent. The "project_id" parameter is optional. If used, function will return the total number of emails for a project, otherwise, the email count for your account will be returned.
Parameters
These are special parameters that are needed for all functions.
- apikey
Your account API Key is your secret code to modify and access objects in your account. You can find this in your My Account page while logged into your account as the account owner on Taskums. Keep it secret. - mode
php, xml, html, text and json are all potential values for mode. Your results will be returned in this format. With php mode, you must run the unserialize function on the results to convert the serialized string back into a php array.
Putting it all Together
So, you're now an expert in the Taskums API. What's next? Login to your account and click on the My Account link in the navigation menu. Find your API Key on this page. You will need this to make your api calls. Keep it locked up in a safe place, as it pertains only to your account and can be used to alter your project information.
Here are some common examples in their complete form for your use. Replace the parameter values in bold with your account details.