Servers Playground How we check Add a server Log in

kiwiHR MCP by usefulapi

Working · 979 ms

io.usefulapi/kiwihrv1.0.0 Domain verified

Read kiwiHR employees, time off, timesheets, projects; create and update employees, timesheets.

Productivity

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://kiwihr.usefulapi.io/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

kiwihr_activate_user

WRITE: re-activate a deactivated employee so they appear in active lists and can use kiwiHR again. GraphQL mutation activateUser.

user_idstring, required

Employee id.

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

kiwiHR MCP by usefulapi MCP server | mcptry

Tools (30)

kiwihr_activate_user

WRITE: re-activate a deactivated employee so they appear in active lists and can use kiwiHR again. GraphQL mutation activateUser.

Argument	Type	Description
user_id*	string	Employee id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "user_id"
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Employee id."
    }
  }
}

kiwihr_create_journey

WRITE: create an onboarding/offboarding journey for an employee from a journey type and optionally a template (ids from kiwihr_list_journey_types / kiwihr_list_journey_templates). Creates a new journey each call (not idempotent). It does not publish it; check the status in the reply. GraphQL mutation createJourney.

Argument	Type	Description
name	string	Journey name.
assignee_id*	string	Employee id the journey is for.
custom_date	string	Custom date steps can relate to (YYYY-MM-DD).
personal_email	string	Private e-mail (for pre-onboarding).
journey_type_id*	string	Journey type id.
custom_date_name	string	Label of the custom date.
journey_template_id	string	Journey template id.
pre_onboarding_access	boolean	Enable pre-onboarding access.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "journey_type_id",
    "assignee_id"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Journey name."
    },
    "assignee_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Employee id the journey is for."
    },
    "custom_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Custom date steps can relate to (YYYY-MM-DD)."
    },
    "personal_email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "maxLength": 200,
      "description": "Private e-mail (for pre-onboarding)."
    },
    "journey_type_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Journey type id."
    },
    "custom_date_name": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Label of the custom date."
    },
    "journey_template_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Journey template id."
    },
    "pre_onboarding_access": {
      "type": "boolean",
      "description": "Enable pre-onboarding access."
    }
  }
}

kiwihr_create_project

WRITE: create a time-tracking project (name, status ACTIVE or INACTIVE; default ACTIVE). Creates a new project each call (not idempotent). GraphQL mutation createProject.

Argument	Type	Description
name*	string	Project name.
status	string	ACTIVE projects can be used for time tracking.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Project name."
    },
    "status": {
      "enum": [
        "ACTIVE",
        "INACTIVE"
      ],
      "type": "string",
      "description": "ACTIVE projects can be used for time tracking."
    }
  }
}

kiwihr_create_timesheet_entry

WRITE: add a time entry to the timesheet of one employee on one day (user_id omitted = the admin user the key acts as). type MANUAL = worked time (give start_at and end_at as HH:mm:ss, or a part_of_day), BREAK = a break. Optional project and note. Creates a new entry each call (not idempotent). Returns the updated day. GraphQL mutation createTimesheetEntry.

Argument	Type	Description
date*	string	Day (YYYY-MM-DD).
note	string	Note for the entry.
type*	string	MANUAL = worked time, BREAK = break.
end_at	string	End time HH:mm:ss.
user_id	string	Employee id. Omit for the admin user the API key acts as.
start_at	string	Start time HH:mm:ss.
project_id	string	Project id (from kiwihr_list_projects).
part_of_day	string	For day-based tracking instead of start/end.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "date",
    "type"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Day (YYYY-MM-DD)."
    },
    "note": {
      "type": "string",
      "maxLength": 1000,
      "description": "Note for the entry."
    },
    "type": {
      "enum": [
        "MANUAL",
        "BREAK"
      ],
      "type": "string",
      "description": "MANUAL = worked time, BREAK = break."
    },
    "end_at": {
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d$",
      "description": "End time HH:mm:ss."
    },
    "user_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Employee id. Omit for the admin user the API key acts as."
    },
    "start_at": {
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d$",
      "description": "Start time HH:mm:ss."
    },
    "project_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Project id (from kiwihr_list_projects)."
    },
    "part_of_day": {
      "enum": [
        "FULL_DAY",
        "MORNING",
        "AFTERNOON"
      ],
      "type": "string",
      "description": "For day-based tracking instead of start/end."
    }
  }
}

kiwihr_create_user

WRITE: add a new employee record (first name, last name and work e-mail are required; optional start date, manager, teams, position, location and phones). Creates a new employee each call (not idempotent). No invitation is sent by this tool. Payroll and bank data cannot be set. GraphQL mutation createUser.

Argument	Type	Description
email*	string	Work e-mail address.
gender	string
team_ids	array	Team ids (from kiwihr_list_teams).
last_name*	string
first_name*	string
manager_id	string	Manager's employee id.
location_id	string	Location id (from kiwihr_list_locations).
position_id	string	Position id (from kiwihr_list_positions).
work_phones	array
employment_start_date

kiwihr_deactivate_user

WRITE, ACCESS-CHANGING: deactivate an active employee (typically after they leave): they lose access to kiwiHR and drop out of active lists. Reversible with kiwihr_activate_user. GraphQL mutation deactivateUser.

destructive

Argument	Type	Description
user_id*	string	Employee id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "user_id"
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Employee id."
    }
  }
}

kiwihr_delete_timesheet_entry

WRITE, DESTRUCTIVE: permanently delete one timesheet entry by id (get it from kiwihr_get_timesheet). This cannot be undone. Returns true when deleted. GraphQL mutation deleteTimesheetEntry.

destructive

Argument	Type	Description
entry_id*	string	Timesheet entry id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "entry_id"
  ],
  "properties": {
    "entry_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Timesheet entry id."
    }
  }
}

kiwihr_get_attendance_statement

Attendance summary of ONE employee over a date range: expected, tracked, total, time off and holiday time (seconds) and days, balance, overtime, meal vouchers, and tracked time per project. GraphQL query attendanceStatement.

read-only

Argument	Type	Description
date_to*	string	Range end (YYYY-MM-DD).
user_id*	string	Employee id.
date_from*	string	Range start (YYYY-MM-DD).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "user_id",
    "date_from",
    "date_to"
  ],
  "properties": {
    "date_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Range end (YYYY-MM-DD)."
    },
    "user_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Employee id."
    },
    "date_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Range start (YYYY-MM-DD)."
    }
  }
}

kiwihr_get_journey

One journey by id with its steps (name, description, fixed start and due dates). With include_personal=true it also returns the private e-mail address stored on the journey. GraphQL query journey.

read-only

Argument	Type	Description
journey_id*	string	Journey id.
include_personal	boolean	Also return the private e-mail on the journey. Default false.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "journey_id"
  ],
  "properties": {
    "journey_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Journey id."
    },
    "include_personal": {
      "type": "boolean",
      "description": "Also return the private e-mail on the journey. Default false."
    }
  }
}

kiwihr_get_project

One time-tracking project by id (name, status). GraphQL query project.

read-only

Argument	Type	Description
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Project id."
    }
  }
}

kiwihr_get_time_off_usage

Who took (or requested) how much time off in a date range: per employee the request count and used days for each time off rule of the chosen time off types. Use it for absence reports ('who was off in March?'). Optional employee filters as in kiwihr_list_users. GraphQL query timeOffRequestUsageStatements.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
date_to*	string	Range end (YYYY-MM-DD).
sort_by	string
team_id	string	Only employees of this team.
date_from*	string	Range start (YYYY-MM-DD).
is_active	boolean	true = active employees only.
location_id	string	Only employees at this location.
sort_direction

kiwihr_get_timesheet

The timesheet of ONE employee for ONE day (user_id omitted = the admin user the key acts as), with all entries and their ids (needed to update or delete an entry). Times in seconds. GraphQL query timesheet.

read-only

Argument	Type	Description
date*	string	Day (YYYY-MM-DD).
user_id	string	Employee id. Omit for the admin user the API key acts as.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "date"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Day (YYYY-MM-DD)."
    },
    "user_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Employee id. Omit for the admin user the API key acts as."
    }
  }
}

kiwihr_get_user

One employee by id: the list fields plus probation end, about-me, language, invitation status, work phones, all teams, work schedule and custom field values. With include_personal=true it also returns birth date, private e-mail and phone, nationality, gender, pronouns, home address, emergency contact and custom fields of the personal sections. Payroll, bank (IBAN/BIC), tax and insurance data are never returned. GraphQL query user.

read-only

Argument	Type	Description
user_id*	string	Employee id.
include_personal	boolean	Also return private data (birth date, private contact data, address, emergency contact). Default false.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "user_id"
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Employee id."
    },
    "include_personal": {
      "type": "boolean",
      "description": "Also return private data (birth date, private contact data, address, emergency contact). Default false."
    }
  }
}

kiwihr_list_attendance_statements

Attendance summaries of ALL employees over a date range (expected vs tracked time, time off, holidays, balance, overtime, tracked time per project). Optionally only employees with time tracked on a project, or with uncategorized time; inactive employees can be included. GraphQL query attendanceStatements.

read-only

Argument	Type	Description
date_to*	string	Range end (YYYY-MM-DD).
sort_by	string
date_from*	string	Range start (YYYY-MM-DD).
project_id	string	Only employees with tracked time in this project.
sort_direction	string	Sort direction (default ASC).
has_uncategorized_time	boolean	true = only employees with tracked time not assigned to any project.
include_inactive_users	boolean	Also include deactivated employees (default false).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "date_from",
    "date_to"
  ],
  "properties": {
    "date_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Range end (YYYY-MM-DD)."
    },
    "sort_by": {
      "enum": [
        "firstName",
        "lastName"
      ],
      "type": "string"
    },
    "date_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Range start (YYYY-MM-DD)."
    },
    "project_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Only employees with tracked time in this project."
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    },
    "has_uncategorized_time": {
      "type": "boolean",
      "description": "true = only employees with tracked time not assigned to any project."
    },
    "include_inactive_users": {
      "type": "boolean",
      "description": "Also include deactivated employees (default false)."
    }
  }
}

kiwihr_list_custom_fields

List the company's custom employee profile fields (id, name, section, data type, choice options). Payroll and bank sections are listed by name only; their values are never returned by any tool. GraphQL query customFields.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
sort_by	string
sort_direction	string	Sort direction (default ASC).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "sort_by": {
      "enum": [
        "id",
        "name",
        "section",
        "type"
      ],
      "type": "string"
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    }
  }
}

kiwihr_list_journey_templates

List journey templates (id, name, description, type). Use a template id with kiwihr_create_journey. GraphQL query journeyTemplates.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
journey_type_id	string	Only templates of this journey type.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "journey_type_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Only templates of this journey type."
    }
  }
}

kiwihr_list_journey_types

List journey types such as pre-onboarding, onboarding or offboarding (id, name, key, archived date). GraphQL query journeyTypes.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    }
  }
}

kiwihr_list_journeys

List onboarding/offboarding journeys (id, name, status DRAFT/ONGOING/COMPLETED/CANCELLED, assignee, journey type, custom date). Filter by status, assignee, type or team. GraphQL query journeys.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
status	string	Only journeys with this status.
team_ids	array	Only journeys of employees in these teams.
assignee_ids	array	Only journeys assigned to these employee ids.
journey_type_ids	array	Only these journey types (from kiwihr_list_journey_types).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "status": {
      "enum": [
        "DRAFT",
        "ONGOING",
        "COMPLETED",
        "CANCELLED"
      ],
      "type": "string",
      "description": "Only journeys with this status."
    },
    "team_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 64,
        "minLength": 1
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Only journeys of employees in these teams."
    },
    "assignee_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 64,
        "minLength": 1
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Only journeys assigned to these employee ids."
    },
    "journey_type_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 64,
        "minLength": 1
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Only these journey types (from kiwihr_list_journey_types)."
    }
  }
}

kiwihr_list_locations

List office locations (id, name). Use the ids to filter employees. GraphQL query locations.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
sort_by	string
sort_direction	string	Sort direction (default ASC).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "sort_by": {
      "enum": [
        "id",
        "name"
      ],
      "type": "string"
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    }
  }
}

kiwihr_list_overtime_balances

Current overtime balance (seconds) per employee. GraphQL query overtimeBalanceStatements.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
sort_by	string
sort_direction	string	Sort direction (default ASC).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "sort_by": {
      "enum": [
        "firstName",
        "lastName",
        "date",
        "balance"
      ],
      "type": "string"
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    }
  }
}

kiwihr_list_positions

List job positions (id, name). Use the ids to filter employees. GraphQL query positions.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
sort_by	string
sort_direction	string	Sort direction (default ASC).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "sort_by": {
      "enum": [
        "id",
        "name"
      ],
      "type": "string"
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    }
  }
}

kiwihr_list_projects

List time-tracking projects (id, name, status ACTIVE or INACTIVE). GraphQL query projects.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
status	string	Only projects with this status.
sort_by	string
sort_direction	string	Sort direction (default ASC).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "status": {
      "enum": [
        "ACTIVE",
        "INACTIVE"
      ],
      "type": "string",
      "description": "Only projects with this status."
    },
    "sort_by": {
      "enum": [
        "id",
        "name"
      ],
      "type": "string"
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    }
  }
}

kiwihr_list_teams

List teams and departments (id, name, kind GROUP or DEPARTMENT). Use the ids to filter employees. GraphQL query teams.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
sort_by	string
sort_direction	string	Sort direction (default ASC).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "sort_by": {
      "enum": [
        "id",
        "name"
      ],
      "type": "string"
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    }
  }
}

kiwihr_list_time_off_balances

Time off balances of all employees: per employee and time off rule the allowance, accrued, used, requested, planned and available days, carry-over and the accrual/usage periods. Filter by time off type, active state and usage period. The API has no per-employee filter or paging for this query; read the result per user. GraphQL query timeOffBalances.

read-only

Argument	Type	Description
sort_by	string
is_active	boolean	true = active balances only.
sort_direction	string	Sort direction (default ASC).
time_off_type_id	string	Only this time off type (from kiwihr_list_time_off_types).
usage_period_end_to	string	Usage period ends on or before this date.
usage_period_start_from	string	Usage period starts on or after this date.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "sort_by": {
      "enum": [
        "periodStartDate",
        "periodEndDate"
      ],
      "type": "string"
    },
    "is_active": {
      "type": "boolean",
      "description": "true = active balances only."
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    },
    "time_off_type_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Only this time off type (from kiwihr_list_time_off_types)."
    },
    "usage_period_end_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Usage period ends on or before this date."
    },
    "usage_period_start_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Usage period starts on or after this date."
    }
  }
}

kiwihr_list_time_off_types

List time off (absence) types such as vacation or sick leave: id, name, colour, visibility to team members. Use the ids with kiwihr_get_time_off_usage and kiwihr_list_time_off_balances. GraphQL query timeOffTypes.

read-only

Argument	Type	Description
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
sort_by	string
sort_direction	string	Sort direction (default ASC).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "sort_by": {
      "enum": [
        "id",
        "name"
      ],
      "type": "string"
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    }
  }
}

kiwihr_list_timesheets

Daily timesheets of one employee (or the key's admin user when user_id is omitted) in a date range: expected, tracked, time off, holiday and break time in SECONDS, approval flag, time offs, holidays, entries (start/end, type, note, project) and break-rule violations. GraphQL query timesheets.

read-only

Argument	Type	Description
limit	integer	Days per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
date_to*	string	Range end (YYYY-MM-DD).
user_id	string	Employee id. Omit for the admin user the API key acts as.
date_from*	string	Range start (YYYY-MM-DD).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "date_from",
    "date_to"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Days per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "date_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Range end (YYYY-MM-DD)."
    },
    "user_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Employee id. Omit for the admin user the API key acts as."
    },
    "date_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Range start (YYYY-MM-DD)."
    }
  }
}

kiwihr_list_users

List or search employees (kiwiHR 'users') with name, work email, active flag, employee number, employment dates, position, team, location and manager. Filter by active state, team, location, position, e-mail or name. Payroll, bank, tax and insurance data are never included. GraphQL query users.

read-only

Argument	Type	Description
email	string	Work e-mail contains this text.
limit	integer	Items per page (1-100, default 50).
offset	integer	Items to skip (default 0). The reply's pageInfo.next says whether there is another page.
sort_by	string	Sort field.
team_id	string	Team id (from kiwihr_list_teams).
user_ids	array	Only these employee ids.
is_active	boolean	true = active employees only, false = deactivated only. Omit for both.
last_name	string	Last name contains this text.
first_name	string

kiwihr_update_project

WRITE: rename a project or switch it ACTIVE/INACTIVE (INACTIVE projects can no longer be used for time tracking). Only the fields you pass are changed. GraphQL mutation updateProject.

destructive

Argument	Type	Description
name	string	New name.
status	string	New status.
project_id*	string	Project id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "project_id"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "New name."
    },
    "status": {
      "enum": [
        "ACTIVE",
        "INACTIVE"
      ],
      "type": "string",
      "description": "New status."
    },
    "project_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Project id."
    }
  }
}

kiwihr_update_timesheet_entry

WRITE: change an existing timesheet entry (get its id from kiwihr_get_timesheet): times, part of day, project or note. Only the fields you pass are changed. Setting the same values again gives the same result. Returns the updated day. GraphQL mutation updateTimesheetEntry.

destructive

Argument	Type	Description
note	string	New note.
end_at	string	New end time HH:mm:ss.
entry_id*	string	Timesheet entry id.
start_at	string	New start time HH:mm:ss.
project_id	string	New project id.
part_of_day	string	New part of day.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "entry_id"
  ],
  "properties": {
    "note": {
      "type": "string",
      "maxLength": 1000,
      "description": "New note."
    },
    "end_at": {
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d$",
      "description": "New end time HH:mm:ss."
    },
    "entry_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Timesheet entry id."
    },
    "start_at": {
      "type": "string",
      "pattern": "^([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d$",
      "description": "New start time HH:mm:ss."
    },
    "project_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "New project id."
    },
    "part_of_day": {
      "enum": [
        "FULL_DAY",
        "MORNING",
        "AFTERNOON"
      ],
      "type": "string",
      "description": "New part of day."
    }
  }
}

kiwihr_update_user

WRITE: change an employee's work profile: name, start date, about-me, work phones, position, team(s), location, manager. Only the fields you pass are changed (team_ids replaces the whole team list). Private, payroll and bank data cannot be changed with this tool. GraphQL mutation updateUser.

destructive

Argument	Type	Description
user_id*	string	Employee id.
about_me	string
team_ids	array	Replaces the list of teams.
last_name	string
first_name	string
manager_id	string
location_id	string
position_id	string
work_phones	array	Replaces the list of work phones.
employment_start_date

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Work e-mail contains this text."
    },
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Items per page (1-100, default 50)."
    },
    "offset": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Items to skip (default 0). The reply's pageInfo.next says whether there is another page."
    },
    "sort_by": {
      "enum": [
        "id",
        "firstName",
        "lastName",
        "position",
        "team",
        "location"
      ],
      "type": "string",
      "description": "Sort field."
    },
    "team_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Team id (from kiwihr_list_teams)."
    },
    "user_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 64,
        "minLength": 1
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Only these employee ids."
    },
    "is_active": {
      "type": "boolean",
      "description": "true = active employees only, false = deactivated only. Omit for both."
    },
    "last_name": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Last name contains this text."
    },
    "first_name": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "First name contains this text."
    },
    "location_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Location id (from kiwihr_list_locations)."
    },
    "position_id": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Position id (from kiwihr_list_positions)."
    },
    "sort_direction": {
      "enum": [
        "ASC",
        "DESC"
      ],
      "type": "string",
      "description": "Sort direction (default ASC)."
    },
    "employment_start_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Only employees who started on or after this date."
    }
  }
}