Table of contents

Scheduling your team

Using the Float API you can allocate people to project work, log time and manage their time offs.

In this tutorial we’ll cover:

Creating an allocation using tasks

This version of the API make use of the /tasks endpoint, this endpoint is named this way for historical reasons. For the purpose of this tutorial you can think of a task_id being the same as an Allocation in the Float app.

To create an allocation, you’ll need to know the IDs for people and projects. See People and Project sections for help on identifying these.

Adding an allocation for someone requires the following mandatory values:

  • Person
  • Project
  • Start Date
  • End Date
  • Hours per day

An example of this may be:

POST /v3/tasks HTTP/1.1
Host: https://api.float.com

{
    "people_id": 11,
    "project_id": 2,
    "start_date": "2023-05-01",
    "end_date": "2023-05-15",
    "hours": 4
}

This will allocate the chosen person to the project, for the set number of hours per day, over the chosen timeframe.

To better categorise the work it’s useful to allocate a project task, this can be done by specifying the name of the project task.

"name": "Concepting"

The API will attempt to match this name to existing project tasks that can be managed in the UI, this can also include project tasks that are non-billable, depending on the project settings.

As you are accessing the API with high privileges, this will always create a new project task if one with the same name does not exist in the project.

If the submission is successful, then you will receive a 201 Created response with a representation of the task that you have just created:

HTTP/1.1 201 Created
{
  "task_id": 1000001613,
  "project_id": 101162,
  "start_date": "2023-05-01",
  "end_date": "2023-05-15",
  "start_time": null,
  "hours": 4,
  "people_id": 46677,
  "status": 2,
  "billable": 1,
  "name": "Concepting",
  "notes": null,
  "repeat_state": null,
  "repeat_end_date": null,
  "created_by": 172717,
  "modified_by": null,
  "created": "2023-04-27 08:41:08",
  "modified": null
}

Updating an allocation

To update an allocation (task_id), Send a PATCH request to the /tasks endpoint. For instance, you could add details of the work with the notes field and also set the allocation to the tentative (status = 1) until the work is ready to start, when you would change it back to confirmed (status = 2).

PATCH /v3/tasks/1000001613 HTTP/1.1
Host: https://api.float.com

{
    "notes": "Work on icon concepts before the homepage",
    "status": 1
}

Repeating allocations

Some project tasks need to repeat on a regular weekly, fornightly or monthly basis. Float supports this with the repeat_state and repeat_end properties of the task. So, to make our task repeat every week until the 22 November 2023, we update it like this:

PATCH /v3/tasks/56 HTTP/1.1
Host: https://api.float.com

{
    "repeat_state": 1,
    "repeat_end_date": "2023-11-22"
}

The repeat_state property is a number which can be set to 0 (default) if the task does not repeat, 1 if it needs to happen every week, 2 if it’s monthly and 3 if it’s every 2 weeks.

Linking allocations

Allocations in the same project and phase may be linked so that updating the start date of a single allocation in the UI updates all linked items whilst maintaining the date offset between them.

Once these links are set it is not possible to update the dates on allocations using the API; it is only possible to update them using the UI. If a range of allocations are linked together, as noted by the fields below, they may be unlinked by setting the fields to null values.

Linked allocations use a root_task_id to determine the first allocation in the chain; all child allocations then contain a parent_task_id value, whereas the first parent (also the root) will have a null value.

Example of three allocations linked together

{
  "task_id": 760283083,
  "root_task_id": 760283079,    -- references the root allocation
  "parent_task_id": 760283081,  -- references the direct parent
  "project_id": 8760362,
  "created": "2023-11-15 03:16:37.363"
},
{
  "task_id": 760283081,
  "root_task_id": 760283079,    -- references the root allocation
  "parent_task_id": 760283079,  -- references the direct parent (also the root allocation)
  "project_id": 8760362,
  "created": "2023-11-15 03:16:34.566"
},
{
  "task_id": 760283079,
  "root_task_id": 760283079,    -- root allocation in the linked chain
  "parent_task_id": null,       -- no parent as this is the root allocation
  "project_id": 8760362,
  "created": "2023-11-15 03:16:28.255"
}

To create links use the update operation on the /tasks/:id endpoint. After identifying the proposed root allocation by task_id, links must be made from the child allocations. Links cannot be made during a create operation.

Update an existing child allocation by task_id to reference the root (first allocation) and its direct parent allocation:

  PATCH /v3/tasks/760283081 HTTP/1.1
  Host: https://api.float.com

  {
    "root_task_id": 760283079,
    "parent_task_id": 760283079,
  }

The root and the parent IDs must be set at the same time.

Errors are returned if the date of the child is earlier than the parent or the root allocation or if the allocations are not in the same project or phase.

Log time

To log time, you’ll need to know the IDs for people and projects. See People and Project sections for help on identifying these.

Time logging requires the following mandatory values:

  • Person
  • Project
  • Date
  • Hours per day

An example of this may be:

POST /v3/logged-time HTTP/1.1
Host: https://api.float.com

{
    "people_id": 11,
    "project_id": 2,
    "date": "2023-05-15",
    "hours": 2
}

Updating logged time works by using a PATCH request (note: this endpoint uses a hexadecimal ID).

For example, to update the time and add a detailed note.

PATCH /v3/logged-time/6407caee371c7128e68f0f0c HTTP/1.1
Host: https://api.float.com

{
  "hours": 2.5
  "note": "Completed first draft of icon concepts"
}

Adding a time off

To assign a time off, you’ll need to know the IDs for people and projects. See People and Time Off Types sections for help on identifying these.

Adding a time off requires the following mandatory values:

  • Person
  • Time off type
  • Start Date
  • End Date
  • Hours per day (Not required when a full day)

An example of this may be:

POST /v3/timeoffs HTTP/1.1
Host: https://api.float.com

{
    "people_id": 11,
    "timeoff_type_id": 2,
    "start_date": "2023-06-01",
    "end_date": "2023-06-01",
    "hours": 4
}

Update time off by using a PATCH request.

For example, changing the time off from 4 hours to an all day request. This will overwrite the hours to null and result in the time off being displayed as an all day activity.

PATCH /v3/timeoffs/2637 HTTP/1.1
Host: https://api.float.com

{
	 "full_day": 1
}

Note: Scheduled allocations and logged time can be created over the API when full-day time off tasks exists on the same date, the task will still be saved in the database but it will not be visible on the UI. However, if there are already scheduled or log tasks present and full-day time off task is added on the same day then those tasks will be deleted. Creating a part-time time off task will not delete already existing tasks.