API docs by Redocly

SaaS.de Customer REST API (2.0)

Download OpenAPI specification:

URL: https://www.saas.de

Integration API for the SaaS.de HR and time-management platform: read employees' working-time accounts, presence and leave data, and record clock-in / clock-out bookings.

Base URL

All endpoints live under the /rest context of your SaaS.de instance, e.g. https://desktop.saas.de/rest/api/....

Authentication

Every request is authenticated with an API key passed as a path segment (the {api} parameter) — a company key for company-wide endpoints, or an employee key where noted. Some endpoints additionally accept an employee email in the request body together with the company key. The key is part of the URL: always call over HTTPS and keep it secret.

Conventions

  • Dates are formatted YYYY-MM-DD; timestamps (e.g. the time field) are epoch milliseconds.
  • Time amounts are in minutes unless a field says otherwise.
  • Month numbering is not uniform. POST /api/time/account takes a 1-based month (1 = January); the v2 GET endpoints take a 0-based month (0 = January … 11 = December). Each endpoint states its base.

Rate limiting

The API allows up to 60 requests per minute; exceeding this returns HTTP 429 (Too Many Requests).

Errors

Authentication or authorization failures return HTTP 403 with a text/plain body that is either empty or one of the codes below. Successful responses that carry a code field use the same table (code: 0 = OK). Some endpoints use 400, 401 or 404 instead — see each operation.

Code Meaning
0 OK
1 Employee not found
2 Company inactive
3 Authentication failed (invalid key)
4 Bad date / value could not be resolved
7 E-mail already in use
8 Missing module / license

Time tracking

Working-time accounts, presence and clock bookings.

Get an employee's monthly time account

Returns the working-time account (target/actual/balance) of a single employee for a month, including that month's individual bookings. For the current month the totals are recalculated on each call.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

query Parameters
project
boolean
Default: false

Include the project name on each booking entry.

Request Body schema: application/json
required
email
required
string <email>

E-mail of the employee whose account is requested.

year
integer

Year. Accepts a number or a numeric string. Defaults to the current year.

month
integer [ 1 .. 12 ]

Month, 1-based (1 = January). Accepts a number or a numeric string. Defaults to the current month. A month in the future is rejected with 403 body 4.

Responses

Request samples

Content type
application/json
{
  • "email": "max.mustermann@example.com",
  • "year": 2026,
  • "month": 6
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "time": 1718700000000,
  • "today_soll": 480,
  • "today_ist": 120,
  • "list": [
    ],
  • "account_balance": 120,
  • "account_soll": 9600,
  • "account_ist": 9480,
  • "account_surcharge": 0,
  • "account_saldo": -120,
  • "flexTime": 0,
  • "PAYOFF_TIMEACCOUNT": 0,
  • "TIMEACCOUNT_PAYOFF": 0,
  • "OVERTIMEACCOUNT_TIMEACCOUNT": 0,
  • "TIMEACCOUNT_OVERTIMEACCOUNT": 0
}

Get target/actual minutes per day for a range

Returns the target (soll) and actual (ist) minutes per day for a date range. With an email only that employee is returned; otherwise all time-tracked employees of the company (identified by the company key) are returned.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

Request Body schema: application/json
required
email
string <email>

Restrict the result to this employee. Omit to get the whole company (company key).

start
string

Start date YYYY-MM-DD. Defaults to today. A malformed date is rejected with 403 body 4.

end
string

End date YYYY-MM-DD. Capped at today; start is not validated against end. Defaults to today.

Responses

Request samples

Content type
application/json
{
  • "start": "2026-06-01",
  • "end": "2026-06-03"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "time": 1718700000000,
  • "info": [
    ]
}

Presence / absence overview

Returns a per-employee presence and absence overview for the current day. With an email only that employee is returned; otherwise the set of employees depends on the modules and supervisor scope of the key owner. Detail fields (current booking, platform, device) are only filled for the key owner or their supervisors. Send at least an empty JSON object {}.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

Request Body schema: application/json
required
email
string <email>

Restrict the overview to this employee.

Responses

Request samples

Content type
application/json
{
  • "email": "max.mustermann@example.com"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "time": 1750334400000,
  • "info": [
    ]
}

Presence and absences for a single day

Returns, per employee, whether they are present on the given day and any absences (leave or public holidays) for that day. With an email only that employee is returned; otherwise all time-tracked employees of the company are returned.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

Request Body schema: application/json
required
email
string <email>

Restrict to this employee. Omit for the whole company (company key).

day
string

Day YYYY-MM-DD. Defaults to today. A malformed date is rejected with 403 body 4.

Responses

Request samples

Content type
application/json
{
  • "day": "2026-06-18"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "time": 1718700000000,
  • "info": [
    ]
}

Clock an employee in or out

Records a time booking for a single employee.

  • come — clock in (optionally on a project/service)
  • go — clock out
  • stop — clock out and immediately clock back in (break / context switch)

Returns true on success, false otherwise — e.g. an invalid company key, an unresolvable employee, a come on a project without the project-management module, a plain come without the time-tracking module, or a go/stop that is not currently possible (such as clocking out when not clocked in). The request body is optional.

path Parameters
action
required
string
Enum: "come" "go" "stop"

The booking action.

api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

employee
required
string

The employee's API key or e-mail (tried in that order).

Request Body schema: application/json
optional
device
string

Free-text device label stored with the booking. Defaults to API.

comment
string
project
string

External project id (for a project-based come).

service
string

External service id (for a project-based come).

Responses

Request samples

Content type
application/json
{
  • "device": "Reception terminal",
  • "comment": "Start of shift"
}

Response samples

Content type
application/json
true

Time account of one employee

Returns the working-time account of a single employee for a month.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

employee
required
string

The employee's API key or e-mail (tried in that order).

year
required
integer
Example: 2026
month
required
integer [ 0 .. 11 ]
Example: 5

Month, 0-based (0 = January … 11 = December).

Responses

Response samples

Content type
application/json
{
  • "employee": "string",
  • "year": 0,
  • "month": 0,
  • "hasTime": true,
  • "hasProject": true,
  • "current": "string",
  • "lastMonth": 0,
  • "soll": 0,
  • "ist": 0,
  • "surcharge": 0,
  • "saldo": 0,
  • "saldo2": 0,
  • "onWork": 0,
  • "outOfWork": 0,
  • "istOnWeekend": 0,
  • "isReadOnly": true,
  • "PAYOFF_TIMEACCOUNT": 0,
  • "TIMEACCOUNT_PAYOFF": 0,
  • "OVERTIMEACCOUNT_TIMEACCOUNT": 0,
  • "TIMEACCOUNT_OVERTIMEACCOUNT": 0,
  • "OVERTIMEACCOUNT_PAYOFF": 0,
  • "PAYOFF_OVERTIMEACCOUNT": 0,
  • "unpaidOvertime": 0,
  • "autoOvertime": 0,
  • "overtimeAccountMonth": 0,
  • "overtimeAccount": 0,
  • "today": {
    },
  • "traffic": {
    },
  • "inactive": true,
  • "start": "string",
  • "end": "string",
  • "list": [
    ]
}

Time accounts of a department

Returns the current time account of every employee in a department, keyed by the employee's login account (e-mail). Employees without a login account are omitted.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

department
required
string

Department API key.

Responses

Response samples

Content type
application/json
{
  • "anna.mueller@example.com": {
    }
}

Monthly time summary for a department

Returns one monthly time summary per active employee in the department for the requested month. The array is empty when the month is in the future or no employee qualifies.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

department
required
string

Department external id.

year
required
integer
Example: 2026
month
required
integer [ 0 .. 11 ]
Example: 4

Month, 0-based (0 = January … 11 = December).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Leave management

Absences, holidays and leave overviews.

Pay extra leave in or out

Adjusts an employee's extra-leave balance and records the change in the leave history. A positive value pays leave in, a negative value pays it out.

Returns true on success, false otherwise — e.g. an invalid company key, an unknown account, an employee of another company, a missing leave-management module, or an unknown action. action must be present in the body.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

Request Body schema: application/json
required
account
required
string <email>

E-mail of the employee.

action
required
string
Value: "extraleave"

Only extraleave is currently supported.

value
required
number

Days to add (positive = pay in) or remove (negative = pay out).

year
integer

Leave year. Defaults to the current year.

comment
string

Responses

Request samples

Content type
application/json
{
  • "account": "max.mustermann@example.com",
  • "action": "extraleave",
  • "value": 1.5,
  • "year": 2026,
  • "comment": "Bonus leave"
}

Response samples

Content type
application/json
true

Book an absence

Books an absence (outside the regular leave workflow) for an employee. abscenceReasonUuid and employeeUuid are required. Depending on the absence type a substitute (replacementUuid) may be mandatory.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

Request Body schema: application/json
required
abscenceReasonUuid
required
string

External id of the absence type / reason.

employeeUuid
required
string

External id of the employee to book for.

replacementUuid
string

External id of the substitute (required for some absence types).

duration
integer
Default: 1

0 = half day, 1 = full day. Defaults to 1.

startDay
string

Start date YYYY-MM-DD. Defaults to today.

endDay
string

End date YYYY-MM-DD. Defaults to today.

planned
boolean
Default: false
comment
string

Responses

Request samples

Content type
application/json
{
  • "abscenceReasonUuid": "ext-leave-type-1",
  • "employeeUuid": "ext-emp-42",
  • "duration": 1,
  • "startDay": "2026-06-18",
  • "endDay": "2026-06-20",
  • "planned": false,
  • "comment": "Family event"
}

Response samples

Content type
application/json
"success"

Leave records for a month

Returns the leave records of all leave-managed employees that overlap the given month.

Note: month is 0-based (0 = January … 11 = December).

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

year
required
integer
Example: 2026
month
required
integer [ 0 .. 11 ]
Example: 5

Month, 0-based (0 = January … 11 = December).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Yearly leave overview

Returns a yearly leave overview for all leave-managed employees, plus a legend that resolves each leave-type id to its localized names.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

year
required
integer
Example: 2026

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "legende": {
    }
}

Employees

Employee master data and department assignments.

Employees with their main department

Returns a list of single-entry objects mapping each employee's full name to the name of their main department.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

List all employees

Returns master data for every employee of the company. Employees without a login account are omitted.

path Parameters
api
required
string
Example: c0mp4ny-4p1-k3y

The API key — a company key for company-wide endpoints, or an employee key where noted. Keep it secret and send it over HTTPS only.

Responses

Response samples

Content type
application/json
[
  • {
    }
]