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, department, and a people code to hold their ID from another system 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,
"people_code": "EMP-123456"
}
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",
"people_code": "EMP-123456",
"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.
Adding identifiers with people codes
The people_code field is a unique identifier that can accept a 32 character string. It is the place to store an ID a person already has in another system, such as an Employee ID from your HR or payroll platform, so you can match records between that system and Float without maintaining a separate mapping of your own. Duplicate people codes are not permitted, so if the code is already used by another person in your instance the request will return a 422 Error response. Comparison is case-insensitive, meaning EMP-123456 and emp-123456 are treated as the same code.
The code can be set when you create a person, or added later:
PATCH /v3/people/11 HTTP/1.1
Host: https://api.float.com
{
"people_code": "EMP-123456"
}
The people_code field can also be used as a filter on a list people request. Because codes are unique, the filter always returns a single person, which is a convenient way to look up the internal people_id you need for other API operations:
GET /v3/people?people_code=EMP-123456&fields=people_id HTTP/1.1
Host: https://api.float.com
Remember to URL encode the code if it contains reserved characters, e.g. emp/123 becomes emp%2F123.
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