What’s New with the 10,000ft API

By now you probably know about our new project planning experience — a collection of new features to help you manage your people and projects in greater detail. These new features are ideal for zooming in on details about your work, including work assignments, subtasks, and status updates on those assignments.

This is all very exciting, but you may be wondering:

“How do these new features affect our API integrations with 10,000ft?”

If you’re already using an integration with 10,000ft, nothing really changes. Your integration(s) will stay intact. But we did create three new API endpoints for added functionality.

Whether you’re just starting to explore what’s possible with the API, or your thinking about new ways to integrate 10,000ft with other tools, these three new endpoints are definitely worth knowing about.

You can find detailed information about all of our API integrations, including these, in our API documentation.

Assignment Subtask Counts

The first new addition is the Subtasks Counts endpoint under Assignments (when we say ‘assignments’ here, we’re talking about Work Items on a project’s Worklist).

Endpoint: /api/v1/projects/<project_id>/assignments?fields=subtasks_counts

The project ID and the assignments part of this endpoint aren’t new. What’s changed here is the last part of the endpoint: subtask_counts.

So, what does it do?

GET /api/v1/projects/<project_id> gives you project data.

GET /api/v1/projects/<project_id>/assignments gives you all of the assignment data for that project. So far, this is all the same data that you would have gotten before about a given projects’ assignments.

Adding the last part to GET /api/v1/projects/<project_id>/assignments?fields=subtasks_counts returns the number of completed subtasks and total subtasks for the project assignment. As noted in the documentation, this is a view-only endpoint and is only accessible with a GET request.

Here’s an example JSON Response:

{
  "data": [
    {
        "id": 12345,
        "allocation_mode": "percent",
        "percent": 1,
        "user_id": null,
        "assignable_id": 123,
        "ends_at": "2018-06-27",
        "starts_at": "2018-06-21",
        "bill_rate": null,
        "bill_rate_id": null,
        "repetition_id": null,
        "created_at": "2018-06-21T23:01:09Z",
        "updated_at": "2018-06-21T23:01:09Z",
        "all_day_assignment": true,
        "resource_request_id": null,
        "status": null,
        "status_option_id": 1,
        "description": "Build wireframes",
        "note": null,
        "subtask_counts": {
            "completed": 5,
            "total": 10
        }
    },
    ...
}

We use this endpoint when we display the Tasklist icons in each assignment row of the Worklist. This is especially helpful if you want to see how many completed and remaining subtasks are attached to your project assignments.

Subtasks

The entire Subtasks endpoint is new, and gives you the ability to manage subtask information for assignments in a variety of ways.

Endpoint: /api/v1/projects/<project_id>/assignments/<assignment_id>/subtasks

As mentioned above, subtasks correspond to the Tasklist of each assignment row on the Worklist.

There are a few different ways to use the subtasks endpoint. Using different calls, you can:

  • Create a subtask using specific params
  • List subtasks
  • Show a single subtask
  • Update a subtask, or
  • Delete a subtask

Here’s an example of the POST parameters you can set to create a subtask on a POST request:

POST {
 "description": "Create wireframe",
 "completed": true,
}

This endpoint may be helpful if you’re already pulling all of your assignment data into another program, and/or putting it into a report every week. Using this new subtasks endpoint, you can now add all the subtasks for those assignments.

Status Options

The new Status Options endpoint is similar to subtasks as far as functionality goes. You can use this new API endpoint to manage the status options for your organization.

Endpoint: /api/v1/status_options

Status options are required to set the status_option_id on assignments. Again, this corresponds to the work status in the project Worklist.

Like the subtasks endpoint, you can do a variety of things with the status options endpoint:

  • Create a status option
  • List status options (with or without deleted status options)
  • Show a single status option
  • Update a status option, or
  • Delete a status option

When creating a status option, there are several required params:

  • Color: one of the valid colors listed in the documentation
  • Label: string
  • Stage: one of the valid stages (planned, in_progress, or done)
  • Order: a float number used for sorting options within UI menus

Here’s an example of the POST parameters you can set to create a status option on a POST request:

POST {
 "color": "green_bright",
 "label": "On Track",
 "stage": "in_progress",
 "order": 100.0
}

This status options endpoint boosts the functionality of the previously mentioned assignment subtasks count endpoint by displaying the status of each assignment. For example, using these two endpoints, you could pull a list of all the subtasks under any given project and quickly identify how many subtasks are done, and how many are at risk.

Ready to Get Started?

Ready to dig into these new integration possibilities? You can find all the technical information in our API documentation.

If you have any questions, we’re happy to help. Drop us a line at support@10000ft.com.

Anton Rius
October 4th, 2018
Receive expert insights, tips + tricks every month
RELATED ARTICLES
Get our newsletter