Introduction
Welcome to the hakuna API. You can use our API to:
- Start/stop a timer
- Manage time entries
- Get a list of absences
- Retrieve key metrics (such as overtime)
- Get an overview of your organization (e.g. who is absent, who has a timer running)
Making Requests
GET /api/v1/ping HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
curl 'https://app.hakuna.ch/api/v1/ping' \
-H 'X-Auth-Token: your-token'
All API responses are delivered in the
json
format:
{
"pong": "2016-11-08T13:38:11.086+00:00"
}
Requirements for making requests:
- Add
api
and the API versionv1
in the URL - Provide your authentication token
X-Auth-Token
as a HTTP header
Authentication
To authenticate against hakuna, you need to use an API authentication token and supply it in every request as X-Auth-Token
HTTP header.
You can retrieve your personal token by clicking your name on the top right in your hakuna and select "API".
Rate Limits
GET /api/v1/ping HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
Response:
HTTP/1.1 429 Too Many Requests
Retry-After: 10
{ "error": "You sent too many requests, please try again later." }
Our API rate limits are setup per IP and tenant. We allow 4000 requests per hour.
If the rate limit is being triggered, the response will have HTTP status 429 contain a corresponding JSON structure.
The Retry-After
header will indicate how long the client should wait before trying again.
Personal
Overview
Retrieve key metrics
GET /api/v1/overview HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
curl -X "GET" "https://app.hakuna.ch/api/v1/overview" \
-H "Accept-Version: v1" \
-H "X-Auth-Token: your-token"
Response:
{
"overtime": "470:30",
"overtime_in_seconds": 1693800,
"vacation": {
"redeemed_days": 21.5,
"remaining_days": 3.5
}
}
GET /api/v1/overview
Retrieves key numbers about your user, e.g. your current overtime.
Attribute | Description |
---|---|
overtime string | Overtime in hh:mm format (as displayed in hakuna) |
overtime_in_seconds integer | Overtime in seconds |
vacation hash | Vacation information (redeemed and remaining days for the current year) |
Timer
{
"date": "2016-11-08",
"start_time": "19:00",
"duration": "02:16",
"duration_in_seconds": 8138,
"note": "Did a lot of work.",
"user": {
"id": 1,
"name": "Ursula Schneider",
"status": "active",
"groups": [
"Administration"
]
},
"task": {
"id": 1,
"name": "Development",
},
"project": {
"id": 3,
"name": "HR",
"archived": false
}
}
Attribute | Description |
---|---|
start_time string | Start time in hh:mm format |
date string | Date when timer was started in yyyy-mm-dd format |
duration string | Duration in hh:mm format (as displayed in hakuna) |
duration_in_seconds integer | Duration in seconds |
note string | |
user object | User object |
task object | Task object |
project object | Optional Project object |
Get Timer
curl -X "GET" "https://app.hakuna.ch/api/v1/timer" \
-H "Accept-Version: v1" \
-H "X-Auth-Token: your-token"
GET /api/v1/timer HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
GET /api/v1/timer
Retrieves the timer.
Start Timer
curl -X "POST" "https://app.hakuna.ch/api/v1/timer" \
-H "Accept-Version: v1" \
-H "X-Auth-Token: your-token" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
"note": "Did a lot of work.",
"project_id": "3",
"task_id": "1"
}'
POST /api/v1/timer HTTP/1.1
X-Auth-Token: your-token
Content-Type: application/json; charset=utf-8
Host: app.hakuna.ch
Content-Length: 65
{
"note": "Did a lot of work.",
"project_id": "3",
"task_id": "1"
}
POST /api/v1/timer
Parameter | Description |
---|---|
task_id required | Task id (see Task) |
start_time optional | Start time in hh:mm format |
project_id depends | Project id (see Projects). Required if the account-wide project module is enabled. |
note optional | Note as string |
Starts the timer.
Stop Timer
curl -X "PUT" "https://app.hakuna.ch/api/v1/timer" \
-H "X-Auth-Token: your-token"
PUT /api/v1/timer HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
PUT /api/v1/timer
Parameter | Description |
---|---|
end_time optional | End time in hh:mm format |
Stops the timer and creates a corresponding Time Entry.
Cancel Timer
curl -X "DELETE" "https://app.hakuna.ch/api/v1/timer" \
-H "X-Auth-Token: your-token"
DELETE /api/v1/timer HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
DELETE /api/v1/timer
Deletes the timer.
Time Entries
{
"id": 7043,
"date": "2016-10-11",
"start_time": "12:00",
"end_time": "14:00",
"duration": "02:00",
"duration_in_seconds": 7200,
"note": "This is a long text explaining what I did.",
"user": {
"id": 1,
"name": "Ursula Schneider",
"status": "active",
"groups": [
"Administration"
]
},
"task": {
"id": 1,
"name": "Entwicklung",
"archived": false
},
"project": {
"id": 3,
"name": "HR",
"archived": false
}
}
Time entries are your "work blocks" and can be created either directly or via timer.
Attribute | Description |
---|---|
id integer | |
date string | Date in ISO 8601 format |
start_time string | Start time in hh:mm format |
end_time string | End time in hh:mm format |
duration string | Duration in hh:mm format (as displayed in hakuna) |
duration_in_seconds integer | Duration in seconds |
note string | |
user object | User object |
task object | Task object |
project object | Optional Project object |
List time entries
curl -X "GET" "https://app.hakuna.ch/api/v1/time_entries?start_date=2016-01-05&end_date=2016-01-08" \
-H "X-Auth-Token: your-token"
GET /api/v1/time_entries?start_date=2016-01-05&end_date=2016-01-08 HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
GET /api/v1/time_entries?start_date={start_date}&end_date={end_date}
Parameter | Description |
---|---|
start_date required | Start date of the range from which the time entries are requested (ISO 8601, i.e. yyyy-mm-dd ) |
end_date required | End date of the range from which the time entries are requested (ISO 8601, i.e. yyyy-mm-dd ) |
Retrieves all time entries in the date range specified by start_date
and end_date
.
Get a time entry
curl -X "GET" "https://app.hakuna.ch/api/v1/time_entries/1838" \
-H "X-Auth-Token: your-token"
GET /api/v1/time_entries/1838 HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
GET /api/v1/time_entries/{id}
Retrieves the time entry specified by id
.
Create a time entry
curl -X "POST" "https://app.hakuna.ch/api/v1/time_entries" \
-H "X-Auth-Token: your-token" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
"date": "2016-10-10",
"start_time": "22:00",
"end_time": "23:00",
"note": "This is a long text explaining what I did.",
"project_id": 1,
"task_id": 1
}'
POST /api/v1/time_entries HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: app.hakuna.ch
{
"date": "2016-10-10",
"start_time": "22:00",
"end_time": "23:00",
"note": "This is a long text explaining what I did.",
"project_id": 1,
"task_id": 1
}
POST /api/v1/time_entries
Parameter | Description |
---|---|
date required | Date in ISO 8601 format |
start_time required | Start time in hh:mm format |
end_time required | End time in hh:mm format |
task_id required | Task id (see Task) |
project_id depends | Project id (see Projects). Required if the account-wide project module is enabled. |
note optional | Note as string |
Creates a new time entry.
Update a time entry
curl -X "PATCH" "https://app.hakuna.ch/api/v1/time_entries/128" \
-H "X-Auth-Token: your-token" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
"end_time": "23:30:00"
}'
PATCH /api/v1/time_entries/128 HTTP/1.1
X-Auth-Token: your-token
Content-Type: application/json; charset=utf-8
Host: app.hakuna.ch
{
"date": "2016-10-10",
"start_time": "22:00",
"end_time": "23:30",
"note": "This is a long text explaining what I did.",
"project_id": 1,
"task_id": 1
}
PATCH /api/v1/time_entries/{id}
Updates the time entry specified by id
.
Delete a time entry
curl -X "DELETE" "https://app.hakuna.ch/api/v1/time_entries/128" \
-H "X-Auth-Token: your-token"
DELETE /api/v1/time_entries/128 HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
DELETE /api/v1/time_entries/{id}
Deletes the time entry specified by id
.
Absences
{
"id": 148,
"start_date": "2016-01-06",
"end_date": "2016-01-06",
"first_half_day": true,
"second_half_day": false,
"is_recurring": false,
"weekly_repeat_interval": null,
"user": {
"id": 1,
"name": "Ursula Schneider",
"status": "active",
"groups": [
"Administration"
]
},
"absence_type": {
"id": 10,
"name": "Kompensation",
"grants_work_time": false,
"is_vacation": false,
"archived": false
}
}
Attribute | Description |
---|---|
id integer | |
start_date date | Start date in ISO 8601 format |
end_date date | End date in ISO 8601 format |
first_half_day boolean | true if this absence covers the the first half day (or the whole day), false otherwise |
second_half_day boolean | true if this absence covers the the second half day (or the whole day), false otherwise |
is_recurring boolean | Whether or not this absence is recurring |
weekly_repeat_interval integer | The weekly repeat interval (is_recurring must be true ) |
user object | User object |
absence_type object | Absence Type object |
List absences
curl -X "GET" "https://app.hakuna.ch/api/v1/absences?year=2016" \
-H "Accept-Version: v1" \
-H "X-Auth-Token: your-token"
GET /api/v1/absences?year=2016 HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
GET /api/v1/absences?year={year}
Retrieves your absences in the supplied year
.
Users
{
"id": 1,
"name": "Ursula Schneider",
"email": "ursula.schneider@firma.ch",
"status": "active",
"groups": [
"Administration"
]
}
Attribute | Description |
---|---|
id integer | |
name string | User name |
email string | User email address |
status string | active or inactive |
groups array | List of groups this user is a member of |
List users you can manage
curl -X "GET" "https://app.hakuna.ch/api/v1/users" \
-H "X-Auth-Token: your-token"
GET /api/v1/users HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
GET /api/v1/users
Retrieves all user you can manage (as admin or supervisor). See here how to make requests for these users.
Get current user
curl -X "GET" "https://app.hakuna.ch/api/v1/users/me" \
-H "X-Auth-Token: your-token"
GET /api/v1/users/me HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
GET /api/v1/users/me
Retrives the currently authenticated user.
Global
Absence Types
{
"id": 1,
"name": "Paid Leave",
"archived": false,
"grants_work_time": true,
"is_vacation": false
}
Absence types are used to categorize absences (e.g. vacation, sickness).
Attribute | Description |
---|---|
id integer | The ID to reference this absence type |
name string | The name of the absence type |
grants_work_time boolean | if true , the absence type yields a time credit equaling the target time in the absent time frame. |
is_vacation boolean | if true , the absence will affect the vacation balance. |
archived boolean | true if the absence type has been archived |
List absence types
curl -X "GET" "https://app.hakuna.ch/api/v1/absence_types" \
-H "X-Auth-Token: your-token"
GET /api/v1/absence_types HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
GET /api/v1/absence_types
Retrieves all absence types
Tasks
{
"id": 1,
"name": "Development",
"archived": false,
"default": true
}
Tasks are used to categorize time entries.
Attribute | Description |
---|---|
id integer | The ID to reference this task |
name string | The name of the task |
archived boolean | true if the task has been archived |
default boolean | true if the task is common and gets added to new projects, false otherwise |
List tasks
curl -X "GET" "https://app.hakuna.ch/api/v1/tasks" \
-H "X-Auth-Token: your-token"
GET /api/v1/tasks HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
GET /api/v1/tasks
Retrieves all tasks
Projects
{
"id": 3,
"name": "HR",
"archived": false,
"groups": null,
"client": "ABC Inc.",
"tasks": [{
"id": 23,
"name": "Hiring",
"archived": false,
"default": false,
}],
"budget": "10:00",
"budget_in_seconds": 36000,
"budget_is_monthly": true
}
Projects can be assigned to the timer and time entries. This allows to differentiate time spent between different tasks or projects.
Attribute | Description |
---|---|
id integer | |
name string | The name of the project |
client string | The name of the client |
archived boolean | true if the project has been archived |
groups array | Groups assigned to this project, null if the project is global |
tasks array | List of Tasks assigned to this project |
budget string | Budget in hours for this project (in hh:mm ), or null |
budget_in_seconds integer | Budget in seconds for this project, or null |
budget_is_monthly boolean | true if budget resets every month, false otherwise |
List projects
curl -X "GET" "https://app.hakuna.ch/api/v1/projects" \
-H "X-Auth-Token: your-token"
GET /api/v1/projects HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
GET /api/v1/projects
Retrieves a list of all active and archived projects.
Company
Fetch company info
curl -X "GET" "https://app.hakuna.ch/api/v1/company" \
-H "X-Auth-Token: your-token"
GET /api/v1/company HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
Response:
{
"company_name": "hakuna AG",
"duration_format": "decimal",
"absence_requests_enabled": true,
"projects_enabled": false,
"groups_enabled": false
}
GET /api/v1/company
Fetches account-wide company info.
Attribute | Description |
---|---|
company_name string | The configured name of the company |
duration_format string | The configured display of duration s, either hhmm or decimal |
absence_requests_enabled boolean | Whether or not absence requests module is enabled |
projects_enabled boolean | Whether or not the projects module is enabled. This setting changes how the Time Entry and Timer endpoints have to be used |
groups_enabled boolean | Whether or not the groups module is enabled |
Organization
Retrieve organization status
curl -X "GET" "https://app.hakuna.ch/api/v1/organization/status" \
-H "Accept-Version: v1" \
-H "X-Auth-Token: your-token"
GET /api/v1/organization/status HTTP/1.1
X-Auth-Token: your-token
Host: app.hakuna.ch
Response:
[
{
"user": {
"id": 1,
"name": "Ursula Schneider",
"status": "active",
"groups": [
"Administration"
]
},
"absent_first_half_day": false,
"absent_second_half_day": false,
"has_timer_running": true
},
{
"user": {
"id": 2,
"name": "Urs Schneider",
"status": "active",
"groups": [
"Marketing"
]
},
"absent_first_half_day": false,
"absent_second_half_day": true,
"has_timer_running": false
}
]
GET /api/v1/organization/status
Retrieves today's presence/absence information about all users in your organization.
Attribute | Description |
---|---|
user object | User object |
absent_first_half_day boolean | true if the user is absent in the first half day or the whole day (e.g. on vacation or due to part-time workplan). |
absent_second_half_day boolean | true if the user is absent in the second half day or the whole day (e.g. on vacation or due to part-time workplan). |
has_timer_running boolean | true if the user has a timer running |