NAV
HTTP Shell

Introduction

Welcome to the hakuna API. You can use our API to:

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:

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 durations, 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
HTTP Shell