The Float API allows you to import your existing team members so you’re up and running in no time.
In this tutorial we’ll cover:
Importing a person
To add a new person to your team, you need to POST to the /people endpoint. The only mandatory field required to add a person is a name:
POST /v3/people HTTP/1.1
Host: https://api.float.com
{"name": "Sarah-Jane Smith"}
Simple right? You can add lots of other information about a person, such as their email address (useful if you plan to grant them access rights later on). You may also want to include their job title and department when creating the person.
POST /v3/people HTTP/1.1
Host: https://api.float.com
{
"name": "Sarah-Jane Smith",
"email": "sjsmith@float.com",
"job_title": "Designer",
"department_id": 12433
}
The department must already exist to determine the department ID. Available departments are accessible from the /departments end point. Check out our Departments section to add new departments. The People section in the API reference has full details of the available fields you can set for a person.
If the submission is successful, then you will receive a 201 Created response with a representation of the person 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: 552
Content-Type: application/json; charset=UTF-8
{
"people_id": 311815,
"name": "Sarah-Jane Smith",
"email": "sjsmith@float.com",
"job_title": Designer,
"department": {
"department_id": 12433,
"name": "Design"
},
"notes": null,
"avatar_file": null,
"auto_email": -1,
"employee_type": 1,
"work_days_hours": null,
"contractor": 0,
"tags": [],
"start_date": null,
"end_date": null,
"active": 1,
"created": "2017-02-04 13:21:32"
}
Note, at this stage we don’t support assigning account access to your team. Access rights can be managed within the app once your team are imported.
Assigning tags
Tags are helpful for filtering the schedule and reports later on. Tags are all normalized to lowercase. To create a Sketch tag for Sarah-Jane, we can use PATCH message to update her tags property:
PATCH /v3/people/11 HTTP/1.1
Host: https://api.float.com
{
"tags": ["sketch"]
}
As you can see, the tags property is an array, so you can have as many tags as you need for each person.
The API will respond with a 200 OK along with the representation.
Customizing their work hours
By default, the person will inherit the accounts working days and hours. However, if they work a different set of hours, you can specify this too. Let’s say Sarah-Jane only works four hours per day, Monday through Wednesday. You’d specify this as:
PATCH /v3/people/11 HTTP/1.1
Host: https://api.float.com
{
"work_days_hours": [0,4,4,4,0,0,0]
}
Each number represents a day of the week where 0 = Sunday, 1 = Monday and so on. Hence example, [0,4,4,4,0,0,0] has Sarah-Jane available for scheduling on Monday (4), Tuesday (4) and Wednesday (4).
If they’re a contractor, and you’d like to split them out from your employees in the reports, make sure you add this to the PATH message too:
"people_type_id": 2