This changelog details updates to the endpoints, parameters, and behaviors of the Float API. For general updates on new product features, check out the What’s new page on our website, where new features are announced as they are developed.
New product features may not always be added to the API immediately, allowing time for feature stabilization and further refinement.
Breaking changes and deprecations
Float makes every effort to avoid breaking changes to minimize disruptions and preserve backward compatibility. We will provide advance notice in the rare circumstance that an update would introduce a breaking change. We consider a breaking change a modification to an endpoint’s functionality, including the removal/renaming of an endpoint or field. For example, altering how time off is created or removing a field from a response would both be breaking changes. However, adding a new field to a response would not be considered a breaking change.
Tip: if a new field may disrupt your integration it is possible on most endpoints to specify which fields you want to return in the response using the
fields
parameter e.g./projects?fields=project_id,name,tags
We consider the following changes to be backward-compatible:
- Adding new API endpoints
- Adding new optional request parameters to existing endpoints
- Adding new fields to existing endpoints
- Changing the order of fields in API responses
If we ever must deprecate a field, it will be marked for deprecation in the API reference. The deprecated field will initially remain operational although it may not be supported in the future. This typically happens when another method supersedes it; for example, in the Allocations endpoint, updates to the billable
field have been deprecated in favor of using the Project tasks endpoint.
Upcoming changes
NEW FEATURE: Project Codes
A project_code
field will be available on the Projects endpoint. This feature simplifies integrations with other systems by enabling external project codes or job numbers to be stored and retrieved.
- The
project_code
field accepts a string value (max 32 characters) representing a project identifier from an external system that must be unique across all projects - When enabled in your Team Settings, the field value will be displayed in the UI alongside other project details
- Projects can then be retrieved using the
project_code
field, making it easier to locate specific projects - Updates to projects will continue to require the
project_id
field. Theproject_code
field is optional and does not replace the primary project identifier.
Change history
The timeline below lists all changes to the API or the documentation, from most to least recent.
November 2024
- In Projects clarified the description of
budget_total
andbudget_priority
and how to calculate total budget for Phase and Task level budgets.
NEW FEATURE: managing project statuses including drafts
- A new
status
field has been introduced to the Projects and Phases endpoints, and included on responses. Integer values will be used to represent each project or phase status;0
= Draft,1
= Tentative &2
= Confirmed - Updating a Project status will impact how the Project and all associated entities appear and are used within Float, see the What’s new post for more details
- The draft status value
0
will also be present in the existingstatus
field within Allocations - The
tentative
field will be deprecated but remains functional
October 2024
-
The department definition in the People endpoint has been updated to align with the API. Requests to create or update people can set an existing department by
department_id
. The Departments endpoint must be used to create or update a department. -
The
default_hourly_rate
field type on People, Projects, and Phases was inconsistent in the documentation. This has now been updated tostring
, consistent with the API response. Note that requests on these endpoints accept both decimal numbers and string values
August 2024
NEW FEATURE: set project budget by tasks
API updates now support setting project budgets at the task level.
- Projects now includes the
budget_priority
field to specify budget types - Project tasks now has a
budget
field, allowing a budget value to be set for each task - The
budget_total
description has been updated in Phases
Existing filter parameters can be used to calculate the total project budget across all tasks within a project and its phases.
July 2024
- People endpoint can now use
manager
with theexpand
parameter options to return a list ofaccount_id
managers
May 2024
- Updated the documentation to show that an empty response from the Status endpoint returns a
204
April 2024
-
Updated descriptions for
capacity
,schedule
, andunscheduled
in the Reports documentation - Corrected a field in Project tasks to
task_name
-
Marked the
billable
field on Tasks asdeprecated
; updates to the billable status should now use the Project tasks endpoint - Based on feedback, updated the navigation menus in the documentation for more logical grouping and order
NEW FEATURE: use the Roles endpoint to manage roles
Use the new Roles endpoint to manage roles in Float, including setting a default hourly rate for each role.
- The new Roles endpoint at
/roles
allows listing, creating, updating, and deleting roles - Use the
default_hourly_rate
field to set a default rate for roles, serving as a fallback for individual hourly rates - The
role_id
can then be used in the People endpoint to assign a role, with thejob_title
field reflecting the role’sname
Older changes to the API or documentation are not listed; some small updates and corrections, like typos in descriptions, may also be omitted from this list.