Table of contents

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 options for status in projects and phases will be introduced soon, keep an eye on the What’s new page on our website for when these will be released.

Existing options:

  • 0 = Draft project
  • 1 = Tentative project
  • 2 = Confirmed project

New Project status options:

  • 3 = Completed project
  • 4 = Canceled project

Change history

The timeline below lists all changes to the API or the documentation, from most to least recent.

June 2025

NEW FEATURE: Cost rates and contracts for people

Following on from the main cost rates release, the API has been updated to enable you to manage cost rates for people and updates to roles.

People cost rates and role changes
Cost rates on people may be updated using cost_rate and effective_date fields. It’s also possible to manage role changes using the role_id field, which is likewise controlled by the effective_date field.

  • To add a new custom cost rate and apply a role change from an effective date, follow this notation:

    PATCH /v3/people/123456?expand=contracts HTTP/1.1
{
    "cost_rate": 150,
    "role_id": 4944,
    "effective_date": "2025-06-12"	
}
  • To overwrite a cost rate or role change, supply the same effective_date field.

  • To delete a cost rate or role change, use this notation:

    PATCH /v3/people/123456?expand=contracts HTTP/1.1
{
    "contracts": {
        "del": [
            "2025-06-12"
        ]
    }
}

Role cost rates
Cost rates on roles may be updated using the cost_rate_history field. The cost_rate_history field can be expanded in the response to see all cost rate changes.

  • To add a new cost rate supply a date and the cost rate, using this notation:
PATCH /v3/roles/1234?expand=cost_rate_history HTTP/1.1
{
  "cost_rate_history": {
    "add": [
      { "rate": 150,
        "effective_date": "2025-06-01" }
    ]
  }
}
  • To delete a cost rate, follow this notation:
  PATCH /v3/roles/1234?expand=cost_rate_history HTTP/1.1
 {
  "cost_rate_history": {
    "del": ["2025-06-10"]
  }
}

Cost rate hierarchy
As per the cost rates documentation, any person-level cost rates will take precedence over the role-level cost rates. It is possible to set a person cost rate to null with an effective date to enable role-level costs to be inherited.

Contracts
To help you understand how an effective cost is being determined, we’re introducing the concept of contracts on people. Changes to a person’s cost rate, updating their role, or changing a role-level cost rate may affect that person’s effective cost rate.

Contracts can be expanded in the response from people in a contracts array.

  • The following fields make up a person’s contract:
    • effective_date: the date the contract starts; defaults to the person’s start_date.
    • role_id: the ID of the role the contract is for (null if the person has no role).
    • role_name: the name of the role the contract is for (null if the person has no role).
    • cost_rate: the effective cost rate for the contract (null if there are no cost rates).
    • cost_rate_from: the entity that the cost rate is derived from, either role or person (null if there are no cost rates).
  • The contract will be automatically calculated from person or role cost rate changes or role changes on the person.
  • To view a person’s contract history, use the expand parameter with the value contracts.
GET /v3/people/1234?expand=contracts HTTP/1.1
 {
  "people_id": 1234,
  "contracts": [
    {
      "effective_date": "2023-01-01",
      "role_id": 3456,
      "role_name": "Senior developer",
      "cost_rate": "150.0000",
      "cost_rate_from": "role"
    }
  ]
}

Also note

  • Cost rates are independent of project data; however, when they’re combined with project budget data, you can calculate project profitability or cost against roles.
  • Cost rates can be sensitive data and the API key can retrieve all cost rates in the system. Ensure that this privilege is managed appropriately.

Other improvements

  • Fields exposed using the expand parameter on the People endpoint; account, managers and contracts are now documented in the people model and labelled in the description.
  • Added missing field task_meta_id to definitions in allocations and logged-time endpoints.
  • Added the query parameter status to projects to filter on the status of a project.

April 2025

  • A field reference_date was missing from the logged-time endpoint. This field can be used to control log time suggestions in the UI along with the task_id field. Including a reference_date and task_id in the logged time payload will suppress any log time suggestions associated with the scheduled allocations on the specified date.

  • We were made aware when not using the locked logged time feature the Logged-time endpoint returns the locked field as false when our documentation states it should return an integer 1|0. To fix this we will start returning 0 in all cases where the lock logged time is not locked (including if the feature is disabled). If the logged time entry is locked then the field will continue to return 1.

February 2025

  • The descriptions for the start_date and end_date fields on projects and phases have been improved to reflect that these dates can be set using create and update operations, and the response values may be calculated based on the dates of the associated phases, milestones, allocations, and logged time.

December 2024

NEW FEATURE: Project codes

A project_code field is now 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
  • 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.
  • Coming soon: The Float UI will be updated so the field value will be displayed in the UI alongside other project details.

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.