{ "openapi": "3.1.0", "info": { "title": "Tiveo API", "version": "1.0.0-beta", "summary": "Read employees, absences, time and shifts from Tiveo (beta).", "description": "The public Tiveo API, from the Business plan. **Beta**: read-only; writing is planned. Documentation: https://tiveo.de/en/entwickler/", "contact": { "name": "Tiveo", "email": "info@tiveo.de", "url": "https://tiveo.de/entwickler/" }, "termsOfService": "https://tiveo.de/agb/", "x-beta": true }, "servers": [ { "url": "https://api.tiveo.de/v1" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Check your key", "description": "Company, scopes and limits of this key — the first call of every integration." }, { "name": "Employees", "description": "All employees of the company, including records without an account and leavers. Without sample persons and admin-only accounts." }, { "name": "Units", "description": "Divisions, departments, teams and locations as a tree (`parent_id`), with leads." }, { "name": "Absence types", "description": "Leave, sickness, remote work and the company’s own types." }, { "name": "Absences", "description": "Requests and recorded absences, without drafts and without free text. Without absences:read_sensitive, sensitive types are masked (`masked: true`, `type_id: null`)." }, { "name": "Leave balances", "description": "Per employee and year: entitlement, taken, requested, remaining and carry-over — calculated live as in the app. Pages by employee." }, { "name": "Holidays and days off", "description": "Public holidays (by country and region) and company days off of one year, by date. No paging." }, { "name": "Clock events", "description": "Clock-in, clock-out and breaks as they stand: without cancelled and replaced entries. Period at most 93 days." }, { "name": "Daily time sheets", "description": "Per employee and day: work, break, target and balance in minutes — calculated like “My times”. Period at most 62 days; `limit` counts employees (default 10, max 25)." }, { "name": "Projects", "description": "Projects employees book time on." }, { "name": "Project times", "description": "Booked minutes per employee, day and project. Period at most 93 days." }, { "name": "Shift types", "description": "Early, late, on-call and other types with times." }, { "name": "Shifts", "description": "Published shifts, including dropped and cancelled ones; no drafts, no notes. Period at most 93 days." }, { "name": "Vehicles", "description": "Company vehicles (pool and assigned cars) and employees’ own cars used for mileage allowance, including retired ones." }, { "name": "Trips", "description": "Trips in their current version, without cancelled ones. Private trips and commutes only with day and kilometres. Protected business partners only as a number. Never the route. Period at most 93 days." }, { "name": "Vehicle costs", "description": "Costs per vehicle, without note and without the receipt (only whether there is one). Period at most 366 days." }, { "name": "Mileage allowances", "description": "Approved mileage allowance for business trips with an own car: the latest version per employee and month." }, { "name": "Writing (planned)", "description": "Locked during the beta." } ], "paths": { "/me": { "get": { "operationId": "list_me", "summary": "Check your key", "description": "Company, scopes and limits of this key — the first call of every integration.", "tags": [ "Check your key" ], "security": [ { "bearer": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/employees": { "get": { "operationId": "list_employees", "summary": "Employees", "description": "All employees of the company, including records without an account and leavers. Without sample persons and admin-only accounts. Scope: `employees:read`.", "tags": [ "Employees" ], "security": [ { "bearer": [ "employees:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Only this status.", "schema": { "type": "string", "enum": [ "record_only", "invited", "active", "inactive", "left" ] } }, { "name": "unit_id", "in": "query", "required": false, "description": "Only this unit (main unit).", "schema": { "type": "string", "format": "uuid" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only what changed since this moment (ISO 8601 with offset) — for syncing.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "post_employees", "summary": "Create an employee (planned)", "description": "Creates an employee record. **Planned — during the beta this always answers 403 `write_not_available_in_beta`.**", "tags": [ "Writing (planned)" ], "security": [ { "bearer": [ "employees:write" ] } ], "x-tiveo-planned": true, "responses": { "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/employees/{id}": { "get": { "operationId": "get_employees", "summary": "Employees — single", "description": "One item by id. Scope: `employees:read`.", "tags": [ "Employees" ], "security": [ { "bearer": [ "employees:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Employee" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unknown path or id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "patch_employees_id", "summary": "Update master data (planned)", "description": "Changes name, personnel number, unit, entry or exit. **Planned — during the beta this always answers 403 `write_not_available_in_beta`.**", "tags": [ "Writing (planned)" ], "security": [ { "bearer": [ "employees:write" ] } ], "x-tiveo-planned": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/units": { "get": { "operationId": "list_units", "summary": "Units", "description": "Divisions, departments, teams and locations as a tree (`parent_id`), with leads. Scope: `employees:read`.", "tags": [ "Units" ], "security": [ { "bearer": [ "employees:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Unit" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/units/{id}": { "get": { "operationId": "get_units", "summary": "Units — single", "description": "One item by id. Scope: `employees:read`.", "tags": [ "Units" ], "security": [ { "bearer": [ "employees:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Unit" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unknown path or id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absence-types": { "get": { "operationId": "list_absence_types", "summary": "Absence types", "description": "Leave, sickness, remote work and the company’s own types. Scope: `absences:read`.", "tags": [ "Absence types" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AbsenceType" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absence-types/{id}": { "get": { "operationId": "get_absence_types", "summary": "Absence types — single", "description": "One item by id. Scope: `absences:read`.", "tags": [ "Absence types" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AbsenceType" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unknown path or id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences": { "get": { "operationId": "list_absences", "summary": "Absences", "description": "Requests and recorded absences, without drafts and without free text. Without absences:read_sensitive, sensitive types are masked (`masked: true`, `type_id: null`). Scope: `absences:read`.", "tags": [ "Absences" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Only absences ending on or after this day.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Only absences starting on or before this day.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Only this status.", "schema": { "type": "string", "enum": [ "requested", "partially_approved", "approved", "rejected", "cancellation_requested", "cancelled" ] } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only what changed since this moment (ISO 8601 with offset) — for syncing.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Absence" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "post_absences", "summary": "Create an absence (planned)", "description": "Records an absence or files a request — with the app’s rules (approval, blackout periods, licence). **Planned — during the beta this always answers 403 `write_not_available_in_beta`.**", "tags": [ "Writing (planned)" ], "security": [ { "bearer": [ "absences:write" ] } ], "x-tiveo-planned": true, "responses": { "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences/{id}": { "get": { "operationId": "get_absences", "summary": "Absences — single", "description": "One item by id. Scope: `absences:read`.", "tags": [ "Absences" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Absence" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unknown path or id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/leave-balances": { "get": { "operationId": "list_leave_balances", "summary": "Leave balances", "description": "Per employee and year: entitlement, taken, requested, remaining and carry-over — calculated live as in the app. Pages by employee. Scope: `absences:read`.", "tags": [ "Leave balances" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page (an employee id).", "schema": { "type": "string", "format": "uuid" } }, { "name": "year", "in": "query", "required": false, "description": "Year, default the current one.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "employee_id", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveBalance" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/holidays": { "get": { "operationId": "list_holidays", "summary": "Holidays and days off", "description": "Public holidays (by country and region) and company days off of one year, by date. No paging. Scope: `absences:read`.", "tags": [ "Holidays and days off" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Year, default the current one.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "region", "in": "query", "required": false, "description": "Region like NW or BY, default the company’s region.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Holiday" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/time-entries": { "get": { "operationId": "list_time_entries", "summary": "Clock events", "description": "Clock-in, clock-out and breaks as they stand: without cancelled and replaced entries. Period at most 93 days. Scope: `time:read`. Only if the company uses time tracking.", "tags": [ "Clock events" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "First day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Last day, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeEntry" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "post_time_entries", "summary": "Record working time (planned)", "description": "Records clock-in, clock-out or a break. **Planned — during the beta this always answers 403 `write_not_available_in_beta`.**", "tags": [ "Writing (planned)" ], "security": [ { "bearer": [ "time:write" ] } ], "x-tiveo-planned": true, "responses": { "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/timesheets": { "get": { "operationId": "list_timesheets", "summary": "Daily time sheets", "description": "Per employee and day: work, break, target and balance in minutes — calculated like “My times”. Period at most 62 days; `limit` counts employees (default 10, max 25). Scope: `time:read`. Only if the company uses time tracking.", "tags": [ "Daily time sheets" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Employees per page, default 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page (an employee id).", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "First day; at most 62 days to `to`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Last day, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimesheetDay" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/projects": { "get": { "operationId": "list_projects", "summary": "Projects", "description": "Projects employees book time on. Scope: `time:read`. Only if the company uses time tracking.", "tags": [ "Projects" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/projects/{id}": { "get": { "operationId": "get_projects", "summary": "Projects — single", "description": "One item by id. Scope: `time:read`. Only if the company uses time tracking.", "tags": [ "Projects" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Project" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unknown path or id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/project-times": { "get": { "operationId": "list_project_times", "summary": "Project times", "description": "Booked minutes per employee, day and project. Period at most 93 days. Scope: `time:read`. Only if the company uses time tracking.", "tags": [ "Project times" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "First day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Last day, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": false, "description": "Only this project.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTime" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/shift-types": { "get": { "operationId": "list_shift_types", "summary": "Shift types", "description": "Early, late, on-call and other types with times. Scope: `shifts:read`. Only if the company uses shift planning.", "tags": [ "Shift types" ], "security": [ { "bearer": [ "shifts:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShiftType" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/shift-types/{id}": { "get": { "operationId": "get_shift_types", "summary": "Shift types — single", "description": "One item by id. Scope: `shifts:read`. Only if the company uses shift planning.", "tags": [ "Shift types" ], "security": [ { "bearer": [ "shifts:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ShiftType" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unknown path or id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/shifts": { "get": { "operationId": "list_shifts", "summary": "Shifts", "description": "Published shifts, including dropped and cancelled ones; no drafts, no notes. Period at most 93 days. Scope: `shifts:read`. Only if the company uses shift planning.", "tags": [ "Shifts" ], "security": [ { "bearer": [ "shifts:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "First day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Last day, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } }, { "name": "unit_id", "in": "query", "required": false, "description": "Only this unit.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shift" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/vehicles": { "get": { "operationId": "list_vehicles", "summary": "Vehicles", "description": "Company vehicles (pool and assigned cars) and employees’ own cars used for mileage allowance, including retired ones. Scope: `vehicles:read`. Only if the company uses vehicle logbook.", "tags": [ "Vehicles" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/vehicles/{id}": { "get": { "operationId": "get_vehicles", "summary": "Vehicles — single", "description": "One item by id. Scope: `vehicles:read`. Only if the company uses vehicle logbook.", "tags": [ "Vehicles" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehicle" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unknown path or id.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/trips": { "get": { "operationId": "list_trips", "summary": "Trips", "description": "Trips in their current version, without cancelled ones. Private trips and commutes only with day and kilometres. Protected business partners only as a number. Never the route. Period at most 93 days. Scope: `vehicles:read`. Only if the company uses vehicle logbook.", "tags": [ "Trips" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "First day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Last day, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } }, { "name": "vehicle_id", "in": "query", "required": false, "description": "Only this vehicle.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trip" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/vehicle-costs": { "get": { "operationId": "list_vehicle_costs", "summary": "Vehicle costs", "description": "Costs per vehicle, without note and without the receipt (only whether there is one). Period at most 366 days. Scope: `vehicles:read`. Only if the company uses vehicle logbook.", "tags": [ "Vehicle costs" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "First day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Last day, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "vehicle_id", "in": "query", "required": false, "description": "Only this vehicle.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleCost" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/mileage-allowances": { "get": { "operationId": "list_mileage_allowances", "summary": "Mileage allowances", "description": "Approved mileage allowance for business trips with an own car: the latest version per employee and month. Scope: `vehicles:read`. Only if the company uses vehicle logbook.", "tags": [ "Mileage allowances" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, default 50, at most the company’s page size (usually 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page.", "schema": { "type": "string", "format": "uuid" } }, { "name": "year", "in": "query", "required": false, "description": "Year, default the current one.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "employee_id", "in": "query", "required": false, "description": "Only this employee.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests per minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Left in this minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the next minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Requests per day.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Left today.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MileageAllowance" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Value for the next page; null on the last one." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: A parameter is missing or wrong; `detail` names it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: No API key or an unknown one. `key_revoked`: The key was revoked. `key_expired`: The key has expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Too many requests per minute; `Retry-After` says when to continue. `daily_limit_reached`: The daily limit of the company is reached. `too_many_failed_attempts`: Too many invalid keys from this address; `Retry-After` says when to continue (up to 15 minutes).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Error on our side; retry later.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: The API is busy or the request took too long; honour `Retry-After`, narrow the period.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences/{id}/approve": { "post": { "operationId": "post_absences_id_approve", "summary": "Approve a request (planned)", "description": "Approves a pending request. **Planned — during the beta this always answers 403 `write_not_available_in_beta`.**", "tags": [ "Writing (planned)" ], "security": [ { "bearer": [ "absences:write" ] } ], "x-tiveo-planned": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences/{id}/reject": { "post": { "operationId": "post_absences_id_reject", "summary": "Reject a request (planned)", "description": "Rejects a pending request. **Planned — during the beta this always answers 403 `write_not_available_in_beta`.**", "tags": [ "Writing (planned)" ], "security": [ { "bearer": [ "absences:write" ] } ], "x-tiveo-planned": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences/{id}/cancel": { "post": { "operationId": "post_absences_id_cancel", "summary": "Cancel an absence (planned)", "description": "Cancels an absence. **Planned — during the beta this always answers 403 `write_not_available_in_beta`.**", "tags": [ "Writing (planned)" ], "security": [ { "bearer": [ "absences:write" ] } ], "x-tiveo-planned": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "403": { "description": "`insufficient_scope`: The key lacks the required scope. `plan_required`: The API is available from the Business plan. `api_paused`: The API is paused for this company. `company_locked`: The company account is locked or closed. `module_not_active`: The company does not use this module. `write_not_available_in_beta`: Writing is not available during the beta.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API key from Settings › Integrations › API: `Authorization: Bearer tiveo_…`." } }, "schemas": { "Problem": { "type": "object", "description": "Error as per RFC 9457.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "enum": [ "invalid_parameter", "invalid_key", "key_revoked", "key_expired", "insufficient_scope", "plan_required", "api_paused", "company_locked", "module_not_active", "write_not_available_in_beta", "not_found", "method_not_allowed", "rate_limited", "daily_limit_reached", "too_many_failed_attempts", "internal_error", "server_busy" ] }, "detail": { "type": "string" } }, "required": [ "type", "title", "status", "code" ] }, "Me": { "type": "object", "properties": { "beta": { "description": "The API is in beta.", "type": "boolean" }, "company": { "description": "The company of the key.", "type": "object", "properties": { "id": { "description": "Company id.", "type": "string", "format": "uuid" }, "name": { "description": "Name.", "type": "string" }, "country": { "description": "Country (DE, AT, CH).", "type": "string" }, "region": { "description": "Default region for holidays.", "type": [ "string", "null" ] }, "time_zone": { "description": "Time zone.", "type": "string" } }, "required": [ "id", "name", "country", "region", "time_zone" ] }, "key": { "description": "The key.", "type": "object", "properties": { "id": { "description": "Key id.", "type": "string", "format": "uuid" }, "name": { "description": "Name given by the company.", "type": "string" }, "scopes": { "description": "Scopes.", "type": "array", "items": { "type": "string" } }, "expires_on": { "description": "Expires (valid through this day).", "type": [ "string", "null" ], "format": "date" } }, "required": [ "id", "name", "scopes", "expires_on" ] }, "limits": { "description": "Limits of the company.", "type": "object", "properties": { "per_minute": { "description": "Requests per minute.", "type": "integer" }, "per_day": { "description": "Requests per day.", "type": "integer" }, "max_page_size": { "description": "Largest page (`limit`).", "type": "integer" } }, "required": [ "per_minute", "per_day", "max_page_size" ] }, "modules": { "description": "Which modules the company uses.", "type": "object", "properties": { "time_tracking": { "description": "Time tracking.", "type": "boolean" }, "shift_planning": { "description": "Shift planning.", "type": "boolean" }, "vehicle_logbook": { "description": "Vehicle logbook.", "type": "boolean" } }, "required": [ "time_tracking", "shift_planning", "vehicle_logbook" ] }, "write_access": { "description": "Writing possible — always false during the beta.", "type": "boolean" } }, "required": [ "beta", "company", "key", "limits", "modules", "write_access" ], "example": { "beta": true, "company": { "id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "name": "Tischlerei Muster GmbH", "country": "DE", "region": "NW", "time_zone": "Europe/Berlin" }, "key": { "id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "name": "Lohnbüro", "scopes": [ "employees:read", "absences:read" ], "expires_on": null }, "limits": { "per_minute": 60, "per_day": 10000, "max_page_size": 200 }, "modules": { "time_tracking": true, "shift_planning": false, "vehicle_logbook": false }, "write_access": false } }, "Employee": { "type": "object", "properties": { "id": { "description": "Id of the person in this company.", "type": "string", "format": "uuid" }, "personnel_number": { "description": "Personnel number.", "type": [ "string", "null" ] }, "display_name": { "description": "Display name.", "type": "string" }, "first_name": { "description": "First name (from the account, else null).", "type": [ "string", "null" ] }, "last_name": { "description": "Last name (from the account, else null).", "type": [ "string", "null" ] }, "email": { "description": "Email address.", "type": [ "string", "null" ] }, "role": { "description": "Role in Tiveo.", "type": "string", "enum": [ "owner", "admin", "hr", "manager", "employee" ] }, "status": { "description": "record_only = record without account, invited, active, inactive = on hold, left.", "type": "string", "enum": [ "record_only", "invited", "active", "inactive", "left" ] }, "unit_id": { "description": "Main unit.", "type": [ "string", "null" ], "format": "uuid" }, "additional_unit_ids": { "description": "Additional units.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "region": { "description": "Region for holidays, if different.", "type": [ "string", "null" ] }, "entry_date": { "description": "Entry date.", "type": [ "string", "null" ], "format": "date" }, "exit_date": { "description": "Exit date.", "type": [ "string", "null" ], "format": "date" }, "weekly_hours": { "description": "Weekly hours of today’s working model.", "type": [ "number", "null" ] }, "created_at": { "description": "Created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last changed.", "type": "string", "format": "date-time" } }, "required": [ "id", "personnel_number", "display_name", "first_name", "last_name", "email", "role", "status", "unit_id", "additional_unit_ids", "region", "entry_date", "exit_date", "weekly_hours", "created_at", "updated_at" ], "example": { "id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "personnel_number": "00042", "display_name": "Anna Achter", "first_name": "Anna", "last_name": "Achter", "email": "anna.achter@example.com", "role": "employee", "status": "active", "unit_id": "8c0e4f7a-2d1b-4c3e-9a55-6f7e8d9c0b1a", "additional_unit_ids": [], "region": null, "entry_date": "2024-01-01", "exit_date": null, "weekly_hours": 40, "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "Unit": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "parent_id": { "description": "Parent unit.", "type": [ "string", "null" ], "format": "uuid" }, "name": { "description": "Name.", "type": "string" }, "type": { "description": "Kind.", "type": "string", "enum": [ "division", "department", "team", "location" ] }, "region": { "description": "Region for holidays.", "type": [ "string", "null" ] }, "active": { "description": "Active.", "type": "boolean" }, "sort_order": { "description": "Sort order.", "type": [ "integer", "null" ] }, "leads": { "description": "Leads and deputies.", "type": "array", "items": { "type": "object", "properties": { "employee_id": { "description": "Employee.", "type": "string", "format": "uuid" }, "kind": { "description": "Lead or deputy.", "type": "string", "enum": [ "lead", "deputy" ] } }, "required": [ "employee_id", "kind" ] } }, "created_at": { "description": "Created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last changed.", "type": "string", "format": "date-time" } }, "required": [ "id", "parent_id", "name", "type", "region", "active", "sort_order", "leads", "created_at", "updated_at" ], "example": { "id": "8c0e4f7a-2d1b-4c3e-9a55-6f7e8d9c0b1a", "parent_id": null, "name": "Werkstatt", "type": "team", "region": null, "active": true, "sort_order": 10, "leads": [ { "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "kind": "lead" } ], "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "AbsenceType": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "key": { "description": "Key (urlaub, krankheit … or custom).", "type": "string" }, "name": { "description": "Name in German and English.", "type": "object", "properties": { "de": { "description": "German.", "type": "string" }, "en": { "description": "English.", "type": "string" } }, "required": [ "de", "en" ] }, "short_name": { "description": "Short name (1–3 characters).", "type": "string" }, "color": { "description": "Colour (#rrggbb).", "type": "string" }, "text_color": { "description": "Text colour (#rrggbb).", "type": "string" }, "counts_against_allowance": { "description": "Counts against the leave allowance.", "type": "boolean" }, "requires_approval": { "description": "Requires approval.", "type": "boolean" }, "requires_certificate": { "description": "Requires a certificate.", "type": "boolean" }, "half_days_allowed": { "description": "Half days allowed.", "type": "boolean" }, "sensitive": { "description": "Sensitive (e.g. sickness): masked without absences:read_sensitive.", "type": "boolean" }, "active": { "description": "Active.", "type": "boolean" }, "sort_order": { "description": "Sort order.", "type": [ "integer", "null" ] } }, "required": [ "id", "key", "name", "short_name", "color", "text_color", "counts_against_allowance", "requires_approval", "requires_certificate", "half_days_allowed", "sensitive", "active", "sort_order" ], "example": { "id": "b7d1e2f3-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "key": "urlaub", "name": { "de": "Urlaub", "en": "Annual leave" }, "short_name": "U", "color": "#1a7d57", "text_color": "#ffffff", "counts_against_allowance": true, "requires_approval": true, "requires_certificate": false, "half_days_allowed": true, "sensitive": false, "active": true, "sort_order": 10 } }, "Absence": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Employee.", "type": "string", "format": "uuid" }, "type_id": { "description": "Absence type; null if masked.", "type": [ "string", "null" ], "format": "uuid" }, "masked": { "description": "Type hidden (sensitive, scope missing).", "type": "boolean" }, "start_date": { "description": "First day.", "type": "string", "format": "date" }, "end_date": { "description": "Last day.", "type": "string", "format": "date" }, "start_day_part": { "description": "First day full or half.", "type": "string", "enum": [ "full", "morning", "afternoon" ] }, "end_day_part": { "description": "Last day full or half.", "type": "string", "enum": [ "full", "morning", "afternoon" ] }, "working_days": { "description": "Working days the absence takes.", "type": "number" }, "status": { "description": "Request status.", "type": "string", "enum": [ "requested", "partially_approved", "approved", "rejected", "cancellation_requested", "cancelled" ] }, "created_at": { "description": "Created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last changed.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "type_id", "masked", "start_date", "end_date", "start_day_part", "end_day_part", "working_days", "status", "created_at", "updated_at" ], "example": { "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "type_id": "b7d1e2f3-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "masked": false, "start_date": "2026-08-03", "end_date": "2026-08-14", "start_day_part": "full", "end_day_part": "full", "working_days": 10, "status": "approved", "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "LeaveBalance": { "type": "object", "properties": { "employee_id": { "description": "Employee.", "type": "string", "format": "uuid" }, "year": { "description": "Year.", "type": "integer" }, "entitlement": { "description": "Entitlement in days (incl. carry-over).", "type": [ "number", "null" ] }, "approved": { "description": "Approved.", "type": [ "number", "null" ] }, "requested": { "description": "Requested, pending.", "type": [ "number", "null" ] }, "remaining": { "description": "Remaining.", "type": [ "number", "null" ] }, "carry_over": { "description": "Carry-over from last year.", "type": [ "number", "null" ] }, "carry_over_remaining": { "description": "Of which still open.", "type": [ "number", "null" ] }, "carry_over_expires_on": { "description": "Carry-over expires on.", "type": [ "string", "null" ], "format": "date" }, "expiring": { "description": "About to expire.", "type": [ "number", "null" ] }, "expired": { "description": "Expired.", "type": [ "number", "null" ] }, "paid_out": { "description": "Paid out.", "type": [ "number", "null" ] } }, "required": [ "employee_id", "year", "entitlement", "approved", "requested", "remaining", "carry_over", "carry_over_remaining", "carry_over_expires_on", "expiring", "expired", "paid_out" ], "example": { "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "year": 2026, "entitlement": 30, "approved": 18, "requested": 2, "remaining": 10, "carry_over": 3, "carry_over_remaining": 0, "carry_over_expires_on": "2026-03-31", "expiring": 0, "expired": 0, "paid_out": 0 } }, "Holiday": { "type": "object", "properties": { "date": { "description": "Day.", "type": "string", "format": "date" }, "name": { "description": "Name.", "type": "string" }, "kind": { "description": "Public or set by the company.", "type": "string", "enum": [ "public_holiday", "company_day_off" ] }, "region": { "description": "Region.", "type": [ "string", "null" ] }, "unit_id": { "description": "Only for this unit (days off).", "type": [ "string", "null" ], "format": "uuid" }, "value": { "description": "1 full, 0.5 half day.", "type": "number" }, "deducted_from_leave": { "description": "Deducted from leave.", "type": "boolean" } }, "required": [ "date", "name", "kind", "region", "unit_id", "value", "deducted_from_leave" ], "example": { "date": "2026-12-25", "name": "1. Weihnachtstag", "kind": "public_holiday", "region": "NW", "unit_id": null, "value": 1, "deducted_from_leave": false } }, "TimeEntry": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Employee.", "type": "string", "format": "uuid" }, "kind": { "description": "Kind.", "type": "string", "enum": [ "clock_in", "clock_out", "break_start", "break_end" ] }, "timestamp": { "description": "Moment.", "type": "string", "format": "date-time" }, "work_date": { "description": "Work day the entry belongs to.", "type": "string", "format": "date" }, "source": { "description": "Source.", "type": "string", "enum": [ "app", "terminal", "manual", "correction", "import", "automatic", "sample" ] }, "location": { "description": "Location.", "type": [ "string", "null" ], "enum": [ "on_site", "remote", null ] }, "recorded_at": { "description": "Recorded at.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "kind", "timestamp", "work_date", "source", "location", "recorded_at" ], "example": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "kind": "clock_in", "timestamp": "2026-10-19T06:58:00Z", "work_date": "2026-10-19", "source": "app", "location": "on_site", "recorded_at": "2026-10-19T06:58:02Z" } }, "TimesheetDay": { "type": "object", "properties": { "employee_id": { "description": "Employee.", "type": "string", "format": "uuid" }, "date": { "description": "Day.", "type": "string", "format": "date" }, "recorded": { "description": "There are entries.", "type": "boolean" }, "start": { "description": "Start.", "type": [ "string", "null" ], "format": "date-time" }, "end": { "description": "End.", "type": [ "string", "null" ], "format": "date-time" }, "work_minutes": { "description": "Work.", "type": [ "integer", "null" ] }, "break_minutes": { "description": "Break.", "type": [ "integer", "null" ] }, "deducted_break_minutes": { "description": "Break deducted by the break rule.", "type": [ "integer", "null" ] }, "target_minutes": { "description": "Target.", "type": [ "integer", "null" ] }, "credit_minutes": { "description": "Credit (leave, sickness, holiday).", "type": [ "integer", "null" ] }, "balance_minutes": { "description": "Balance of the day. Empty while the day is still running, or if the company keeps open days separate and the clock-out is missing (`open`).", "type": [ "integer", "null" ] }, "open": { "description": "Incomplete (e.g. clock-out missing).", "type": [ "boolean", "null" ] }, "running": { "description": "Running right now.", "type": [ "boolean", "null" ] }, "violations": { "description": "Working time act notices (codes).", "type": "array", "items": { "type": "string" } }, "absent": { "description": "Absent that day (without type).", "type": "boolean" } }, "required": [ "employee_id", "date", "recorded", "start", "end", "work_minutes", "break_minutes", "deducted_break_minutes", "target_minutes", "credit_minutes", "balance_minutes", "open", "running", "violations", "absent" ], "example": { "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "date": "2026-10-19", "recorded": true, "start": "2026-10-19T06:58:00Z", "end": "2026-10-19T15:31:00Z", "work_minutes": 483, "break_minutes": 30, "deducted_break_minutes": 0, "target_minutes": 480, "credit_minutes": 0, "balance_minutes": 3, "open": false, "running": false, "violations": [], "absent": false } }, "Project": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "number": { "description": "Project number.", "type": [ "string", "null" ] }, "title": { "description": "Title.", "type": "string" }, "link": { "description": "Link.", "type": [ "string", "null" ] }, "contact_employee_id": { "description": "Contact person.", "type": [ "string", "null" ], "format": "uuid" }, "active": { "description": "Active.", "type": "boolean" }, "created_at": { "description": "Created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last changed.", "type": "string", "format": "date-time" } }, "required": [ "id", "number", "title", "link", "contact_employee_id", "active", "created_at", "updated_at" ], "example": { "id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "number": "P-2026-014", "title": "Dachstuhl Hauptstraße", "link": null, "contact_employee_id": null, "active": true, "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "ProjectTime": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Employee.", "type": "string", "format": "uuid" }, "date": { "description": "Day.", "type": "string", "format": "date" }, "project_id": { "description": "Project; null for free text.", "type": [ "string", "null" ], "format": "uuid" }, "text": { "description": "Free text instead of a project.", "type": [ "string", "null" ] }, "minutes": { "description": "Minutes.", "type": "integer" }, "note": { "description": "Note.", "type": [ "string", "null" ] }, "recorded_at": { "description": "Recorded at.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last changed.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "date", "project_id", "text", "minutes", "note", "recorded_at", "updated_at" ], "example": { "id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "date": "2026-10-19", "project_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "text": null, "minutes": 240, "note": null, "recorded_at": "2026-10-19T15:40:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "ShiftType": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "unit_id": { "description": "Unit.", "type": [ "string", "null" ], "format": "uuid" }, "name": { "description": "Name.", "type": "string" }, "short_name": { "description": "Short name.", "type": "string" }, "color": { "description": "Colour (#rrggbb).", "type": "string" }, "start_time": { "description": "Start (local time).", "type": [ "string", "null" ], "format": "time" }, "end_time": { "description": "End (local time).", "type": [ "string", "null" ], "format": "time" }, "break_minutes": { "description": "Break.", "type": "integer" }, "kind": { "description": "Kind.", "type": "string", "enum": [ "shift", "on_call_duty", "standby", "training", "appointment" ] }, "active": { "description": "Active.", "type": "boolean" }, "sort_order": { "description": "Sort order.", "type": [ "integer", "null" ] } }, "required": [ "id", "unit_id", "name", "short_name", "color", "start_time", "end_time", "break_minutes", "kind", "active", "sort_order" ], "example": { "id": "f7a8b9c0-d1e2-4f3a-9b4c-5d6e7f8a9b0c", "unit_id": "8c0e4f7a-2d1b-4c3e-9a55-6f7e8d9c0b1a", "name": "Frühdienst", "short_name": "F", "color": "#2563eb", "start_time": "06:00:00", "end_time": "14:00:00", "break_minutes": 30, "kind": "shift", "active": true, "sort_order": 10 } }, "Shift": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Employee; null for an open shift.", "type": [ "string", "null" ], "format": "uuid" }, "unit_id": { "description": "Unit.", "type": "string", "format": "uuid" }, "shift_type_id": { "description": "Shift type.", "type": [ "string", "null" ], "format": "uuid" }, "date": { "description": "Day.", "type": "string", "format": "date" }, "start": { "description": "Start.", "type": "string", "format": "date-time" }, "end": { "description": "End.", "type": "string", "format": "date-time" }, "break_minutes": { "description": "Break.", "type": "integer" }, "status": { "description": "Status.", "type": "string", "enum": [ "published", "dropped", "cancelled" ] }, "dropped_reason": { "description": "Reason for a dropped shift; “sickness” only with absences:read_sensitive, else “absence”.", "type": [ "string", "null" ], "enum": [ "leave", "sickness", "absence", "company", null ] }, "published_at": { "description": "Published at.", "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "description": "Last changed.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "unit_id", "shift_type_id", "date", "start", "end", "break_minutes", "status", "dropped_reason", "published_at", "updated_at" ], "example": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "unit_id": "8c0e4f7a-2d1b-4c3e-9a55-6f7e8d9c0b1a", "shift_type_id": "f7a8b9c0-d1e2-4f3a-9b4c-5d6e7f8a9b0c", "date": "2026-10-20", "start": "2026-10-20T04:00:00Z", "end": "2026-10-20T12:00:00Z", "break_minutes": 30, "status": "published", "dropped_reason": null, "published_at": "2026-10-01T09:00:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "Vehicle": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "license_plate": { "description": "License plate.", "type": "string" }, "name": { "description": "Name.", "type": [ "string", "null" ] }, "kind": { "description": "Company vehicle or an employee’s own car.", "type": "string", "enum": [ "company", "private" ] }, "usage": { "description": "Pool vehicle or assigned car; null for an own car.", "type": [ "string", "null" ], "enum": [ "pool", "assigned", null ] }, "private_use": { "description": "Private trips allowed.", "type": "boolean" }, "drive": { "description": "Drive.", "type": "string", "enum": [ "combustion", "hybrid", "electric" ] }, "list_price": { "description": "Gross list price in euros.", "type": [ "number", "null" ] }, "first_registration": { "description": "First registration.", "type": [ "string", "null" ], "format": "date" }, "start_odometer": { "description": "Odometer at the start of the logbook.", "type": "integer" }, "logbook_from": { "description": "Logbook from.", "type": "string", "format": "date" }, "inspection_due": { "description": "Vehicle inspection due.", "type": [ "string", "null" ], "format": "date" }, "safety_check_due": { "description": "Safety check due.", "type": [ "string", "null" ], "format": "date" }, "owner_employee_id": { "description": "Owner for an own car.", "type": [ "string", "null" ], "format": "uuid" }, "unit_id": { "description": "Location unit.", "type": [ "string", "null" ], "format": "uuid" }, "retired_on": { "description": "Retired from.", "type": [ "string", "null" ], "format": "date" }, "created_at": { "description": "Created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last changed.", "type": "string", "format": "date-time" } }, "required": [ "id", "license_plate", "name", "kind", "usage", "private_use", "drive", "list_price", "first_registration", "start_odometer", "logbook_from", "inspection_due", "safety_check_due", "owner_employee_id", "unit_id", "retired_on", "created_at", "updated_at" ], "example": { "id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "license_plate": "D-AB 123", "name": "Caddy", "kind": "company", "usage": "pool", "private_use": false, "drive": "combustion", "list_price": 38500, "first_registration": "2024-03-01", "start_odometer": 12500, "logbook_from": "2026-11-01", "inspection_due": "2027-05-31", "safety_check_due": null, "owner_employee_id": null, "unit_id": null, "retired_on": null, "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "Trip": { "type": "object", "properties": { "id": { "description": "Trip id (the same across all versions).", "type": "string", "format": "uuid" }, "version": { "description": "Version; every change is a new one.", "type": "integer" }, "journey_id": { "description": "Journey: parts of a mixed trip share it.", "type": "string", "format": "uuid" }, "split_from_id": { "description": "Split off from this trip.", "type": [ "string", "null" ], "format": "uuid" }, "vehicle_id": { "description": "Vehicle.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Driver.", "type": "string", "format": "uuid" }, "category": { "description": "Business, private or commute.", "type": "string", "enum": [ "business", "private", "commute" ] }, "date": { "description": "Day (local time).", "type": "string", "format": "date" }, "start": { "description": "Start; null for private trips and commutes.", "type": [ "string", "null" ], "format": "date-time" }, "end": { "description": "End; null while running and for private trips and commutes.", "type": [ "string", "null" ], "format": "date-time" }, "odometer_start": { "description": "Odometer at the start.", "type": [ "integer", "null" ] }, "odometer_end": { "description": "Odometer at the end.", "type": [ "integer", "null" ] }, "distance_km": { "description": "Kilometres driven.", "type": [ "integer", "null" ] }, "origin": { "description": "Origin; protected partners as “Nr. 17”.", "type": [ "string", "null" ] }, "destination": { "description": "Destination; protected partners as “Nr. 17”.", "type": [ "string", "null" ] }, "purpose": { "description": "Purpose.", "type": [ "string", "null" ] }, "business_partner": { "description": "Business partner visited; protected partners as “Nr. 17”.", "type": [ "string", "null" ] }, "detour": { "description": "Detour and reason.", "type": [ "string", "null" ] }, "project_id": { "description": "Project.", "type": [ "string", "null" ], "format": "uuid" }, "status": { "description": "Running, open (can still be completed) or closed.", "type": "string", "enum": [ "running", "open", "closed" ] }, "incomplete": { "description": "Details are missing.", "type": "boolean" }, "changed": { "description": "Changed after recording (history in Tiveo).", "type": "boolean" }, "late_entry": { "description": "Added later or recorded after the deadline.", "type": "boolean" }, "recorded_at": { "description": "Recorded at (first version); null for private trips and commutes.", "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "description": "This version recorded at; null for private trips and commutes.", "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "version", "journey_id", "split_from_id", "vehicle_id", "employee_id", "category", "date", "start", "end", "odometer_start", "odometer_end", "distance_km", "origin", "destination", "purpose", "business_partner", "detour", "project_id", "status", "incomplete", "changed", "late_entry", "recorded_at", "updated_at" ], "example": { "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "version": 2, "journey_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "split_from_id": null, "vehicle_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "category": "business", "date": "2026-11-03", "start": "2026-11-03T07:40:00Z", "end": "2026-11-03T08:25:00Z", "odometer_start": 12500, "odometer_end": 12542, "distance_km": 42, "origin": "Werkstatt", "destination": "Kunde Meier, Hauptstraße 1, 40210 Düsseldorf", "purpose": "Wartung Heizung", "business_partner": "Herr Meier", "detour": null, "project_id": null, "status": "closed", "incomplete": false, "changed": false, "late_entry": false, "recorded_at": "2026-11-03T07:40:05Z", "updated_at": "2026-11-03T08:26:10Z" } }, "VehicleCost": { "type": "object", "properties": { "id": { "description": "Id.", "type": "string", "format": "uuid" }, "vehicle_id": { "description": "Vehicle.", "type": "string", "format": "uuid" }, "date": { "description": "Day.", "type": "string", "format": "date" }, "kind": { "description": "Kind.", "type": "string", "enum": [ "fuel", "charging", "workshop", "tyres", "insurance", "tax", "leasing", "financing", "depreciation", "tolls_parking", "cleaning", "other" ] }, "amount_gross": { "description": "Gross amount in euros.", "type": "number" }, "amount_net": { "description": "Net amount in euros.", "type": [ "number", "null" ] }, "quantity": { "description": "Quantity (litres or kWh).", "type": [ "number", "null" ] }, "odometer": { "description": "Odometer.", "type": [ "integer", "null" ] }, "has_receipt": { "description": "A receipt is stored in Tiveo.", "type": "boolean" }, "recorded_at": { "description": "Recorded at.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last changed.", "type": "string", "format": "date-time" } }, "required": [ "id", "vehicle_id", "date", "kind", "amount_gross", "amount_net", "quantity", "odometer", "has_receipt", "recorded_at", "updated_at" ], "example": { "id": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a", "vehicle_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "date": "2026-11-04", "kind": "fuel", "amount_gross": 71.4, "amount_net": 60, "quantity": 38.2, "odometer": 12542, "has_receipt": true, "recorded_at": "2026-11-04T16:02:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "MileageAllowance": { "type": "object", "properties": { "id": { "description": "Id of this approval.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Employee.", "type": "string", "format": "uuid" }, "month": { "description": "Month (the first day).", "type": "string", "format": "date" }, "version": { "description": "Version; a new approval replaces the old one.", "type": "integer" }, "distance_km": { "description": "Kilometres.", "type": "integer" }, "rate": { "description": "Rate per kilometre in euros.", "type": "number" }, "amount": { "description": "Amount in euros.", "type": "number" }, "trip_count": { "description": "Trips.", "type": "integer" }, "approved_at": { "description": "Approved at.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "month", "version", "distance_km", "rate", "amount", "trip_count", "approved_at" ], "example": { "id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "month": "2026-10-01", "version": 1, "distance_km": 420, "rate": 0.3, "amount": 126, "trip_count": 18, "approved_at": "2026-11-02T09:15:00Z" } } } } }