API changelog

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. The project_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 and budget_priorityand 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 existing status 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 to string, 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 the expand parameter options to return a list of account_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, and unscheduled in the Reports documentation

  • Corrected a field in Project tasks to task_name
  • Marked the billable field on Tasks as deprecated; 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 the job_title field reflecting the role’s name

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.