Retrieve staff¶
Introduction¶
The staff API allows you to retrieve data about staff ("personal", "anställda").
https://personalkollen.se/api/staffs/ provides a list of all available staff.
Individual staff objects can be retrieved at https://personalkollen.se/api/staffs/<staff-id>/
Example request and response¶
Here is a basic example using httpie client:
http GET https://personalkollen.se/api/staffs/ "Authorization: Token demo" --verbose
GET /api/staffs/ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Token demo
Connection: keep-alive
Host: personalkollen.se
User-Agent: HTTPie/0.9.9
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 332
Content-Type: application/json
Date: Sun, 26 Aug 2018 11:01:09 GMT
Expires: Sun, 26 Aug 2018 11:01:09 GMT
Vary: Cookie
X-Frame-Options: SAMEORIGIN
{
"next": null,
"previous": null,
"results": [
{
"url": "https://personalkollen.se/api/staffs/4132/",
"id": 4132,
"email": "anders@andersson.com",
"employment_number": 123,
"first_name": "Anders",
"last_name": "Andersson",
"personal_identification_number": "199012241234",
"confirmed": true,
"mobile_phone": "+46123456789",
"group": "https://personalkollen.se/api/staff-groups/2342/",
"group_name": "Hovmästare",
"registration_date": "2018-07-30T13:23:54.635862+02:00",
"company": "https://personalkollen.se/api/companies/678/",
"workplace": "https://personalkollen.se/api/workplaces/123/",
"bank_account": "12345678",
"clearing_number": "1234",
"tax_table": null,
"tax_percent": "30.12",
"default_cost_group": 1337
}
]
}
Result description¶
The actual data can be found as a list of objects in the results field. Each
object contains the fields listed below.
url¶
This value is a unique resource link to this particular staff.
id¶
This value is an internal unique identifier to this particular staff.
bank_account¶
Bank account number. This value might be null.
clearing_number¶
Bank clearing number. This value might be null.
tax_table¶
The Swedish "Skattetabell". If tax_percent has a value then this field's value is null. This value might be null.
tax_percent¶
String with a two decimal number, for example "30.12". If tax_table has a value then this field's value is null. This value might be null.
default_cost_group¶
Integer representing a Staff's default cost group for non-scheduled logged times. This value might be null.
employment_number¶
User-editable number that many employers use to identify their employees. These should not be used as unique identifiers as they can be changed.
first_name¶
First name of the staff.
last_name¶
Last name of the staff.
personal_identification_number¶
12-digit representation of the Personal identification number for this staff. Age and gender can be calculated from this.
Note that different staff objects might have the same personal identification number. This is because a staff object belongs to a single company, and the same physical person might work on multiple companies. You do not have to think about this unless you are fetching data from multiple API keys/companies.
If the staff does not have a swedish personal identification number, this field might instead contains a so-called coordination number ("samordningsnummer").
In cases where the staff does not have a personal identification number nor coordination-number, this field will instead contain an 11-digit identification number called "födelsetid". This consists of the birth date followed by three arbitrary numbers, and is basically the same format as the personal identification number without the last digit.
confirmed¶
Boolean, true if chief has confirmed the registration of the staff.
group¶
Unique identifier of the staff group that this staff belongs to.
group_name¶
The name of the staff group that this staff belongs to.
registration_date¶
Timestamp that describes when the staff was registred in Personalkollen.
employments¶
This attribute is only returned if you passed query parameter with_employments with a truthy value.
Each employment will have the following attributes start, end, salary_type, hourly_salary, monthly_salary, fixed_cost_per_day and service_grade. For example:
"employments": [
{
"start": "2023-05-01",
"end": "2023-09-30",
"salary_type": "hourly_salary",
"hourly_salary": "123.00",
"monthly_salary": null,
"fixed_cost_per_day": "0.00",
"service_grade": "100.0"
},
{
"start": "2023-10-01",
"end": "2023-10-31",
"salary_type": "monthly_salary",
"hourly_salary": null,
"monthly_salary": "25000.00",
"fixed_cost_per_day": "1270.88",
"service_grade": "50.0"
},
{
"start": "2019-11-01",
"end": null,
"salary_type": null,
"hourly_salary": null,
"monthly_salary": null,
"fixed_cost_per_day": "0.00",
"service_grade": null
},
],
salary_type is "hourly_salary", "monthly_salary" or null.
If salary_type is null then both hourly_salary and monthly_salary will be null.
The fixed_cost_per_day field is always present but will only be non-zero if manually activated for a staff member with a monthly salary. When enabled, the cost in logged time will show as 0, and instead, this field will reflect a fixed daily cost. This value represents the monthly salary distributed evenly across all days of the year, meaning it remains constant regardless of whether the staff member is working or not.
workplace¶
URL of the workplace which the staff belongs to. A workplace represents one physical unit, such as a restaurant. Some companies only have a single workplace, other companies have multiple workplaces. This value might be null.
company¶
Unique identifier of the company that the staff belongs to. This will always have the same value for all objects as long as the same API secret is used, since secrets belongs to a single company.
Filters/parameters¶
You may use the following query string/GET parameters to select a specific set of results.
with_employments=BOOLEAN¶
Pass query parameter with_employments=true if you want to include employment details in the result set. See "employments" in "Result description" for more information.
workplace=URL¶
Retrieve only staffs which belong to a certain workplace URL, for example https://personalkollen.se/api/workplaces/123/. Note that workplace might be null and that there is currently no way to only retrieve staffs with null-values.
Filtering on employment date¶
It's possible to retrieve staffs that is employed between two dates
(including edges). The start_date and end_date are used for this,
and both parameters must be given. The dates should be in ISO8601 format,
for example 2018-08-31. This can for example be used to get staffs
with a currently active employment