The Float API allows you to import and manage your projects to save you a whole lot of double entry.
In this tutorial we’ll cover:
Importing a project
Note: If you use an existing service, such as Basecamp or Asana, you may also want to consider using Zapier to keep your projects in sync with Float.
To add a project, you’ll just need to give it a name. It’s the only mandatory field we require. For example:
POST /v3/projects HTTP/1.1
Host: https://api.float.com
{"name": "Project One"}
If the submission is successful, then you will receive a 201 Created response with a representation of the project you just created:
HTTP/1.1 201 Created
Date: Thu, 01 Dec 2016 17:08:17 GMT
Location: https://api.float.com/v3/people/6
Content-Length: 303
Content-Type: application/json; charset=UTF-8
{
"project_id": 1027707,
"name": "Project One",
"project_code": null,
"client_id": null,
"color": "68ddfd",
"notes": "",
"tags": [],
"budget_type": 0,
"budget_total": null,
"budget_per_phase": 0,
"budget_priority": 0,
"default_hourly_rate": null,
"non_billable": 0,
"tentative": 0,
"status": 2,
"locked_task_list": 1,
"active": 1,
"project_manager": 80851,
"all_pms_schedule": 0,
"created": "2024-10-24 05:08:26",
"modified": "2024-10-24 05:09:04",
"start_date": null,
"end_date": null
}
The Projects section in the API reference has full details of the available fields you can set for a project.
Selecting a project color and a client
Each project has an associated color to make it easy to identify associated items on the schedule. By default, this is is blue. You can specify a custom color using hex codes (not sure which hex code to use? This site makes it easy: https://htmlcolorcodes.com). Here’s an example of a red color:
"color": "FF2D00",
You can group the project with a client assuming you know the client ID (if you’re not sure how to find this, check out our Clients section). Identify the client ID and assign it to the project, e.g.
"client_id": "212",
Putting these together, you can update your project using a PATCH request:
PATCH /v3/projects/1234 HTTP/1.1
Host: https://api.float.com
{
"color": "FF2D00",
"client_id": "212"
}
The API will respond with a 200 OK along with the representation.
Adding identifiers with project codes and tags
The project_code field is a unique identifier that can accept a 32 character string, ideal for job numbers or IDs generated by other systems. Duplicate project codes are not permitted so if one is found on another project in your instance the request will return a 422 Error response.
Like people, projects can also have tags, useful for other identifiers that you may want to search for later. Project tags are lowercase and may have spaces in them.
Both of these fields can be added:
PATCH /v3/projects/1234 HTTP/1.1
Host: https://api.float.com
{
"project_code": "job-12345/11",
"tags": ["iphone app", "internal project"]
}
Both project codes and tags can be used as filters to help narrow the results from a list projects request. The project_code filter will always return a single project allowing you to obtain the internal project_id of that project that can be used in other API operations.
GET /v3/projects?project_code=job-12345%2F11&fields=project_id HTTP/1.1
Host: https://api.float.com
Assigning team members
Team members are assigned to a project once you start scheduling project tasks to them, however you can also assign them to projects ahead of time using the project_team attribute when creating the project. For each person you want to add you need to know their people_id and then you can add them like this:
POST /v3/projects HTTP/1.1
Host: https://api.float.com
{
"name": "Project Two",
"project_team": ["12345","12346","12534"]
}
If you’d like to view the team members assigned to a team, you can do so like this:
GET /v3/projects/12345?expand=project_team HTTP/1.1
Host: https://api.float.com
Assigning a project owner
Each project is assigned a project owner, using the project_manager field. When a project is added via the API, by default the project owner is the account owner. You can modify this by specifying the account ID.
You can retrieve the account ID from the /accounts endpoint like this:
GET /v3/accounts HTTP/1.1
Host: https://api.float.com
The response is a list of accounts:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"account_id": 63686,
"name": "John Smith",
"email": "john@float.com",
"account_type": 1,
"department_filter_id": 11924,
"active": 1,
"created": "2023-09-09 01:21:44",
"modified": "2023-12-15 21:24:44"
},
{
"account_id": 63691,
"name": "Donna Noble",
"email": "donna@float.com",
"account_type": 1,
"department_filter_id": 0,
"active": 1,
"created": "2017-09-10 04:21:02",
"modified": "2017-11-14 08:01:25"
}
]
We want to assign Donna as the project manager, so we update the project like this:
PATCH /v3/projects/1234 HTTP/1.1
Host: https://api.float.com
{
"project_manager": 63691
}
If you’d like any project manager to have access to edit the project mark it as all_pms_schedule:
PATCH /v3/projects/1234 HTTP/1.1
Host: https://api.float.com
{
"all_pms_schedule": "1"
}
Adding related project tasks, phases and milestones
Once the project is created you can use the project_id to add other associated entities like tasks, phases and milestones.
Adding task name defaults
Adding task names to your project enables your team to select from these when assigning tasks in the schedule. It also makes reporting on these tasks more consistent. For example, if you know the project has design, development and testing tasks, you can add these by using the /project_tasks endpoint, this is the example for the “Design” task.
POST /v3/project_tasks HTTP/1.1
Host: https://api.float.com
{
"project_id": 123,
"task_names": "Design"
}
Adding phases and milestones
Phases are used to break up the project into smaller chunks, budgets may be added at the phase level which can be calculated to determine the overall project budget. Milestones and tasks maybe also be set at the phase level which allows for tailoring the UI when creating schedules and logging time.
Phases require the project_id and name and the dates of the phase, other fields may be added as outlined in the /phases endpoint.
POST /v3/phases HTTP/1.1
Host: https://api.float.com
{
"project_id": 123,
"name": "Discovery phase",
"start_date": "2024-11-15",
"end_date": "2025-01-10",
"status": 1,
"notes": "Covers all aspects of discovery with the client, this is a billable",
"non_billable": 0,
"color": null
}
To add a milestone for the project or phase, such as an important launch date, you can use the create /milestones endpoint. Let’s say you wanted to add a deadline for a website launch on December 1. You would specify:
POST /v3/milestones HTTP/1.1
Host: https://api.float.com
{
"project_id": 123,
"name": "Launch website",
"date": "2024-12-01"
}